splatter-tennis/HANDOFF.md

# HANDOFF — Splatter Tennis

**This file is the only planning document.** `PLAN.md` and `POLISH-PLAN.md` are deleted —
everything they specified is shipped, and what still matters from them is recorded below. For the
long history, `~/.claude/projects/.../memory/splatter-tennis-history.md` is auto-loaded; for the
detail of any individual change, read the git log.

Last updated 2026-07-30 after Oliver playtested the fixes. All eight retest issues are closed and
recorded at the bottom with what the fix was, because each one is a trap worth not re-digging.
Issue 1's first fix was **vetoed on feel and replaced** — read that entry before touching movement.

## What this is
SNES-style pseudo-3D tennis (Super Tennis reference) that transitions into a zombie splatter game
while keeping every tennis aesthetic (umpire voice, 15/30/40 scoring, ball boys, applause).
Zero-dependency vanilla JS, native ES modules, no build step. Mobile portrait one-handed play is
the primary target.

- **Run locally**: `preview_start` name `splatter-tennis` (python http.server :8641, `.claude/launch.json`)
- **Deploy**: push to `git@gitea.wuwi.one:wuwi/splatter-tennis.git` (main) → Coolify webhook builds
  the Dockerfile (nginx, no-cache). Oliver tests on his phone at splatter-tennis.wuwi.one ~30s after
  a push. **Bump `main.js?v=N` in index.html every time** or phones keep the old build.
  The Dockerfile must also COPY any new top-level file (it currently ships `index.html`,
  `manifest.webmanifest`, `*.js`, `assets/`).
- **Oliver edits files himself** (tuning values, sometimes sprites). ALWAYS Read current file state
  before editing; never assume your last version is what is on disk.

## Module map (all in repo root)
`config.js` TUNE (live T panel) + structural constants + `UI` palette · `state.js` the `G` object +
P/O/ball/score + `setupPoint`/`sendBoy` · `gameplay.js` ballistics/swings/serve/rules/AI/`update()` +
transition + `splatPoint` + ball-boy routines · `zombies.js` zombie/gore/particle state +
`updateZombies` · `render.js` camera/palette-lerp/sprites/all drawing · `input.js` keys/touch/flick ·
`audio.js` sfx + recorded umpire (`assets/audio/*`, macOS `say -v Daniel`) · `panel.js` the T panel ·
`main.js` boot, loop, umpire-tap cheat, `window.T` test surface.
Two runtime-only import cycles (documented in headers): input↔gameplay, zombies↔gameplay.

## How the game flows
Tennis → win a game → **transition** (`G.mode='transition'`, timeline on `G.transT`) → **splatter**.
In splatter you serve at zombies; `ball.pow` ≥ `TUNE.zSplatQ` splatters, below that it staggers.
Tennis scoring keeps running. `TUNE.killsPerPoint` kills = one point; games/sets accumulate;
6 games = a set = a **horde** (racket auto-fires, finger steers you absolutely).
Odd games end in a **changeover** breather. A won game leaves the wave standing — you must
**clear it by hand** (`G.clearing`) before play advances (`proceedAfterClear`).
Weapons are **only ever won**, in the **sudden-death duel** (`G.interlude`) against the racket
zombie. Getting caught = `G.mode='eaten'` = permadeath, and the run summary is the whole game.

## Architecture & invariants — know these before touching anything

- **`G.modal` is the only thing that stops the world.** `update()` early-returns on it (after
  flash/card decay), so no zombie steps, no ball flight, no spawn timers — only `idleT` ticks for
  the blink. `showModal`/`dismissModal` in gameplay.js; `drawModal` is the LAST thing render draws.
  Dismissal must **swallow the gesture**: input.js `touchstart` returns on it, keydown returns on
  it, and the `pointerdown` dismisser is registered **only on `pointer: fine`** — on touch,
  pointerdown fires *before* touchstart, so a shared handler cleared the modal and let the
  touchstart underneath serve. `G.seen.<key>` gates first-time-only modals.
- **`UI` in config.js is the accent palette** (hot/warm/pick/cream/dim/bad/ball). Every HUD colour
  goes through it. Gore reds are deliberately NOT in it — the splatter stays loud.
