splatter-tennis/HANDOFF-MATCH.md

HANDOFF — ZOMBIE TENNIS, making it a real mode

TEMPORARY FILE. Written 2026-08-12 because a session ran out of context mid-slice. When the work below is done, fold anything durable into PROJECT.md (the only planning document) and delete this file. It is deliberately not in the Dockerfile COPY — docs are not served.

Read PROJECT.md first, as always — especially "How to work on this", the invariants, and the drill/match session logs (passes 13-23), which carry the reasoning behind every number named here.

---

Where things stand

Zombie tennis is a back-room prototype that plays well on a real phone ("big improvement on real mobile"). Entry: splash → five taps in the top-left corner (#hot) → MATCH TEST, or #match. Sibling prototypes there: WEAPON TEST, BOSS TEST, DRILL TEST (the abandoned cognitive mode — see below). 49 tests green, seeds clean. Last commit 9b9f18d, index.html at ?v=176.

What it is: real tennis against the racket zombie. One game per opponent, tap-and-timing controls, the deuce/ad serve positions, and the score is the body — each point you win takes a quarter of its pool and walks it through its wound stages; the game-winning point fells it and a fresh opponent shambles on. Its points draw your blood (matchPlayerHp 8, matchHeal 2 per game won). It runs on a PERMANENT interlude — G.interlude is what makes serving tennis-like, hides the rack and wakes racketAI — and the only change is in resolveInterlude, which feeds matchPoint instead of ending anything. All of it is ~120 lines in beats.js.

The ladder escalates in racketAI, not hp: speed (matchSpeedBase/Per), whiff (matchFlub/FlubKeep), width (matchWideBase/WidePer), pace (matchOppPace/PacePer). Player side: matchAssist, matchReach.

---

THE DECISION JUST MADE — scoring model A

Oliver picked A: blood-only, of three options offered:

• A (chosen) — the run is one long bleed across opponents; losing a game costs nothing but the blood already spent, and heals are how you last. The measure becomes OPPONENTS FELLED.
• B — tennis-true: a lost game ends the run. Rejected for now (worth one playtest someday; it might be the mode's real personality).
• C — hybrid, a lost game drops you an opponent. Rejected.

Important context for whoever implements this: Oliver believed losing a match killed him ("i really die losing one match"). It does not — he was bleeding out during deuce wars and hitting zero at their game point. That misreading is itself the bug to fix: the mode is not communicating its own rules. Model A only works if the player can see they are bleeding, not losing.

---

The build slice, in order

1. Run summary + the measure DONE (2026-08-12, staging). The measure is OPPONENTS FELLED, in play (OPPONENT n · m FELLED under the board) and on the death screen (BLED OUT. / FELLED n OPPONENTS · m GAMES). No second localStorage key: a match run is banked through the same endRun with a mode tag — see "The record shape" below. The blood also got a readout, one pip per hit left beside the board, because the vignette says "worse" and never says "how many".

2. Named opponent list DONE, partly. Opponent N takes design N's name off the chapter roster (matchFoe in config, rows in config.OPPONENTS) plus a personality that is DIALS — pace, width, flub, speed scalings on numbers racketAI already reads. Name plate on the walk-on, the board names it (short), and the kill files under it so the OPPONENTS FELLED screen can list it. (The word "ladder" was retired — it had come to mean the opponent list, the wound stages AND a stats screen. One word per thing now: OPPONENTS, WOUND STAGES, and a sprite FAMILY.) Still open, and still the cheapest depth in the mode: shots[] and the PARRY are fully built and completely unused here. A body-shot thrower is a personality no dial can express.

3. Wound-driven play (small, big payoff) — the injuries should MEAN something: a one-armed opponent loses reach, a headless one flubs more. Score-is-the-body becomes score-changes-the-game. Read the fraction the way drawZombie and bleed() do (never literal hp). The art is now there for it: every wound stage has its own ready stance, shuffle pair and forehand (z_rw1*, z_rw2*), so a wounded opponent still plays rather than reverting to a walk.

4. The fall animation DONE (2026-08-12). Point won → the body COLLAPSES → drags itself up minus the limb. beats.tickMatchFall, on its OWN clock beside the horde's warning (a beat that moves the phase under a latch strands it — the mgT lock, again); the 'over' beat it also sets is only there to keep the court quiet and is deliberately set to OUTLIVE the fall, so it cannot expire into setupPoint() mid-collapse and hand the player a serve over a body on the ground. The contract, and the whole point of the beat: the three collapse frames wear the stage it STILL WAS, the rise wears the stage it has BECOME. Frames are named through zb.showFrame (the bench's own override, which already degrades a missing stage to the healthy frame). Only when the stage actually moved — a quarter off a full pool is 0.75, so point one crosses nothing and a second of collapse for nothing is a beat the player waits out.

5. Menu entry DONE. Three modes on the setup screen, from config.MODES. The back room keeps its door (MATCH TEST still works) — the menu did not replace it, it just stopped being the only way in.

6. Teaching (small) — a ghost-hand lesson for the PLACEMENT FLICK. It is the counter-attack (flick during the swing aims the return; wrong-footing is how points are won) and it is taught nowhere on touch. The placement ring (G.placeMark) already shows the result; nothing teaches the cause.

7. Opponent serve games DONE (2026-08-12), and it was almost entirely switched off rather than missing. setupPoint's tennis branch already placed a non-player server behind its own baseline and armed G.aiServeT; update() already tossed and struck for O. Both were gated on G.mode === 'tennis', and the match runs in splatter under a permanent interlude — one condition. What was genuinely new: service alternates at each game boundary (the match calls advancePoint directly, and the flip lives in tennis's pointTo, which the match bypasses — the same shape as the G.serveNum bug above), the zombie takes O's mark when it serves so the picture and the ballistics agree on where it stands, and the serve POSES are named onto it (bounce → toss → serve, held briefly after contact) because O is invisible here. Known simplification: the interlude's line-call branch has no serve box and no second serve, so a missed opponent serve is simply the player's point. Add faults when it matters.

