Star Crusher

Star Crusher is an educational arcade collection about two young space travelers flying between dungeon planets. The current encounters include a Time Pilot-style Math Invaders game where drifting numbered targets display possible answers to grade-level math questions, Math Pong, and Reading Snake, a Snake-inspired mini game where players collect letters in order to spell words.

On mobile, the home screen is the Star Academy hub: a portrait-native landing page with a grade badge, 10-pip star meter, and five quick-tap games grouped by subject — four math games (Meteor Catch, Number Rain, Plasma Breaker, Frog Lane) and one reading game (Reading Snake). Stars earned in each game advance the player toward the next grade and persist between sessions.

Current build: 1.11.0

Latest Mobile Release

• Version 1.11.0 upper-grade Frog Lane depth: Three new Frog Lane rendering modes so 2nd–5th grade math plays like the skill it teaches instead of falling back to plain counting. SkipCount walks an arithmetic sequence — each crossing adds the lesson's step (3, 6, 9… for multiplication tables, 10, 20, 30… for place value), with the full sequence previewed under the header dots and the target value on the goal beacon. Fractions fills an on-screen fraction bar one segment per crossing (1/5, 2/5… up to one whole). Decimals counts by tenths (0.2, 0.4… to 1.0, also used for money/percent lessons). The lesson generator now maps fraction/decimal/multiplication/division/place-value/addition lessons onto these modes — extracting explicit steps like "count by 5s" from lesson titles — and bakes the sequence into each lesson's instruction and success text. 34 of the 72 generated math lessons now use the new modes; PreK's hand-tuned lessons are unchanged. Two new tests lock in sequence-data validity and upper-grade concept coverage (63 total).
• Version 1.10.1 corpus cleanup + richer 1st–5th vocabulary: The D:/lesson-plans corpus was repaired at the source (2,170 broken JSON files fixed — BOMs, truncation, stray braces) and vocabulary-builder supplemental files were generated for all 72 ELA lessons in grades 1–5 with inferred parts of speech. Regenerated lesson_plans_gen.rs from the cleaned corpus: 3rd and 4th grade each recovered a previously unreadable literacy lesson (now 12/12), and 2nd–5th grade Reading Snake words now come from the richer vocabulary builders instead of bare lesson vocab. Also added a weekly dependency-watch CI workflow (scheduled cargo-audit + an upstream canary that flags when the macroquad --allow-undefined workaround can be dropped — verified still required as of macroquad 0.4.15 / Rust 1.96).
• Version 1.10.0 grade-level content + grade-up ceremony: Every grade now gets its own lesson content instead of preschool material. A new code generator (tools/generate-lesson-plans-rs.mjs) compiles K–5 Mathematics and English-Language-Arts lessons from the D:/lesson-plans corpus into src/lesson_plans_gen.rs (72 math + 73 literacy lessons total), with vocabulary enriched from the additional-materials vocabulary builders where available and a repair pass for the corpus's malformed JSON (BOMs, truncated files, stray braces). Frog Lane and Reading Snake automatically serve the active grade's lessons via the now grade-aware *_for_grade() accessors; Pre-K stays hand-tuned. Filling the 10-star meter now triggers the long-promised Grade-Up ceremony — a celebration screen offering "Advance to " or "Stay" (never forced); advancing resets the old grade's meter and persists the new grade. Three new tests lock in per-grade coverage (every grade ≥8 math + ≥8 literacy lessons, ≥10 playable vocab words, and distinct content per grade).
• Version 1.9.8 build/CI repair for Rust 1.96: Restored the GitHub Pages WASM build, which had failed on every push since Rust 1.96 removed the implicit --allow-undefined wasm linker flag. The JS-bridge extern "C" blocks now declare #[link(wasm_import_module = "env")], a new .cargo/config.toml restores --allow-undefined for macroquad/miniquad's own JS imports until upstream adds import modules, and a new rust-toolchain.toml pins Rust 1.95.0 (+ wasm target) so CI and local builds match. CI now installs the pinned toolchain and all GitHub Actions pins were refreshed to Node 24-ready releases ahead of the June 16, 2026 forcing date. Verified on both Rust 1.95.0 and 1.96.0; no gameplay changes.
• Version 1.9.7 Reading Snake part-of-speech label: The academy Reading Snake question card now shows the word's real part of speech (noun, verb, adjective, …) instead of the placeholder "Lesson Term". Added a part_of_speech field to VocabEntry in lesson_plans.rs, populated it for every lesson term, and wired it through literacy_vocab_for_grade to the card.
• Version 1.9.6 Number Rain tap wording: Number Rain now generates its own prompt wording so the touch instruction reads correctly — the shared "Shoot number three" prompt is reworded to "Tap number three" for Number Rain only. Math Invaders and other games keep the shared "Shoot" wording (they actually shoot). Change is contained entirely in number_rain.rs.
• Version 1.9.5 warning cleanup: Cleared all 10 pre-existing dead-code compiler warnings — the build is now warning-clean. Removed genuinely dead items (HEADER_BOTTOM, Block::center, is_academy_mode), gated test-only helpers behind #[cfg(test)] (lives_remaining in Meteor Catch/Number Rain, clear_stars_for_current_grade), and annotated intentional bridge/API/data (return_to_landing JS bridge, academy_grade_label, LessonPlan grade/subject metadata) with #[allow(dead_code)]. No runtime behavior change.
• Version 1.9.4 Frog Lane road spacing variation: Road traffic now spawns with random spacing variation at every grade so the pattern isn't perfectly rhythmic; river logs keep their even spacing for predictable landing. Hazard count and speed are unchanged, so overall difficulty stays the same — only the road rhythm varies.
• Version 1.9.3 Frog Lane difficulty rebalance: Simplified the hazard patterns for the PreK–6th target. Each lane now has a single travel direction and one consistent speed (no more bidirectional traffic or random per-hazard speeds), hazards are evenly spaced, and road-traffic density scales gradually with grade (2 cars at the lowest grades up to 4 at the highest) while river logs stay generous so crossing is always fair. Speed is unchanged.
• Version 1.9.2 Frog Lane mobile pacing: Lowered the mobile speed scale to 0.05 — Frog Lane was still far too fast on touch devices at 0.5. Desktop speed is unchanged.
• Version 1.9.1 Reading Snake mobile touch fix: Touch/swipe steering now works during Reading Snake gameplay on phones. Gameplay touches were being mapped with the CSS-pixel transform instead of the DPI-aware touch_to_virtual_position, so on high-DPI screens every touch landed outside the board and the snake never turned. Tap-to-steer (relative to the snake head, the same pattern Frog Lane uses) is also re-enabled on portrait. Desktop input is unchanged.
• Version 1.9.1 Frog Lane mobile pacing: Frog Lane now runs at half speed on touch/portrait devices so PreK–6th players can keep up; desktop speed is unchanged.
• Version 1.9.1 audit: Verified against the 12-state iPhone-portrait CDP audit (393×852 @3x) — all captures clean, both changed games render correctly, no visual regressions to the GW theme or other games.
• Version 1.9.0 GW blue & gold theme: Replaced the per-game color schemes with a single shared GW palette (src/theme.rs) — deep navy / royal-blue backgrounds with gold accents — applied consistently across the hub, Meteor Catch, Number Rain, and Plasma Breaker. Correct/wrong feedback stays green/crimson as gameplay signals.
• Version 1.9.0 Meteor Catch prompt: Question now reads "Catch number [Word]" (e.g. "Catch number Two") and auto-fits so it never wraps on phone screens; the player still catches the meteor showing the matching numeral.
• Version 1.9.0 Meteor Catch difficulty: Narrowed the catch paddle (140px → 104px) for a fairer-but-tougher catch, and made the per-wave drop count random within a grade-scaled range (Preschool 3-4 up to 5th grade 6-8) instead of a fixed 4.
• Version 1.9.0 Plasma Breaker question card: Removed the hearts/lives row from the Plasma Breaker question banner (same cleanup applied earlier to Meteor Catch and Number Rain); lives logic is unchanged.
• Version 1.8.0 question card cleanup: Removed the hearts/lives row from the Meteor Catch and Number Rain question banners — the question card now shows the question text and score only. Lives still drive win/loss logic; the heart row simply no longer crowds the prompt.
• Version 1.8.0 Meteor Catch word matching: Meteor Catch now shows a written number word ("three", "five") as the prompt and the player catches the meteor showing the matching numeral, reinforcing number-word recognition for early grades. Distractor meteors and the grade-scaled count range are unchanged.
• Version 1.8.0 hub two new games: The Star Academy hub now lists five games across Math and Reading sections — adding Frog Lane (hop across lanes counting crossings) and Reading Snake to the original three, filling the previously empty lower half of the hub. AcademyGame and PlayerProgress gained the two new game columns while preserving existing saved stars.
• Version 1.8.0 hash routing on WASM: #adventure and #mission URL hashes now route to the adventure intro and mission select on the WASM build via the shared StartupRoute, matching native behavior, instead of always landing on the hub.
• Version 1.8.0 grade picker tap fix: Enlarged the hub "Change Grade" tap target and made the grade badge pill itself open the picker, so grade selection registers reliably on touch.
• Version 1.7.5 Meteor Catch shield tuning: Shrunk the catch shield from 200px to 140px so meteors require real aiming on the 720px portrait canvas without becoming unfair for K-5 players.
• Version 1.7.4 Touch DPI fix: Normalized touch positions by screen_dpi_scale() before mapping to the virtual camera, fixing silently-broken canvas taps on every high-DPI mobile display — touches were landing off the right edge of the 720x1280 virtual canvas, so hub cards, HOME buttons, and Star Academy game taps never registered. Mouse paths were unaffected (already CSS-pixel correct).
• Version 1.7.3 Plasma Breaker: Added the third Star Academy game — a Breakout-style math round where players drag a paddle to bounce a plasma ball into the block whose value matches the question. 5x3 block grid, grade-scaled ball speed, three lives, star award persists to the hub.
• Version 1.7.2 Number Rain: Added the second Star Academy game — tap the falling number that matches the current math question before it lands. Waves of four drops, three lives, grade-scaled fall speed, star award persists to the hub.
• Version 1.7.1 Meteor Catch: Added the first Star Academy game — drag a shield horizontally to catch the meteor whose value matches the current math question. Waves of four meteors, three lives, star award persists to the hub.
• Version 1.7.0 Star Academy hub: New mobile home screen that auto-launches on page load — grade badge with picker overlay, 10-pip star meter for grade advancement, three game cards (Meteor Catch, Number Rain, Plasma Breaker), best-rating dots per game, and PlayerProgress persisted to localStorage via a JS bridge. Replaces the legacy mobile flow.
• Version 1.6.3 overlay architecture cleanup: HTML overlay controls now use typed Rust payloads and startup routing now flows through a small StartupRoute abstraction instead of raw platform mode codes.
• Version 1.6.2 HTML overlay controls: Mobile web buttons now render as real HTML controls layered over the canvas, giving iPhone Safari first-class tap handling for HOME, mission/menu choices, CONTINUE, START, PLAY, and NIGHT.
• Version 1.6.2 mobile shell sizing: Landing and game shell sizing now use dynamic viewport units for better iPhone Safari behavior as browser chrome changes.
• Version 1.6.1 Reading intro polish: Reading Planet and Night Planet intro cards now show the hidden word, part of speech, and definition as one clean prompt, with the yellow START action above the helper text and a matching mobile tap target.
• Version 1.6.0 UI pass: Unified the Star Crusher arcade aesthetic across the title flow, Launch Voyage intro, Math Invaders, Math Orbit, Reading Planet, Night Planet, and Word Cargo.
• Math Invaders shape-count enemies: Preschool count prompts now ask clean How many ...? questions while the requested objects appear as the enemy wave; the player shoots the correctly numbered shape target.
• All-grade Math Invaders targets: Numbered targets across Preschool through 5th Grade use the larger target footprint and the same yellow answer-number color as the question card.
• Math Invaders mobile spacing: Active gameplay hides the old title chip, moves stat pills below the ship, opens the playfield, and keeps the player separated from the footer HUD.
• Reading/Night mobile layout: Score, lives, and next-letter pills sit below the word card; definition and board areas expand into the reclaimed vertical space.
• Portrait-native canvas (720×1280): Mobile uses a dedicated portrait virtual screen that fills the phone viewport with uniform scaling—no letterboxing or vertical font stretch.
• Split mobile shell: Active portrait gameplay hides the desktop/site exit chrome, removing the old in-canvas X and mobile HOME controls from the phone play surface.
• iPhone UI polish: Larger title rows, bigger helper copy, portrait question cards, adventure intro copy, gate prompts, game-over panels, and Reading Snake HUD/footer text fit inside their panels without clipping.
• Clickable touch targets: Mobile title rows, mission rows, START, CONTINUE, PLAY, and NIGHT button hitboxes are aligned with their visible button bounds.
• Tap-to-select menus: Title and Mission Select use first-tap to highlight, second-tap to launch.
• Reading Snake: Retuned definition cards, stat chips, and board layout for the portrait canvas; tap/swipe steering on the board.
• Math Invaders: Expanded portrait question card, lowered HUD/stat pills, larger/lower player ship, and enemies that step closer after each kill.
• Math Orbit: Portrait HUD with question below numbered targets, centered stat pills, paddle above START, and hearts/circles/X's question prompts.
• Font fitting: Mobile gameplay text shrinks to the available panel width instead of relying on one large global text multiplier.
• build-wasm.ps1: Root build script verifies WASM freshness, copies artifacts, and writes sanitized star-crusher.wasm.buildinfo.json (relative paths only).
• Rebuilt checked-in star-crusher.wasm for the static site with cache-busting query string in index.html.

