kgames

CLAUDE.md (17239B)

---

 # KGames — Claude Guide
 
 ## What this project is
 
 Free educational games for young kids. No ads, no signup, no backend.
 Static HTML + CSS + JavaScript served from any web host. Phaser 3 and
 Tone.js loaded from CDN. GPL-3.0.
 
 No build tools — double-clicking `index.html` is a valid development
 workflow for the games that exist today, and worth preserving for them.
 New games are not bound by it; see "Constraints for new games".
 
 ## Testing — run before every commit
 
 ```bash
 npm install          # one-time; downloads playwright (~112 MB Chromium)
 npm test             # unit tests + browser smoke tests; must all pass
 npm run test:unit    # fast, no browser (~0.2 s)
 npm run test:browser # headless Chromium (~10 s)
 ```
 
 **Never commit if `npm test` fails.** The browser tests catch broken
 rendering that syntax checks miss (see the projection-bug incident).
 
 ## Architecture
 
 | Path | Purpose |
 |---|---|
 | `index.html` + `css/style.css` + `js/main.js` | Portal — game tile grid |
 | `games/<slug>/index.html` | HTML shell: CDN scripts, HUD buttons, game container |
 | `games/<slug>/lib.js` | Pure logic (projection math, route gen) — dual-export for unit tests |
 | `games/<slug>/game.js` | Phaser scene — all graphics via `generateTexture`, audio via Web Audio / Tone.js |
 | `games/story-stamp/` | DOM-based phonics game (no Phaser) — see "Story Stamp" |
 | `tools/story-stamp-assets.py` | Fetches + cuts Story Stamp's recorded audio and pictures, writes its manifest and credits |
 | `tools/story-stamp-audit.py` | Checks the phoneme clips with independent methods (acoustics, cross-speaker match, Vosk recognition, spectrograms) |
 | `js/shared/game-shared.js` | Shared `KGames.*` helpers (AudioSystem, win screen, confetti, progress bar) |
 | `js/shared/touch-controls.js` | On-screen keyboard / D-pad for phones — see "Mobile / touch controls" |
 | `assets/thumbnails/<slug>.svg` | 160×130 viewBox, rx=18, stroke from palette, `#FFF5F5` fill |
 | `tests/unit/` | `node --test` unit tests — no browser, no Phaser |
 | `tests/browser/runner.js` | Playwright smoke tests — no JS errors + canvas renders |
 | `tests/serve.js` | Tiny Node HTTP server used by browser tests (and for local dev) |
 
 ## Top-down rendering (fire-truck)
 
 Fire-truck is a **top-down** driving game: the camera zooms 1/`SCALE` (SCALE=5)
 and follows the truck over a 50×50-cell island. `lib.js` `buildIsland()` lays
 out water/beach ring roads + BSP-subdivided interior blocks; the road graph
 drives the route and fire pathing.
 
 **Chunk bake pipeline** (`renderIsland()` in game.js). The static island is
 baked once into 16×16-cell chunk textures at `BAKE_CELL = 96` px/cell, drawn
 ×SCALE (zoom 1/SCALE) → **~1:1 on screen**, so ~96 px of detail per cell costs
 nothing per frame and Phaser culls offscreen chunks for free. Each chunk runs
 named passes into one `Graphics`, in order: `_bakeGround` → `_bakeSidewalks`
 (incl. road corner masks) → `_bakeRoadMarkings` → `_bakeBuildings` → `_bakeParks`
 → `_bakePalms`.
 
 - **1-cell apron rule** (highest visual-bug risk): every pass iterates a 1-cell
   margin around the chunk (clamped) at true local coords so overhanging art —
   SE drop shadows, palm fronds, block-spanning buildings — that crosses a chunk
   seam is re-drawn by the neighbour; `generateTexture` clips the overflow.
 - Buildings are drawn **per block, not per cell**: `FT.findBuildingBlocks(grid)`
   covers all building cells with disjoint rectangles (BSP guarantees rectangular
   road-bounded blocks) so each block reads as one building with one roof.
   `FT.assignParks()` tags ~15% of blocks `cell.park = true` (**type stays
   `building`**, so grid/route tests are untouched; parks are excluded as fire
   destinations).
 
 **Ocean underlay**: a screen-fixed (`scrollFactor 0`) `TileSprite` at depth −1
 drifts each frame. A world-sized TileSprite would allocate a multi-GB fill
 canvas — keep it viewport-sized.
 
 **Dual cameras** (game.js): `cameras.main` is the world; `uiCamera` is the HUD.
 Every new **world** object must be hidden from the HUD camera —
 `this._addWorld(obj, depth)` sets depth + `uiCamera.ignore`. HUD objects are
 added to `cameras.main.ignore(...)`.
 
 **Depth ordering** (exact values live in game.js): ocean < chunks <
 boats/buoys < peds < bikes < cars/buses < burning overlay < fire glow < fire <
 spray < smoke < cloud shadows < truck < birds < HUD.
 
 **Hose minigame** (`FireHoseScene`): when the truck reaches the fire, the
 driving scene enters state `minigame`, pauses itself, and launches a
 street-view scene — building facade with a window grid (`FT.buildFacade` in
 lib.js, pure + unit-tested), arrow keys move an aim reticle, SPACE sprays from
 the truck's rotating ladder. Quenched windows reveal waving residents/a cat;
 when all are out the scene resumes the driving scene and calls
 `_onMinigameComplete()`. **Headless-RAF rule**: gameplay logic lives in
 `_step()` driven from both `update()` and a wall-clock `setInterval` fallback
 (same trick as the driving scene's `fallbackTimer`), and all scene transitions
 use wall-clock `setTimeout` — never `this.time.delayedCall`, which starves in
 throttled/headless browsers and hangs the tests.
 
 **Shared cartoony art** (file-scope helpers in game.js): `bakePeopleTextures`
 (`kg-person-0..7`, racially diverse cartoon townspeople), `bakeSideTruckTexture`
 (`kg-truck-side`), `bakeLadderTexture`, `bakeCritterTextures` (dog/cat/parrot/
 iguana), `drawSidePalm`. Used by both `FireHoseScene` and `FireTruckEndScene` —
 reuse these rather than drawing new people/trucks.
 
 **Ambient life** (`_initAmbient` / `_updateAmbient`, driven from `update()` —
 never `step()`, which tests call directly): baked-texture Images for traffic
 (`FT.advanceCarPlan` graph walk), pedestrians, cloud shadows, boats, birds.
 Guard with `this.ambientReady`; clean up in `shutdown()`. All decor variety is
 deterministic via `FT.hashCell(x, y, salt)` so the island bakes identically
 every run.
 
 ## Story Stamp (DOM game, recorded audio)
 
 Story Stamp teaches blending (synthetic phonics) and is the first game built
 outside Phaser: plain DOM + CSS animations in `games/story-stamp/`, keyboard
 only. It is the reference for "Constraints for new games" in practice.
 
 The child runs the checkout desk of the island library. Patrons queue with a
 topic sign (bugs, space, dinosaurs …); the child picks one, gets a request
 slip with the title in sound boxes, stamps each letter (hearing its sound),
 presses SPACE to sound it out, and picks the matching book from the cart.
 **The game never says the word the child is decoding** — three blend passes
 with shrinking gaps, then the picture choice is the proof. "Returns" (patron
 says the word, child types its sounds) unlock after five mastered words.
 
 - `lib.js` — pure content + logic: `PHONEMES` (with `stretch` for held
   sounds and `home` for override sounds), `GRAPHEMES`/`BASE`/`SEQUENCE` (the
   teaching order, s-a-t-p-i-n first, digraphs and vowel teams later), `TOPICS`,
   `WORDS` (decodable words; `g` is the grapheme split, `art` the Fluent Emoji
   asset, `t` topics, `p` overrides ambiguous sounds like book's `oo` or
   robot's first `o` — override words are only offered once the child knows
   the grapheme that teaches that sound), `PATRONS`, the mastery /
   spaced-repetition scheduler (`recordOrder`, `pickNext`, `shouldIntroduce`),
   `buildQueue` (distinct topics per patron), `blendTimeline` (no word event),
   and the multi-child profile store. Unit-tested in
   `tests/unit/story-stamp-*.test.js`.
 - `audio.js` — Web Audio player for the recorded clips, speech synthesis for
   everything else, oscillator SFX. **Phonemes are never synthesised** and
   **never looped**: held sounds are ~1 s recordings and `playPhoneme(id,
   {len})` cuts them with a fade. A missing clip is silent. `audio.log`
   records every clip for the tests.
 - `game.js` — screens + desk flow. Exposes `window.__SS_GAME__` (`state`,
   `order`, `queue`, `profile`, `audio`) and `quickStart(name)` (lands on the
   queue) for tests; honours `window.__SS_NOW__` (clock) and
   `window.__SS_FORCE_MODE__` (`'return'`).
 - **Assets are generated, not hand-edited.** `python3 tools/story-stamp-assets.py`
   downloads Wikimedia Commons recordings and Fluent Emoji 3D PNGs and writes
   `assets/manifest.js` + `CREDITS.md`. Continuants and short vowels are cut
   from IPA recordings and held to ~1 s by WSOLA time-stretching of the steady
   middle; stops/affricates are cut from the start of word recordings (burst +
   aspiration, up to voicing); r-coloured vowels and diphthongs are whole word
   recordings ("are", "or", "ow", "boy" minus the b …). Add a word to `WORDS`
   with a Fluent asset name, rerun the script (`--offline` reuses `.cache/`),
   commit the outputs. The assets unit test checks manifest ↔ lib ↔ credits.
 - **Audit the clips after touching the pipeline:** `python3
   tools/story-stamp-audit.py` (Vosk in `.cache/pylib`, model in
   `.cache/vosk`; `--no-asr` without them). It checks acoustics per clip
   (duration class, voicing, centroid, stutter = looping, level flatness),
   matches each clip against sounds cut from a *different speaker's* word
   recordings, runs Vosk over words assembled from the clips (about half
   recognised at speech rate is normal for concatenated sounds; look for one
   sound far below the rest), and writes a spectrogram sheet to
   `.cache/audit/phonemes.png` to look at.
 - Age rules the code enforces: no timers/lives/fail state (a wrong key
   re-demonstrates the sound; after three wrong books the word is given and the
   book pointed out), every instruction is spoken, six books make a "day",
   meaning is checked with the book choice, progress is per-child in
   `localStorage` (`kg-story-stamp-v1`).
 
 ## Mobile / touch controls
 
 Phones have no physical keyboard and a Phaser canvas can't summon the native
 one, so `js/shared/touch-controls.js` renders an on-screen control bar whose
 buttons dispatch **synthetic `KeyboardEvent`s to `window`**. Phaser's keyboard
 plugin already listens on `window`, so every game's existing key handling works
 unchanged — game logic never references this module.
 
 - Opt in from the HTML shell, after `game.js`:
   `<script>KGames.initTouchControls({ layout: 'alphabet' });</script>`
 - Layouts: `alphabet` (A–Z), `text` (A–Z + Space/Backspace/Enter, e.g. work),
   `text-nav` (text + arrow row, e.g. story-stamp), `drive` (arrows +
   Music/Siren/Lights/Spray, e.g. fire-truck).
 - Shown only on touch / coarse-pointer devices. Force with `?kbd=1` / `?kbd=0`
   or `window.__FORCE_TOUCH_CONTROLS__` (tests use the latter).
 - The bar is a flex child below `#game-container`, so the canvas shrinks to fit
   above it. Phaser's `Scale.RESIZE` ignores a synthetic window `resize` when the
   window size is unchanged, so the module calls `game.scale.refresh()` directly.
   **This requires the game instance on `window.__KG_GAME__`** — assign it where
   you call `new Phaser.Game(...)`.
 
 ## Adding a new game
 
 The checklist below is the **Phaser + no-build** recipe the current games
 follow. It is a well-worn default, not a requirement — read "Constraints for
 new games" first and deviate where the game calls for it.
 
 1. Create `games/<slug>/index.html` (clone from `games/fire-truck/index.html`)
 2. Create `games/<slug>/lib.js` for pure (unit-testable) logic
 3. Create `games/<slug>/game.js` for the Phaser scene
 4. Add `render: { preserveDrawingBuffer: true }` to the `Phaser.Game` config
    (required for the Playwright pixel-reading tests to work), and assign the game
    to `window.__KG_GAME__` so touch controls can resize it
 5. Create `assets/thumbnails/<slug>.svg` (160×130, rx=18 rounded rect)
 6. Replace a `Coming Soon` placeholder in `js/main.js`
 7. Wire up touch controls: `KGames.initTouchControls({ layout: ... })` in the
    HTML shell (pick or add the layout that matches the game's keys)
 8. Add unit tests in `tests/unit/<slug>-*.test.js`
 9. Add browser test cases to `tests/browser/runner.js`
 10. Run `npm test` — all must pass before committing
 
 ## Hosting & deploy
 
 The project is self-hosted on NearlyFreeSpeech — there is no Codeberg/GitHub forge.
 
 - `origin` is `ssh://…@ssh.nyc1.nearlyfreespeech.net/home/private/kgames.git`
   (a bare repo outside the document root).
 - A **`pre-push` hook** runs `deploy.sh` on every push to `origin`, which rsyncs
   the site, refreshes the restic-backed mirror at
   `/media/bespin/kyle/backups/gits/kgames.git`, and publishes a static
   [stagit](https://codemadness.org/stagit.html) code browser + dumb-HTTP clone
   source to `https://www.keyboard.games/code/`. Skip with `KG_SKIP_DEPLOY=1`.
 - `deploy.sh` and the hook are **untracked**, so a fresh clone does not reproduce
   this setup — copies plus restore notes live in
   `/media/bespin/kyle/backups/gits/kgames-untracked/`.
 - The mirror is deliberately **never repacked** so restic dedups its objects.
 - `tools/stagit-style.css` is the code browser's stylesheet (site palette).
 
 ## Asset policy
 
 **Prefer real, openly licensed art made by human artists.** Procedural
 generation and AI generation are not the house style and must not be the
 default for a game's character and world art.
 
 Priority order for any new art or audio:
 
 1. Existing open-license work (CC0, CC-BY, CC-BY-SA, OFL, or otherwise
    GPL-3.0-compatible) — OpenGameArt, Kenney, open itch.io packs, Wikimedia
    Commons, Freesound, and similar.
 2. Commissioned or hand-made original work contributed under a
    GPL-3.0-compatible license.
 3. Procedural generation — fine for incidental effects (particles, gradients,
    simple shapes, UI chrome), not for characters, creatures, or environments.
 4. AI-generated assets — avoid.
 
 The same order applies to audio: real recorded voice and openly licensed music
 and SFX beat synthesised equivalents, so use human recordings when they can be
 found (Wikimedia Commons has thousands of CC-licensed word pronunciations and
 IPA sound recordings — see `tools/story-stamp-assets.py`). **Synthesised speech
 is acceptable** where no recording exists or the text is dynamic
 (instructions, character chatter, a word with no clip): use the browser's Web
 Speech API, which needs no server. Where a game depends on audio accuracy
 (phoneme audio for phonics), recorded assets are still expected.
 
 Record every third-party asset's source, author, and license in the repo, and
 surface attribution wherever the license requires it. **GPL-3.0 compatibility
 is a hard requirement**, never a preference.
 
 ## Constraints for new games
 
 The rules above under "Architecture" and "Key conventions" describe how the
 *existing* games are built. They are not a cage for new ones. A new game may
 use a different engine, a build step, bundled dependencies, and real image and
 audio asset files — pick whatever serves the game.
 
 What still holds for everything in this repo:
 
 - **Open source, GPL-3.0**, with license-compatible dependencies and assets.
 - **No ads, no signup, no backend, no tracking.** Static hosting only; any
   saved progress stays on the player's device.
 - **Tested** — new work ships with unit and browser coverage, and
   `npm test` must pass before every commit.
 - **Keyboard-first** — a game must be fully playable from the keyboard alone.
   Pointer input may be a convenience; no mechanic may depend on it. Phones are
   served by the on-screen keyboard in `js/shared/touch-controls.js`.
 
 ## Color palette
 
 `#E63946` red · `#1D7CF2` blue · `#FFD23F` yellow · `#2EC4B6` teal
 
 Tint equivalents: `0xE63946 · 0x1D7CF2 · 0xFFD23F · 0x2EC4B6`
 
 ## Key conventions
 
 - **Existing games use no external image assets** — all textures via
   `make.graphics({ add: false }).generateTexture()`. This is a description of how
   the current games were built, **not a rule for new ones** — see "Asset policy".
 - **Audio**: Tone.js for looping music; Web Audio API oscillators for SFX
   (lazy-init on first user interaction to satisfy browser autoplay policy).
   **Never start music/SFX straight from `Tone.start()` or a first keydown** —
   on phones the first key comes from the touch bar's `pointerdown`, which does
   not grant user activation, so contexts stay suspended (Safari never
   auto-resumes). Hand every AudioContext to `KGames.installAudioUnlock(...)`
   and do the "audio is up" work in its callback; the `audio:` browser tests
   emulate the Safari policy and will catch regressions.
 - **Music is opt-in.** Background music and the fire-truck siren start OFF and
   are switched on by the player (`M` / `S`, mirrored in the settings panel and
   the touch bar), so the first audio work a browser ever sees happens inside a
   real keypress — the one moment every browser (Edge on macOS included) accepts.
   Fire-truck also runs a once-a-second watchdog (`_audioWatchdog`) that re-nudges
   a Tone transport that failed to start, and the on-canvas HUD line says whether
   music is off, starting, or on.
 - **Font**: Fredoka, 400 + 600 weight (Google Fonts)
 - **Scale**: `Phaser.Scale.RESIZE` + `applyLayout(W, H)` / `onResize` pattern
 - **No `console.log` in production code** — browser tests assert zero console errors
 - **`window.__FT_SCENE__ = this`** exposed in `create()` for browser test inspection