- **`F(size, bold)` in render.js builds every canvas font string.** Bare `monospace` resolves to
  Courier, a slab SERIF — that was the "generic serif" bug, not taste. Never hand-write `ctx.font`.
  Widest string checked fits 270px portrait with ~10px spare.
- **Weapons are only ever WON.** `deliverTin()` has exactly one caller: `resolveInterlude('P')`.
  The schedule (`TUNE.duelFirst`/`duelEvery`, `G.duelDue`) calls the **duel**, fired from
  `proceedAfterClear()` — the one beat where the court is guaranteed empty. The game beat it
  interrupts is parked in `G.afterDuel` and resumed when the duel resolves.
- **Anything that blocks serving.** If a "can't serve" report ever comes in, check these first —
  each is an early return in `keyPressed`: `G.mgT`, `G.horde`, `G.changeover`, `G.interlude.introT`,
  `G.modal`. `G.mgT` in particular must keep counting down in EVERY phase (it used to tick only
  during `rally`, so a duel calling `setupPoint()` stranded it above zero forever = permanent lock).
- **Animation frames step off DISTANCE COVERED, never elapsed time** — `boy.dist` for ball boys,
  `zb.z / TUNE.bruteStride` for brutes. Time-driven cycles moonwalk the moment speed and frame rate
  disagree. Sprite heights follow the PNG (`img.height / SPRITE_H`) because `_slice.py`
  common-scales a sheet; a wound stage's height must ALWAYS come from its A frame or it pops.
- **Fire chains.** `zb.burnT`/`burnD`; `ignite()` is read-only over `zombies[]` so it is safe inside
  a kill loop; `burnTick()` returns true when the fire killed the body and the caller MUST
  `continue`. The flame ball also ignites what it FLIES PAST (`TUNE.burnBallR`) — without that its
  full pierce killed its own lane outright and nothing was left to catch. Flames are drawn
  procedurally (`drawFlames`), no sprite sheet.
- **Any loop over `zombies[]` whose body can kill** can cascade into a sweep and gut the array
  mid-iteration — keep the `if (!zb) continue` guards and iterate backwards.
- **The ball boy is ONE slot.** `sendBoy` never replaces a boy already on court (a kill streak used
  to teleport him back to the wing several times a second); new work is appended via `jobs`.
  `mopRound` walks him to a stain, holds him there for `TUNE.boyMopDwell` while the push cycle
  animates in place, then moves him on. Three sheets: `x_boymop` (stopped, working),
  `x_boycarry` (walking with the mop shouldered), `x_boyrun` (tennis-mode fetch).
- **Crowd applause is a real two-frame swap** (`x_crowd` seated / `x_crowd2` arms up), per column on
  its own phase, with **no vertical offset**. A fractional `dy` on a scaled image re-snaps its pixel
  rows every frame under nearest-neighbour — that boiling beside the HUD was the "scoreboard
  flicker" (the board art is 99.9% opaque; nothing was ever showing through it).
  **If you touch one crowd frame you must apply the identical curve to the other**, or the swap
  starts flashing brightness. `assets/_sheet_crowd1.png` is the pre-brightening original.

## Settled feel decisions — do not regress silently
- **Two-stage serve**: touch = reticle, drag = aim, release = fire, drag back under `pullMin` =
  cancel. The pull's DIRECTION picks the lane, its LENGTH is power — deliberately decoupled so a
  far shambler never costs a longer drag than the screen has.
- **The manual wave clear** after a won game (`G.clearing`). Oliver was emphatic.
- **Thin, dynamic blood.** Open wounds gush live particles (`bleed()`); blood is never painted into
  a sprite. Gore piles/stains are the loud part; keep the trickle sparse.
- **One gesture means one thing** on touch. No mode where a drag silently becomes something else.
- **Volleys**: pre-bounce contact gets reach ×1.4 / window ×1.8 (`VOLLEY`). A RISING ball is
  hittable at any height; only a dropping ball below `CONTACT.minY` is past you.
- **Aim magnet**: `flickTarget` picks the best-ALIGNED body, with `TUNE.aimTie` of slack in which a
  nearer one still wins, so a straight-ahead lane still eats the nearest body first.
  `aimTie: 1` restores the old "nearest along the lane always wins" for A/B.