Previous Mobile Improvements

• Fixed portrait touch mapping by converting screen coordinates through the virtual camera in screen.rs, so paddle and ship controls align with finger position on iPhone Safari.
• Earlier builds moved the web exit control out of in-canvas headers; the current mobile game shell hides that control during active portrait play while desktop keeps Back to Home.
• Math Invaders portrait HUD leads with the active question card at the top; score, wave, and lives sit in stat pills.
• Math Invaders portrait gameplay scales the player ship and numbered targets for easier reading on phone screens.
• Math Pong portrait HUD moves the question card below numbered targets, with Q, Lives, and Score stat pills and footer hints above the paddle.
• Reading Snake portrait mode removes the thumb D-pad; tap or swipe on the board to steer toward the next letter.
• Added a web touch bridge so mobile Safari taps on canvas buttons trigger the matching game controls.
• Desktop virtual playfield remains 1280×720 (16:9); portrait mobile uses 720×1280.
• Arcade movement is frame-rate independent, preserving the original 60fps feel if browser rendering slows down.

Features

• Seven-grade progression from Preschool through 5th Grade.
• Grade-appropriate math questions covering counting, arithmetic, multiplication, division, fractions, percentages, pre-algebra, area, volume, and ratios.
• Launch Voyage opens a guided planet route: intro, first Math Invaders wave, Reading Snake, Math Pong, Nightmare Snake, then continued Math Invaders progression.
• Math Invaders waves with Time Pilot-style drifting numbered targets tied to the active math question.
• Math Invaders shows the active question in a top-centered banner on portrait mobile, with wave, score, and lives in readable stat pills.
• Math Invaders scales the player ship and numbered targets on portrait mobile for clearer phone play.
• Preschool shape prompts spawn visual shape targets in Math Invaders while keeping the question card clean.
• Kindergarten number-recognition prompts use words, such as Shoot number three, while targets remain numeric.
• Question gates between waves that require typed answers to advance.
• Question gate prompts and answer input are spaced to avoid overlapping the wave-complete instructions.
• Question gates use larger portrait-mode number pad targets for phone play.
• Math Pong mode for launching a straight ball into randomly placed numbered targets.
• Reading Snake mini game for letter order, word recognition, and definition practice, with randomized default or custom spelling lists and Nightmare mode.
• Reading Snake shows definition cards, keeps the active definition visible above the board, and keeps new letter tiles away from the snake head.
• Reading Snake supports portrait tap-or-swipe steering on the board; arrow keys and WASD remain available as fallback controls.
• Reading Snake definition cards show part of speech and use larger definition text for easier reading.
• Completing the standard Reading Snake list starts a bonus Nightmare round using the same words in the same randomized order.
• In Launch Voyage, completing normal Reading Snake advances directly to Math Pong instead of the standalone bonus round.
• Space-travel title menu with two travelers, a ship, dungeon planets, a focused main adventure menu, and a Mission Select submenu.
• Portrait mobile gameplay uses a clean game-only surface; desktop keeps the shell-level Back to Home control.
• Portrait mobile menus use large rounded touch buttons with tap-to-select (first tap highlights, second tap launches).
• Portrait mobile gameplay uses a 720×1280 virtual canvas; desktop uses 1280×720.
• Arcade movement uses frame-time scaling for enemies, ships, bullets, explosions, and Math Orbit ball/paddle motion so desktop and mobile pacing stay consistent across frame rates.
• Game over and victory stat panels are centered with their score and progress text.
• Procedural graphics only; no external assets or fonts required.
• Launches in a 1920x1080 fullscreen window with a fixed 1280x720 virtual playfield, with 16:9 title, gate, overlay, HUD, and mini-game layouts.

