kgames

CLAUDE.md (9189B)

---

 # 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. Keep it that way.
 
 ## 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 |
 | `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.
 
 ## 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),
   `drive` (arrows + 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
 
 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).
 
 ## Color palette
 
 `#E63946` red · `#1D7CF2` blue · `#FFD23F` yellow · `#2EC4B6` teal
 
 Tint equivalents: `0xE63946 · 0x1D7CF2 · 0xFFD23F · 0x2EC4B6`
 
 ## Key conventions
 
 - **No external image assets** — all textures via `make.graphics({ add: false }).generateTexture()`
 - **Audio**: Tone.js for looping music; Web Audio API oscillators for SFX
   (lazy-init on first user interaction to satisfy browser autoplay policy)
 - **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