- `TUNE.fps` 60 — 30 was vetoed on feel.
- **The player only walks during `rally`.** Never between points. Letting him walk during the 'over'
  beats and `pretoss` was shipped once and vetoed immediately: *"I basically can never walk around
  freely"* — so suddenly being able to, only between points, reads as the game breaking rather than
  as a fix. Frozen-with-danger-approaching is fixed by holding the DEAD instead (`held` in
  `updateZombies`), never by handing back movement.
- **The player must always be ON SCREEN.** `P_BOUNDS.x` is 6.5 m but portrait only shows about
  ±4 m either side of the centre line at the baseline, so the walk bound alone let him leave the
  frame entirely. `xLim = Math.max(xVis, COURT.W / 2)` — the camera limit, floored at the sideline so
  every legal ball stays catchable.

## Verification recipe (the regression net)
Drive the game deterministically via `window.T` with `javascript_tool`. The Browser-pane eval
context reports `document.visibilityState === 'hidden'`, so RAF is paused; halt it anyway with
`window.requestAnimationFrame = () => 0` and step with `T.step(1/60)`. `T.press('Space')` = tap.
Clear the intro first: `document.getElementById('intro')?.remove()`.
- **You MUST set `T.TUNE.autoAssist = 1.15` first** — the Browser pane reports `pointer: fine`, so
  the mobile assist is off and every ball reads as "never reachable".
- Force splatter with `T.forceZombies()` then ~600 steps (in splatter it forces a HORDE instead).
- `T.zombies`, `T.spawnZombie(x, z, 'a')`, `T.TUNE.zMax = 0` to stop spawns during tests.
- Also exposed: `T.explode`, `T.splatPoint`, `T.startDuel`, `T.resolveInterlude`, `T.deliverTin`,
  `T.flickTarget`, `T.showModal`/`T.dismissModal`, `T.render`.

**Benchmarks that must keep holding** (re-run after any physics/aim change):
- CPU returns ~11/12 serves (91.7%). Recent 150-sample runs: 90.7%, 89.3%, 90.7%, 88.7% (±2.5%).
  Watch this — the last few sit under the bar rather than scattered around it.
  **The harness for this number was never written down and I could not reconstruct it.** A rig that
  counts "did the CPU get a racket on the served ball" scores 100/100, because after a flub the CPU
  gets another swing at the SAME ball (`aiSwingCool = 0.5`) and connects — 91.7% ≈ 1 − aiFlub, so the
  recorded number must count only the FIRST swing opportunity, or only returns that land in.
  Until someone writes the rig down, prove "no tennis regression" **differentially** instead: run
  your rig, `git stash` the change, reload the modules, run the identical rig, compare. Equal
  numbers on the same rig is the real claim; a bare percentage against this line is not.
- 30 human-tapped points (tap when the incoming ball is 2.2–3.2 m away) = **50 hits / 0 whiffs**.
  This one DOES reproduce exactly — drive it off `G.missLog` (HIT vs MISS counts).
- A 26-game state-machine soak with bombs/bursts/fire must finish with no exceptions, no stall,
  `mgT` back to 0, and gore/piles arrays bounded (gore caps at 40, piles at 30).
  **Two ways a soak lies to you**, both cost me a run: force-spawning zombies during `G.clearing`
  makes the hand-clear un-completable and reads as a 30-minute stall; and reviving the player after
  each `eaten` inflates gore past its cap, because the death push (`zombies.js`, the `eatenR` hit) is
  the one uncapped `gore.push` in the file — fine at one death per run, not at 260. Respect
  `clearing`, and either end the soak on death or set `TUNE.eatenR = 0` to make him untouchable.
- **Never trust a single sample.** aiFlub is 9%; a 20/24 run is normal noise. Use 150.

## Asset pipeline
1. `generate-image` skill (needs `OPENROUTER_API_KEY` in the gitignored repo `.env`; run with the
   scratchpad venv python — system python lacks `requests`). Passing the existing sheet as
   `--input` (edit mode) nails the style and is how every matching sheet here was made.