Controls

Title menu controls:

• Move menu cursor: Up / Down arrow keys or W / S
• Launch selected option: Enter or Space
• Main menu options: Launch Voyage, Mission Select, and Word Cargo
• Mission Select options: Reading Planet, Math Orbit, and Night Planet
• Return from Mission Select to the main menu: Esc
• Continue Launch Voyage intro: Enter or Space
• Return from Launch Voyage intro to title: Esc
• Return from adventure mini-games to title and cancel the adventure: Esc
• Direct shortcut for Math Invaders: M
• Direct shortcut for Mission Select from the main menu: P
• Direct shortcut for Math Pong from Mission Select: P
• Direct shortcut for Reading Snake: R
• Direct shortcut for Reading Snake Nightmare: N
• Direct shortcut for Word Cargo: L
• On mobile, tap menu rows directly (first tap selects, second tap launches).
• On mobile, use explicit CONTINUE, START, PLAY, and NIGHT buttons for story, restart, and list-entry screens.

Math Invaders controls:

• Move: Left / Right arrow keys or A / D
• Shoot: Space
• Start / continue: Enter or Space
• Return from mini games to title: Esc
• Type gate answers with number keys, then press Enter
• Delete typed answer characters with Backspace
• On mobile, hold or drag in the lower play area to move and fire.
• On mobile, the active question appears in the top banner; wave, score, and lives appear in stat pills below it.
• On mobile, use the visible START / continue actions for gameplay flow; desktop keyboard Esc remains available for returning to title.
• On mobile, use the enlarged gate number pad and OK button to submit answers.

