splatter-tennis/PLAN.md

PLAN v2 — Match structure, enemies, weapons, interlude (phases 7–13)

Phases 1–6 (shot loop, fanfare, gore piles, bombs, hordes, racket zombie) are SHIPPED — see git log. This plan is the next arc, agreed with Oliver 2026-07-12.

Read HANDOFF.md FIRST (module map, verify recipes, gotchas — especially the stale-module cache one and "always Read current file state before editing"). Every phase is independently shippable: implement → verify → commit → push (push = deploy, Oliver tests on his phone). Do NOT start a phase before the previous one is pushed.

Ground rules (unchanged from v1):

• Zero dependencies, no build step, vanilla ES modules. Match the existing code style (compact, commented for intent, TUNE knobs for anything Oliver might want to tune).
• The tennis benchmarks in HANDOFF ("Tennis feel — CONFIRMED GOOD") MUST keep holding after every phase. Run them via window.T (Browser pane, RAF paused, T.step manual).
• New TUNE knobs go in config.js TUNE so they appear in the live T panel.
• Mobile portrait one-handed is the primary target: tap, flick, drag. No new buttons.
• Umpire lines: record with say -v Daniel → afconvert → assets/audio/*.m4a (pipeline and listen-check exactly as v1 Phase 2 did; mapping lives in audio.js).

Design decisions (made with Oliver — do not re-litigate)

1. The scoreboard IS the progression. Waves = tennis games, escalation = sets, breathers = changeovers, weapon deliveries = the new-balls rule. All structure comes from tennis rules — that's the joke and the design.
2. Permadeath runs. Eaten = the run is over. Score = games/sets survived, best run persisted. Runs are 3–5 minutes; restart is one tap (reload, as today).
3. Enemy roster: runner, brute, one "weird one" (shield zombie, design checkpoint). Sprites are approved by Oliver BEFORE any behavior code (Phase 10 is a STOP).
4. Tennis interlude = one sudden-death point vs the racket zombie, triggered when the umpire "restores order". Winner-takes-all, ~15s, then chaos resumes. If playtests love it, promoting to a full game is just the win condition — do NOT build that now.

---

Phase 7 — Match structure: games drive difficulty, sets, changeovers, permadeath

The root fix. Today spawning is a flat drip (zSpawnEvery 2.6s, zMax 6, forever) — that's why waves feel random, easy, and progression-free. Replace the drip with a spawn director keyed to games won, and give the run a real end.

• state.js G: add runGames: 0 (total games finished this run, never resets), sets: [0, 0], changeover: false. Keep splatT (the speed ramp stays as-is).
• Spawn director (zombies.js, replaces the flat timer in updateZombies):
  • spawnEvery(g) = max(TUNE.zSpawnMin, TUNE.zSpawnEvery - g * TUNE.zSpawnStep) with g = G.runGames. New knobs: zSpawnMin: 1.0, zSpawnStep: 0.22.
  • zMax becomes dynamic: min(TUNE.zMaxCap, 3 + G.runGames). New knob zMaxCap: 14. (Keep the TUNE.zMax knob as the game-1 floor: max(TUNE.zMax, ...) — no, simpler: replace zMax semantics: zMax = base 3, cap knob separate. Pick ONE and comment it.)
  • Game 1 of a fresh run must feel lonely: 3 shamblers, ~3s apart. Check the transition's scripted spawns still make that true.
  • Pause spawning during G.changeover — the breather must actually breathe. Zombies already on court keep walking (still dangerous, eaten still applies).
• Changeover (gameplay.js splatPoint, gameOver branch): after ODD total games (real rule: 1st, 3rd, 5th… game of a set), set G.changeover = true, G.phase='over', G.overT = TUNE.changeoverT (new knob, 4.5). Boys mop (sendBoy a couple of times), cheer, flash 'CHANGEOVER'. On expiry (setupPoint or a flag check): changeover=false, voice('time') — record: say -v Daniel "Time." → time.m4a. Even games keep the short beat they have today.
• Sets: in splatPoint's gameOver branch, G.runGames++; score.games[i] >= 6 → set won: G.sets[i]++, score.games = [0,0], voice('game_set_massacre'), cheer(3, .7), and startHorde() — the horde MOVES from "every game after the 2nd" to SET END. Delete the G.splatGames trigger (state field can go too). Horde stays the set-boss spike; endHorde still spawns the racket zombie (unchanged).
• Zombies win a game (baseline crossings): flash 'GAME. THEM.', and set G.shameGame = true — Phase 9 uses it to skip the next new-balls delivery. No other penalty; losing games mostly means the player is already drowning.
• Permadeath screen (render.js eaten overlay, main.js): the overlay becomes the run summary — 'GAME, SET, MASSACRE' / 'survived N games, M sets' / best run. Persist best via localStorage.splatterBest = JSON.stringify({games, sets}) (read lazily, guard with try/catch — private mode throws). Tap to restart = reload, as today.
• HUD: show sets alongside games (tennis scoreboard style: SETS · GAMES · PTS).

Verify (Browser pane, force splatter via umpire triple-tap… which now forces a horde — use T to set G.mode/score directly, or transition normally):

• Fresh run: ≤ 3 zombies on court in game 1, spawn gap ≈ 3s.
• T-set G.runGames = 8: spawn gap ≈ 1s, court fills toward the cap.
• Win game 1 (odd) → changeover: 4.5s beat, NO spawns during it, 'Time.' plays at the end.
• Win 6 games → set on HUD, horde fires, endHorde spawns the racket zombie.
• Get eaten → summary screen shows games/sets + best; reload; best survived the reload.
• Regression: tennis mode scoring/changeover untouched (changeover logic must be splatter-only); eaten flow benchmark updated to expect the summary screen.

Phase 8 — Bomb juice pass (make the explosion FELT)

Pure render/audio. The bomb works; it just doesn't LAND. All in explode() + render.js.

• Screen shake: G.shake = {t: 0.35, mag: 6} set in explode(). render.js: at frame start, if shake, translate the camera by (rand±mag, rand±mag) * (t/0.35) px and decay t. Restore transform after. (One translate around the whole draw — cheap.)
• Flash frame: G.boomFlash = 0.08 — render fills a white overlay, alpha t/0.08.
• Scorch crater: explode() pushes a gore entry with scorch: true (r 1.6, a 1). render draws scorch entries near-black/brown instead of red; boys mop them 10× slower (d.a -= dt * 0.16). The court should scar for most of a run.
• Hitstop: 0.1 → 0.18 in explode().
• Umpire loses composure: record say -v Daniel "Order. Order, please." → order.m4a; voice('order', 0.6) from explode(), rate-limited like horde scoring so bomb chains don't spam it.
• boom() louder/longer if it currently underwhelms on phone speakers — Oliver judges.

Verify: force a bomb (T: G.bombs=1, serve into a cluster): shake visible, flash frame, scorch stays after gore fades, 'Order' plays. Screenshot for Oliver. No transform leaks (HUD must not shake — draw HUD after restore).

Phase 9 — Weapons ride the new-balls rule (kill-meter retired)

Story fix: weapons aren't loot, they're DELIVERED — because tennis rules say new balls come after 7 games. The ball boys are the armorers. (In real tennis: first change after 7 games, then every 9. Too sparse for 3–5 min runs — knobs, commented with the real rule.)

• Delete the kill-meter path in zombies.js splatter() (G.killMeter, TUNE.bombEvery gone from state/config).
• gameplay.js splatPoint gameOver branch: if G.runGames === TUNE.ballChangeFirst (3) or (G.runGames - ballChangeFirst) % TUNE.ballChangeEvery === 0 (4) → schedule a delivery at the next changeover beat: sendBoy(), voice('new_balls', 0.5), flash 'NEW BALLS', G.bombs = TUNE.bombMax (a fresh tin of three).
• Shame rule: if G.shameGame (zombies took a game since the last delivery) → skip it: flash 'NO NEW BALLS', clear the flag. The umpire punishes sloppy play.
• HUD bomb pips already exist — unchanged.
• Phase 12 will extend the delivery ladder to new weapon types; here it's bombs only.

Verify: T-run to game 3 → tin delivered at changeover, bombs = 3 on HUD; let a zombie cross before game 7 → 'NO NEW BALLS' at that delivery, next one works. killMeter is gone from state (T.G.killMeter === undefined).

Phase 10 — SPRITE SESSION (STOP: Oliver approves every sheet before Phase 11)

The only asset phase. Pipeline gotchas in HANDOFF (generate-image skill, OPENROUTER_API_KEY in .env, magenta bg, scratchpad slice.py — recreate venv, IDLE_TARGET_H=112, watch for the generator ignoring magenta or drawing near-identical frames).

Sheets to produce (match the existing zombie sheets' style/palette):

1. Runner — gaunt, sprinting, arms trailing. Poses: 2-frame sprint (STRONGLY contrasted stride), idle/lurch. Visibly leaner than shamblers.
2. Brute — huge, slow. Oliver-pleasing absurdity: it dragged a net post along and uses it as a club. Poses: 2-frame trudge, idle. Roughly 1.5× shambler height.
3. Shield zombie — carries a line judge's chair as a shield, held forward. Poses: 2-frame walk with chair up, one 'staggered' pose with the chair dropped/lowered (that pose IS the vulnerability window, it must read at a glance).
4. Weapon tin — a "new balls" ball can, matte black, small skull where the brand goes. One still; the boy carries it on delivery runs (small, ~24px).

Deliverable: sliced sheets committed + one composite preview image sent to Oliver. STOP for approval. Rejected sheets get re-prompted, not hand-fixed.

Phase 11 — Enemy roster wired in (one new type per set)

Behaviors only after sprites are approved. Introduce one type per set so each gets its moment. Spawn mix lives in one table in zombies.js: const MIX = set => ... → weights for a/b, 'f' (runner), 'g' (brute), 's' (shield); runner from set 1 game 3, brute from set 2, shield from set 3.

• Runner ('f'): v ×= TUNE.runnerSpeed (3.2). Spawns SOLO with a warning shriek — new synth sfx shriek() in audio.js (style of moan(), higher/harsher). Cap: at most 1 runner alive (zombies.some(z => z.variant==='f') gate). It punishes tunnel vision; the shriek is the fairness contract.
• Brute ('g'): hp: TUNE.bruteHp (2) — reuse the racket-zombie hp pattern in the ball-contact branch (splat-quality hit decrements, killing blow → splatter()). v ×= 0.55, contact radius 0.75 (vs 0.55), immune to pushback (staggers don't move it), pellets take 3 hits (hp respected in the pellet loop too — currently pellets one-shot everything). Kill = double particles, size-2 pile.
• Shield ('s'): blocks balls arriving from the front (ball.vz < 0 at contact) — clank sound (pock variant), ball spent (lastHit='X'), zombie unharmed. A STAGGER (any front hit) drops the chair for TUNE.shieldDown (1.5s) — during that window any splat-quality ball kills it. Also always dies to: bombs, melee, pellets, and balls hitting it from BEHIND (ball.vz > 0 — the flick-down-behind-it shot, which the free-aim system already allows). Render the dropped-chair pose during the window.
• render.js drawChar: wire the three sheets; brute scale ×1.5 off SPRITE_H.
• Eaten radius: brute 0.9 (it's bigger). Runner eaten radius unchanged (speed is enough).

Verify (per type, T.spawnZombie grows a variant arg — it already has one):

• Runner: shriek on spawn, crosses the court ~3× faster, only ever one alive.
• Brute: survives one splat-quality hit, dies on the second, ignores pushback, eats 3 pellets.
• Shield: front ball clanks off; stagger → chair-down pose → kill lands; a ball aimed behind it kills outright; bomb kills it.
• Mix: T-set G.sets/runGames per set tier, watch 20 spawns, composition matches MIX.
• Full regression ladder after wiring: tennis benchmarks + phases 7–9 verifies.

Phase 12 — Weapon ladder on the delivery rail

Extends Phase 9's deliveries beyond bombs. Every weapon stays one-thumb: it's a serve modifier, auto-consumed, zero new inputs (exactly like ball.bomb today).

Delivery ladder by delivery index (1st, 2nd, 3rd… of the run):

1. Bomb tin (as shipped in Phase 9)
2. Triple serve (G.triples = 3 stock): the serve spawns 2 extra balls fanned ±6°. Extra balls: check git history first — a multi-ball array existed pre-revert (killZombie's comment still references "extra (multi-serve) balls"); reuse that shape if salvageable, else a lightweight extras[] in zombies.js (ballistic clones carrying pow, killing via killZombie, no scoring double-dip beyond it).
3. Flame ball (G.flames = 3): ball.flame flag — kills on ANY contact regardless of pow (the real power: quality-free kills), full pierce (no zPierce slowdown), fire trail (orange/yellow parts each frame, cheap), renders orange-hot.
4. Machine gun, 8s (G.mgT = TUNE.mgPickupLen): horde auto-fire machinery reused outside hordes — firePellet + drag-to-steer for 8s, then back to serving. (Flag interactions: serve prompt suppressed while mgT > 0, same gate as horde.) 5th+: cycle 1→4.

• HUD: one small icon row (reuse bomb pip drawing, one glyph per type).
• Flash text on delivery names the weapon ('NEW BALLS: FIRE').
• Precedence: one special stock at a time — a delivery replaces any unspent stock (simpler than stacking; comment it).

Verify: T-walk the ladder (set runGames): each delivery arms the right stock, each weapon kills as specced, mg mode enters/exits cleanly, no leakage into tennis mode. Triple/flame respect brute hp and shield-block rules from Phase 11.

Phase 13 — The interlude: order is restored (one sudden-death point)

The absurdity peak: tennis rules never stopped applying. Trigger — a racket zombie is alive (post-horde) AND the court is otherwise clear AND no horde/changeover: the umpire restores order and ONE real point is played.

• Record: say -v Daniel "Quiet, please. Play will resume." → play_resume.m4a, and say -v Daniel "Sudden death." → sudden_death.m4a.
• Trigger check in gameplay.update (splatter, ball dead, conditions above, once per racket zombie — flag on the zombie): G.interlude = true, spawning paused, voices, flash 'SUDDEN DEATH'.
• During the interlude the point is played under TENNIS rules: onBounce's line-call branch runs (out/net = you lose the point — the umpire is watching again). You serve (pretoss as normal); the racket zombie returns via its existing racketAI. NOTE: its AI only chases balls with pow < zSplatQ — during the interlude it must chase ANY ball (it's playing tennis, not dodging); killing it with a splat ball mid-interlude is allowed and counts as winning the point (crowd goes wild).
• Resolution: your point → weapon delivery on the spot (next rung of the Phase 12 ladder) + cheer(3, .7). Its point (return passes you, or your ball out/net) → 'GAME. THEM.' on the scoreboard AND an instant surge: 5 shamblers spawn at once. Either way G.interlude = false, normal spawning resumes.
• Zombie spectators: any shamblers that spawn-raced the trigger freeze in place for the duration (v = 0 while G.interlude — one gate in the walk loop). They watch.
• Keep it ONE point. Full-game promotion is a possible follow-up, not this phase.

Verify: survive a horde (or T-spawn a racket zombie + clear court), let the ball die → interlude triggers once: voices, tennis line rules live (hit one out → THEM + surge of 5), replay → win the point → delivery fires. Racket zombie chases soft AND hard balls during the interlude, only soft ones outside it. Eaten still works if the surge gets you.

---

New TUNE knobs (summary)

zSpawnMin 1.0 · zSpawnStep 0.22 · zMaxCap 14 · changeoverT 4.5 · ballChangeFirst 3 · ballChangeEvery 4 · runnerSpeed 3.2 · bruteHp 2 · shieldDown 1.5 · mgPickupLen 8 Retired: bombEvery (kill meter gone).

Umpire lines to record (pipeline in v1 Phase 2 / audio.js)

time.m4a "Time." · order.m4a "Order. Order, please." · play_resume.m4a "Quiet, please. Play will resume." · sudden_death.m4a "Sudden death."

Benchmarks that must stay green after EVERY phase (scripts in HANDOFF)

• Tennis: CPU returns ~11/12 serves; human-like tap sim = all hits, no whiffs; feet-bounce tap sweep ≈ 19/30.
• Splatter: serve→serve ≤ 20 frames with immediate flicks; eaten flow now ends in the RUN SUMMARY screen (games/sets/best) → tap restarts.
• Game 1 of a fresh run: ≤ 3 zombies, ~3s spawn gaps (the "starts slow" contract).
• No console errors after each phase's full verify run.