2. Ask for a **magenta background** and, for sheets, "at least 150px of empty magenta between
   frames" plus "the prop must stay inside its own frame".
3. `python3 assets/_slice.py sheet.png out1.png ...` — chroma-key on the corner colour, magenta
   de-fringe, column-gap segmentation, common-scale per sheet, `IDLE_TARGET_H=112`. `--largest`
   keeps only the main blob.
4. Standalone art (logo, popup panels) uses `assets/_key.py` instead: chroma-key + crop to the
   content bbox + optional downscale, no frame splitting, no forced height.
5. Register new names in `render.js`'s `SPR` preload array.

Known generator quirks, all still true:
- It sometimes ignores the magenta (harmless — the key uses the corner colour).
- It draws near-identical animation frames unless you describe strongly contrasted poses.
- **It adds props the A frames don't have** (a dragged pole on every brute B frame, a mop head). If
  the prop is a separate blob, keep the largest connected component; if it touches the body, cut on
  column density — a torso is dense, a dragged pole is a thin diagonal of ~7 px per column.
- **If frames merge** (a handle bridging the gap) `_slice.py` reports "found 1 frames". Re-prompt
  for wider gaps first; if that fails, cut at the true column gaps plus the thinnest column inside
  the merged pair, then common-scale.
- **Colour-match any regenerated frame** of an existing pair before shipping: fit a per-channel
  linear map onto the original's mean and sd, then verify with a mean-difference number.

## Gotchas learned the hard way
- **Stale ES modules are the #1 time sink.** python http.server sends no cache headers, so an edited
  module often loads STALE. `preview_stop`/`preview_start` only helps if the port actually changes,
  and holding 8641 with a throwaway socket **did not work reliably**. What DOES work:
  ```js
  await Promise.all(['main.js','state.js','gameplay.js','render.js','config.js','zombies.js',
    'input.js','audio.js','panel.js','dom.js'].map(f => fetch(f, {cache:'reload'})));
  ```
  then reload the page. **Always sanity-check a just-added field before trusting any result** —
  and note the trap: if `state.js` is stale but `gameplay.js` is fresh, a new `G` field
  materialises as **NaN** (undefined + dt), which reads exactly like a logic bug.
- `drawChar` mirrors sprites by `ch.facing` — any stance that must not mirror needs facing reset.
- Synthetic touch tests: input.js only sets `stick.moved` in touchmove, so touchstart→touchend
  reads as a TAP. Always dispatch a touchmove between them.
- Contact/kill tests must step 1/60 — pellets at 26 m/s tunnel past 0.55 m radii at coarser steps
  and kills silently don't happen, which looks exactly like a bug.
- **When testing fire or any serve, fire a real ARC.** A flat ball from z=16 hits the net
  (netH 0.914) and bounces back at you; a "the weapon is broken" reading was my test hitting the tape.
- The scratchpad venv gets wiped between sessions — recreate it with `requests` + `pillow`.
- Commit style: imperative summary + `Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>`.
  Push = deploy.

---

# CLOSED — Oliver's 35-game retest (2026-07-27), all fixed 2026-07-30
Kept because each one is a trap worth not re-digging. Every fix was verified in the browser via
`window.T`; the numbers quoted are from those runs.

### 1 + 6. Player frozen (and stuck mid-animation) during the between-game pauses — was HIGH
**Two fixes: the first was wrong.** The movement block — pose update included — lived inside
`if (G.phase === 'rally')`, so every 'over' beat and every `pretoss` left the player standing while
zombies walked at him. The `pretoss` case is issue 6: `endHorde` calls `setupPoint()`.

The first attempt widened the block to all of splatter except `'toss'`. Oliver vetoed it on sight:
*"the mechanic where I suddenly can move freely around feels broken.. I basically can never walk
around freely - also I could walk off the screen"*. He is right — free movement for five seconds
between points, in a game where you otherwise only move while a ball is live, reads as a bug. It is
reverted, and the rule is now in Settled feel decisions above.