Reading Snake controls:

• Move: arrow keys or W / A / S / D
• Start spelling after a definition card: Enter or Space
• Restart after game over: Enter or Space
• Return to title: Esc
• On mobile, tap or swipe on the board to steer toward the next letter.
• On mobile, tap START on definition cards and game-over screens to continue.
• On mobile, use the visible START actions for definition cards and restart screens; desktop keyboard Esc remains available for returning to title.

Reading Snake layout and safety:

• The definition card shows the part of speech before each word, and the definition remains visible above the playfield.
• The blank word prompt appears below the playfield.
• After each correct letter, the next target and decoy letters avoid a 6-by-6 area around the snake head.

Reading Snake Nightmare rules:

• Start from title: N
• All letter tiles use the same color
• Wrong letters cost one life
• Completing a nightmare word awards one bonus life, up to 9 lives

Spelling-list entry controls:

• Start list entry from title: L
• Type word: definition pairs separated by semicolons, then press Enter
• Press N from list entry to play Nightmare with the typed list
• Plain word lists separated by spaces or commas still work
• Delete typed characters with Backspace
• Leave the list blank and press Enter to use the default words
• Return to title without starting: Esc
• On mobile, tap PLAY to start normal Reading Snake with the typed list.
• On mobile, tap NIGHT to start Nightmare Snake with the typed list.
• On mobile, use the visible PLAY and NIGHT actions to start from the list-entry screen.