---

What the 2026-08-12 session added beyond the slice

CLASSIC TENNIS is a real mode, not the opener with the turn switched off. Oliver: "if the core tennis is good everything else is good." Six games with a two-game lead is a set, TUNE.classicSets is the match, no tiebreak (marked ponytail: — add it when a real match actually stalls at 6-6). The CPU stops rubber-banding there: aiFlubLoss exists to get a new player PAST the opener and would have him in pieces by the second set.

A second ENDING, with no corpse in it. G.done = {won, t} — same summary and gated tap as the death screen, its own words, the man still standing. All three endings share one render block; three copies of it would drift the first time one moved.

THE RECORD SHAPE — read this before touching stats.js. One character m on the run record (gore / zombie tennis / classic; absent means gore, so no migration). The record's two headline slots carry each MODE's own two numbers:

mode	g	s	dead
gore	games survived	sets banked	died
zombie tennis	opponents felled	games played	died
classic	games played	sets won	match LOST

g is what everything ranks on, so each mode's real measure goes in that slot and there is no second best stored anywhere to drift. read(period, runs, mode) filters; the stats screen is one function with three sets of words (BODY COUNT / OPPONENTS FELLED / THE RECORD). The world board stays the gore mode's — it ranks kills in a run, and a five-body match would post a "5 kills" row next to a 300-kill massacre. A tennis board would rank FELLED with points won as the tiebreak; that is a server change.

THE MATCH OPPONENT HAS ITS OWN SPRITES (z_r*), drawn off the living opponent's poses: ready stance, shuffle pair, forehand, at each wound stage, both tours. z_c* (the turned CPU) is untouched and keeps its shamble — in the gore mode shambling is the right thing for it to do. The frame is picked off racketAI's own pose, so the picture cannot drift from the behaviour.

Expansion ideas that survived discussion, in PROJECT.md's LATER: the tournament frame (QUALIFYING → ROUND OF 16 → THE FINAL vs THE CHAMPION — gives the run a destination), the Hawk-Eye challenge as an earned continue, sudden-death deuce past a given opponent, doubles, and item 7: multiplayer (ghost match first).

---

THE TOOL THAT MATTERS: the flight recorder

Four rounds of "still the same behaviour" were ended by watching Oliver play, not by measuring with an autopilot. Autopilot measurement lied for three passes straight because the autopilot set autoAssist by hand and therefore had legs the real player did not.

Recipe — inject into the Browser pane, let him play, then read it:

window.__rec = { losses: [], wins: [], trail: [] };
let lastPts = '0-0', lastHp = null;
setInterval(() => {
  const T = window.T; if (!T || !T.G.match) return;
  const G = T.G, ball = T.ball, P = T.P;
  window.__rec.trail.push({ pts: T.score.pts.join('-'), phase: G.phase, hp: G.hp,
    bx: +ball.x.toFixed(1), bz: +ball.z.toFixed(1), bAct: ball.active, bLast: ball.lastHit,
    px: +P.x.toFixed(1), pz: +P.z.toFixed(1), swing: P.swingT >= 0 });
  if (window.__rec.trail.length > 100) window.__rec.trail.shift();
  const pts = T.score.pts.join('-');
  if (pts !== lastPts) {
    const wasO = pts.split('-')[1] !== lastPts.split('-')[1] || (pts === '0-0' && G.hp < (lastHp ?? G.hp));
    (wasO ? window.__rec.losses : window.__rec.wins).push({ at: pts, from: lastPts, trail: window.__rec.trail.slice(-30) });
    lastPts = pts;
  }
  lastHp = G.hp;
}, 16);

Then classify each loss by: minimum player↔ball gap, whether he swung at closest approach, how far he ran, where the ball died. That triple diagnosed every defect in the contact chain.

• Sample at 60 Hz, not 20 — a 20 Hz sampler overstates closest approach by up to ~0.5 m on a 20 m/s ball, which is the entire size of the effect being measured.
• It is passive. Do not "help" the player from inside it.
• A page reload wipes it. Re-arm after every module refresh.