What actually ships, three separate pieces:
- **The dead wait too.** `held = !!G.changeover` in `updateZombies` stops every zombie's `z` advance,
  its x steering, and the eat check for the breather's duration. They still bleed, still burn, still
  animate — they just stand there, because the umpire called time and it is still a tennis match.
  This is Oliver's own second option and the characterful one (the boys mop, everyone waits).
- **The stuck pose.** `expirePose` only ever expired `swing`/`serve`; `'run'` was the pose nothing
  reset, and `P.runT` stops advancing outside the movement block, so a beat that began mid-stride
  welded him to one run frame. An `else if (P.pose === 'run')` on the movement block fixes it for
  every phase at once.
- **The on-screen clamp** (see Settled feel decisions) — `xVis` already existed but was applied only
  in auto-fire modes, so ordinary play could walk clean off the edge. Now it always applies.

**The path where this actually bit** — worth knowing, because a clear court makes it look impossible:
a changeover normally starts only after `G.clearing` has emptied the court, so nothing is walking.
But `resolveInterlude('O')` spawns **five fresh zombies** ("the dead lose their patience") and *then*
hands back to `startChangeover` via `G.afterDuel`. Lose a duel scheduled on a changeover beat and you
get five shamblers plus five seconds with no agency. Verified fixed: they advance 0.000 m across the
breather and resume 0.75 m/s the instant "Time." is called.

If the 5 s still drags on a phone, `TUNE.changeoverT` is the knob — it is now a safe, watchable beat
rather than a dangerous one, so shortening it is purely a pacing call.

### 2. The mop boy walks on during the 1:1 duel — was LOW
`sendBoy` now returns early on `G.interlude`, and `startDuel` sets `G.boy = null`. Note the ordering
that makes this safe: `resolveInterlude('P')` clears `G.interlude` **before** calling `deliverTin()`,
so the boy still comes out with the tin.

### 3. Triple serve: the two wing balls lob off at the wrong height — was MEDIUM
The diagnosis in the old text was right. `g: ball.g` is now copied onto each clone (both push sites:
`hitServe`'s triple fan and `dragServe`'s re-fire clone) and `zombies.js` integrates
`e.vy -= (e.g || TUNE.gravity) * dt`. Verified at full pull: clones carry g = 21.16 (2.3 × the 9.2
base) instead of 9.2, and centre and wing apex heights now match exactly (2.90 m both).

### 4. The umpire calls "Time" on pauses that aren't changeovers — was LOW
`G.changeover` is now the **seconds left**, not a flag (still truthy, so every `!G.changeover` guard
reads the same), and it counts itself down near the top of `update()`, calling `voice('time')` when it
hits zero. It no longer rides the generic `G.overT` expiry — anything that overwrote `overT` mid-
breather (a melee kill taking a game, say) used to make the umpire call time on a pause that was
never a changeover. Verified with a `fetch` spy on `assets/audio/time.m4a`: an unrelated `overT`
expiry at t=0.4 s says nothing and leaves 4.6 s on the breather; the line fires exactly once, when
the breather's own clock runs out.

### 5. The transition tutorial illustration confuses people — was MEDIUM
`assets/x_howto.png` regenerated (Gemini 3 Pro, edit mode with the old sheet as `--input`, then
`assets/_key.py … 240`). The curved arrow and thumbprint are gone; it is now a press ring at the top,
a straight vertical dashed track, two chevrons pointing DOWN, and a fingertip at the bottom — with the
yellow shot arrow flying the opposite way to the zombie, which is the inversion lesson. Aspect is
unchanged (240×321 vs 240×322), so the modal still draws it at 90×120 in portrait. Checked at that
drawn size, not at full resolution.

### 7. Aiming plays the toss animation; it should stay in the pretoss stance — was MEDIUM
`update()`'s forced `sv.pose = 'serve'` for `phase === 'toss'` is now gated on `!G.aim`: while the
slingshot is drawn the server holds the pretoss stance, and only `hitServe` puts him into the
toss/smash. Verified: plain tap → pose `serve`; drawn bow → pose `idle`.

### 8. Show the current game number persistently — was LOW
`GAME N` now sits permanently under the scoreboard, right-aligned to the board's width, on the same
row as the NEXT pips and in the same dim tone (`render.js`, just before the pips block). The 1.1 s
flash when a game arms is still there.