Math Pong controls:

• Move paddle: Left / Right arrow keys or A / D
• Launch ball: Space or Enter
• Restart after game over: Enter or Space
• Return to title: Esc
• On mobile, drag or hold in the gameplay band near the lower play area to move the paddle, then tap START to launch the ball.
• On mobile, the question card appears at the top of the screen; wider answer targets and Q, Lives, and Score stat pills sit below it.
• On mobile, use the visible START action to launch and restart Math Orbit.

Requirements

• Rust 2021 toolchain
• Cargo

Install Rust from https://www.rust-lang.org/tools/install if needed.

Run The Game

cargo run

Or use the included launcher:

./run-game

Check Compilation

cargo check

Project Structure

run-game             Convenience launcher that loads rustup environment and runs Cargo
src/main.rs          Game state machine and update/draw loop
src/screen.rs        Window configuration, virtual camera (1280×720 desktop / 720×1280 portrait), and shared touch mapping
src/platform.rs      Optional parent-shell event bridge for embedded web deployments
src/levels.rs        Grade progression and difficulty configuration
src/question.rs      Grade-specific math question generation
src/random.rs        Shared randomization helpers
src/math_pong.rs     Math Pong number target mini game
src/reading_snake.rs Reading Snake mini game
src/theme.rs         Shared GW blue & gold color palette for the Star Academy games and hub
src/hub.rs           Star Academy hub screen + grade picker overlay (mobile home)
src/progress.rs      PlayerProgress data model + localStorage persistence bridge
src/meteor_catch.rs  Star Academy game #1 — catch the meteor whose numeral matches the number word
src/number_rain.rs   Star Academy game #2 — tap the correct falling number
src/plasma_breaker.rs Star Academy game #3 — Breakout-style; break the correct block
src/frog_lane.rs     Star Academy game #4 — hop across lanes, count crossings
src/lesson_plans.rs  Lesson content (math concepts) consumed by Frog Lane
src/enemy.rs         Numbered Math Invaders targets, movement, explosions
src/player.rs        Player ship, player bullets, enemy bullets
src/ui.rs            HUD, title, mobile touch buttons, game over, victory, and question gate UI
src/assets.rs        Procedural drawing helpers for ships, enemies, stars, effects
star-crusher.wasm    Checked-in WASM artifact used by the static landing page
star-crusher.wasm.buildinfo.json  WASM hash, build time, and git SHA (relative paths only)
build-wasm.ps1       Build, copy, verify, and record WASM freshness for local/CI checks
mq_js_bundle.js      Vendored Macroquad/Miniquad browser loader for the WASM build
index.html           Static landing page and local WASM loader bootstrap