---

THE FLICK WAS LOSING THE POINT (fixed 2026-08-12)

Oliver: "when returning a ball with a spin on the screen that seems to be too sensitive, 8/10 times the ball lands out." It was arithmetic, not feel. The singles line is 4.115 m. An aimed shot targeted a flat ax * 3.3 and THEN added err() on top — up to ±aimError (2.4 m) at quality 0 — so a flicked return landed as wide as 5.7 m, and the only clamp in the path was at ±5, outside the court. An UNAIMED return targets 0 + the same scatter and is therefore always in. Aiming was the thing that lost the point, which is exactly backwards for the mode's one act of skill.

TUNE.flickReach (0.45) scales the aim width by the same quality the scatter shrinks with, so the two can never sum past the line: worst case 1.49 + 2.4 = 3.89 at quality 0, and a perfectly timed flick still gets the full 3.3 with no scatter left on it. A test asserts that sum across the whole quality range rather than sampling rallies. Not named aimReach — that key already exists further down TUNE (the slingshot's aim-ray length, 22 m) and the duplicate silently won, which a test caught.

The placement ring carries q now and reads as the flick's receipt: tight and hot when your timing earned the full width, wide and dim when you barely got a racket on it. Without it the new rule is invisible — the shot simply goes less wide and nothing says why.

Traps this mode has already sprung (do not re-learn these)

• autoAssist is 0 on pointer: fine. The desktop pane has no auto-run. The match floors it with matchAssist, and assistK() is shared by the mover AND intercept — computing reachability with the raw knob made the planner answer "run home" forever.
• The contact chain is three separate things: LEGS (matchAssist) → DESTINATION (assistK in intercept, plus the anyHit short-ball candidate that chases dying rollers) → REACH (matchReach). Each was a separate defect found in a separate recorded session.
• ball.lastHit must be stamped by tossBall. A stale 'O' on a toss from behind the baseline read as the opponent's passing shot: a point and blood PER TAP. Fixed, but the shape recurs — anything that revives the ball must own it.
• G.serveNum is only reset by tennis's pointTo, which the match bypasses. matchReady() resets it; a new mode with its own point boundary must too.
• A 20 Hz snapshot of a population that legitimately empties is not a measurement (this cost a flaky test that blocked the pipeline). The suite is seeded — SEED=1234 node test.js fuzzes; a fixed seed can silently turn a guarded test into a no-op, so check guards still run.
• ?v= in index.html on every push, or phones keep the old build. Bump SPRV too if sprites change.
• stats.banked is only cleared by a KILL, and classic tennis has none — so the second and every later classic match of a session was silently swallowed by the double-bank guard. beginRun() is the reset now and restartRun calls it. Any future mode with no kills in it needs that path.
• _fine.py used to key EVERY magenta pixel, not just the background — and the generator paints racket strings in the backdrop colour more often than not, so sheet after sheet installed a body holding an empty hoop. Fixed (flood from the border; interior magenta is repainted pale grey), but check a new sheet's rackets anyway. While fixing it: Image.fromarray images are READ-ONLY and PIL's floodfill swallows the write error and returns having filled nothing.
• The regen detail bar RATCHETS against the file being replaced. A repose of art that is already fine (check: 'same') can be rejected for not out-detailing a redraw; 'loose' is the right bar for that job, and resetting the placeholder to the coarse original resets the bar.

The art pipeline

A new opponent FAMILY is now one API call and one script — read PROJECT.md, "THE ZOMBIE FAMILY PIPELINE" before generating one. The one-line version: ask for all 31 figures in a single sheet (one roll, one character, by construction), poses from an existing family and identity from one reference frame with each image's JOB named in the prompt, then assets/_zsheet.py cuts it back down with ONE global scale and ONE global palette.

The older nine-batch flow (_regen.py, _master.py) is still right for single sheets, remasters and the boss roster, and PROJECT.md, "THE ART PIPELINE, corrected" still governs it. Run python3 assets/_regen.py --verify <batches> before trusting any chained batch: it is what proved 27 of the parked brute's 31 frames were never art.

The match opponent's own art is complete — 31 frames, three wound stages, the serve and the fall — and the BRUTE is live beside it (ZFAMS has 'br', the KEEPER wears it), generated by the new path.

Do not

• Re-add regicide to the match (killing the body with a smash) — removed deliberately; it made every hard serve a free unaimed kill and smeared the score-is-the-body relationship.
• Turn drillOneShot on as a default — it skips every ZWOUND stage, so the roster's best art never renders.
• Touch the gore mode's contact/recovery rules while tuning the match. matchReach and the centre-recovery are match-only ON PURPOSE; gore splatter's tight contact and depth-only recovery protect the sidestep.
• Revive the TRIAGE DRILL without a new idea. It is still in the back room and it works exactly as designed, but it failed the only test that matters: "i think the normal player does not grasp this." Four designs died learning that an invented rule needs teaching; the rules a scene already implies do not. That is why the match is tennis.