Architecture

Single binary crate (star-crusher) on macroquad. main.rs owns the update/draw loop and GameMode state machine; all other logic lives in flat src/ modules.

Module dependencies

flowchart TB
    subgraph runtime["Runtime"]
        mq["macroquad"]
    end

    subgraph core["Core loop"]
        mainRs["main.rs"]
        screenRs["screen.rs"]
    end

    subgraph shared["Shared services"]
        levelsRs["levels.rs"]
        questionRs["question.rs"]
        randomRs["random.rs"]
        assetsRs["assets.rs"]
        uiRs["ui.rs"]
    end

    subgraph mathInvaders["Math Invaders"]
        playerRs["player.rs"]
        enemyRs["enemy.rs"]
    end

    subgraph miniGames["Mini-games"]
        mathPongRs["math_pong.rs"]
        readingSnakeRs["reading_snake.rs"]
    end

    mq --> mainRs
    mainRs --> screenRs
    mainRs --> uiRs
    mainRs --> levelsRs
    mainRs --> playerRs
    mainRs --> enemyRs
    mainRs --> mathPongRs
    mainRs --> readingSnakeRs

    levelsRs --> questionRs
    levelsRs --> enemyRs
    questionRs --> randomRs
    enemyRs --> questionRs
    enemyRs --> assetsRs
    enemyRs --> randomRs
    playerRs --> assetsRs
    mathPongRs --> questionRs
    mathPongRs --> levelsRs
    mathPongRs --> randomRs
    readingSnakeRs --> randomRs
    uiRs --> assetsRs
    uiRs --> levelsRs

Loading

Game modes and Launch Voyage flow

stateDiagram-v2
    [*] --> Title

    Title --> AdventureIntro: Launch Voyage
    Title --> Playing: Math Invaders
    Title --> ReadingSnake: Reading Snake
    Title --> MathPong: Math Pong
    Title --> SpellingList: Custom list

    AdventureIntro --> Playing: Begin wave 1

    Playing --> ReadingSnake: Wave cleared
    ReadingSnake --> MathPong: List complete
    MathPong --> ReadingSnake: Pong complete
    ReadingSnake --> Playing: Nightmare done

    Playing --> GateIntro: Wave complete
    GateIntro --> GateQuestion
    GateQuestion --> Playing: Correct gate answer
    GateQuestion --> GameOver: Wrong or no lives

    Playing --> GameOver: Lives exhausted
    Playing --> Victory: 5th grade complete

    GameOver --> Title
    Victory --> Title
    ReadingSnake --> Title: Esc
    MathPong --> Title: Esc
    SpellingList --> Title: Esc

Loading

Build and deploy

flowchart LR
    srcDir["src modules"]
    cargo["cargo build"]
    native["Native binary"]
    wasm["wasm32 release"]
    dist["dist + index.html"]
    gha["pages.yml"]
    pages["GitHub Pages + www.boohw.com"]

    srcDir --> cargo
    cargo --> native
    cargo --> wasm
    wasm --> dist
    dist --> gha
    gha --> pages

Loading

Gameplay Loop

Math Invaders:

1. Choose Launch Voyage to see the space-route intro, then press Enter or Space through the final prompt to begin.
2. Clear the first Math Invaders wave to enter normal Reading Snake automatically.
3. Complete normal Reading Snake to enter Math Pong automatically.
4. Complete Math Pong to enter Nightmare Snake automatically.
5. Complete Nightmare Snake to return to Math Invaders progression and answer the wave-complete gate.
6. Choose Math Invaders from the title menu, or press M, to launch standalone Math Invaders immediately.
7. Read the active math question in the top banner on portrait mobile and find the drifting target showing the correct answer.
8. On portrait mobile, wave, score, and lives stay visible in stat pills below the banner.
9. Shoot the correct drifting number to score and receive a new question for the remaining targets.
10. Shooting an incorrect number costs one life and leaves that target in play.
11. Clear all numbered targets, then answer typed math questions at the wave-complete gate.
12. Advance through each grade until the 5th Grade wave is completed.

Math Pong:

1. Choose Mission Select, then choose Math Orbit, or press P from Mission Select.
2. Read the math question in the top banner on portrait mobile and identify the correct widened numbered target.
3. Move the paddle under the correct number before launching the ball.
4. Launch straight upward into the correct number to clear the question.
5. Clear five questions to advance to the next grade.

Reading Snake:

1. Choose Mission Select, then choose Reading Planet, or press R, to play with the default word list.
2. Or choose Word Cargo, type weekly spelling words with definitions, then press Enter.
3. Use the format apple: a fruit; moon: shines at night for custom definitions.
4. Read the definition card, then press Enter or Space to start spelling.
5. Use the visible definition above the board and follow the blank word prompt below the board.
6. Steer the snake into the next correct letter; on portrait mobile, tap or swipe on the board to choose direction.
7. Avoid wrong letters, walls, and the snake's own tail.
8. New letters appear away from the snake head so the player has room to react.
9. Complete every word in the randomized list to unlock a bonus Nightmare pass through those same words in the same order.

Reading Snake Nightmare:

1. Choose Mission Select, then choose Night Planet, or press N.
2. Or choose Word Cargo, type a custom spelling list, then press N.
3. Read the definition card and spell the hidden word.
4. Choose carefully because all letter tiles look the same.
5. Complete the word to earn a bonus life.

Development Notes

• This is a binary Rust project, so Cargo.lock is intentionally committed.
• Build output in target/ is ignored.
• The game uses macroquad for windowing, input, and drawing, and rand for question/enemy randomization.
• CI runs cargo audit before each Pages deploy. Local check: cargo audit --ignore RUSTSEC-2025-0035.
• The static web shell uses a restrictive Content Security Policy in index.html; wasm-unsafe-eval and inline script/style allowances are required for the Macroquad WASM loader.
• Custom spelling input is capped at 64 words, 12 characters per word, and 180 characters per definition.

Web Deployment (GitHub Pages)

This project builds to WASM and deploys automatically from the main branch via GitHub Actions to GitHub Pages and the custom domain www.boohw.com.

How It Works

1. Pushing to main triggers .github/workflows/pages.yml.
2. The action installs Rust, compiles the WASM target, and stages index.html, CNAME, and star-crusher.wasm in dist/.
3. actions/deploy-pages publishes the dist/ artifact to GitHub Pages.
4. GitHub Pages serves the same build at www.boohw.com when the custom domain is configured.

Custom Domain (www.boohw.com)

The repository includes a CNAME file for www.boohw.com. To complete or verify setup:

1. Go to Settings -> Pages on this repo and add www.boohw.com as a custom domain.
2. Add these DNS records at your registrar for boohw.com:

Type	Name	Value
CNAME	www	nontechit.github.io
A	@	185.199.108.153
A	@	185.199.109.153
A	@	185.199.110.153
A	@	185.199.111.153

3. After DNS propagates (up to 48 hours), enable Enforce HTTPS in Pages settings.

Local WASM Build

Use the project build script (recommended — unsets sandbox CARGO_TARGET_DIR, copies WASM, verifies markers, writes buildinfo):

powershell -File build-wasm.ps1

Verify an existing root WASM without rebuilding:

powershell -File build-wasm.ps1 -VerifyOnly

Manual build (only if you unset CARGO_TARGET_DIR yourself):

rustup target add wasm32-unknown-unknown
cargo build --target wasm32-unknown-unknown --release
# Output: target/wasm32-unknown-unknown/release/star-crusher.wasm

To update the static landing-page artifact after a local WASM build:

Copy-Item -LiteralPath target\wasm32-unknown-unknown\release\star-crusher.wasm -Destination star-crusher.wasm

The build script also writes star-crusher.wasm.buildinfo.json (hash, UTC time, git SHA, relative paths) for freshness checks.

Security

This repository is intended for public GitHub Pages deployment. Before publishing:

• No secrets in repo: Do not commit .env, API keys, tokens, or private paths. star-crusher.wasm.buildinfo.json uses relative paths only.
• Content Security Policy: index.html restricts scripts/styles to 'self' with wasm-unsafe-eval required for WebAssembly.
• postMessage: Platform events forwarded to a parent frame use window.location.origin (not *).
• Dependencies: CI runs a Rust dependency vulnerability scan on push to main.
• Static site: The game runs client-side only; no server-side user data collection in this repo.

Then open index.html in a browser through a local server because WASM module loading is restricted from direct file URLs:

python3 -m http.server 8080
# Visit http://localhost:8080