Hands: realism overhaul (simulation feel, netcode, animation, injuries, presentation)

README.md

@@ -495,7 +495,7 @@ The right stick also performs one punch after a center→peak→center gesture.
 
 ### Presentation and settings
 
-The committed client renders a real-time 3D broadcast presentation with WebGL (pinned three.js): a procedurally modeled arena, canvas-textured ring, a referee, dynamic lighting and shadows, and GPU particle effects—including deliberately over-the-top, full-mode arcade gore—plus generated Web Audio. The fighters use the realistic “Boxer” rig by Texel, Inc. (CC BY 4.0; source, attribution, and modification notice in `web/hands/assets-src/Boxer.LICENSE.txt`) driven by authored clips retarget-baked from the project's own boxing motion (idle, movement, guards, all punches both hands, reactions, knockdown, get-up), phase-locked to the authoritative simulation via combat-manifest.json. All arena meshes, textures, and sounds remain generated in code. **Blood defaults to graphic `full` mode**; Settings can select `full`, `reduced`, or `off` without changing authoritative trauma or HUD information. Settings also provide master audio volume, haptics on/off, and reduced motion. Audio unlocks only after user interaction and suspends while hidden; haptics are feature-detected and limited to bounded authoritative impact events. Reduced motion removes particles/shake while preserving match state and private get-up information.
+The committed client renders a real-time 3D broadcast presentation with WebGL (pinned three.js): a procedurally modeled arena, canvas-textured ring, a referee, dynamic lighting and shadows, and GPU particle effects—including deliberately over-the-top, full-mode arcade gore—plus generated Web Audio. The fighters and the referee use the realistic “Boxer” rig by Texel, Inc. (CC BY 4.0; source, attribution, and modification notice in `web/hands/assets-src/Boxer.LICENSE.txt`) posed at runtime by a two-bone IK solver: planted, stepping feet, punches that extend from the rotated shoulder to the opponent's live head phase-locked to combat-manifest.json timing, spring-damper hit reactions along the incoming punch line, and authored falls and get-ups. Injuries are shaded in object space on the skin materials (bruising, swelling, cuts, flowing blood) and the finishers detach the fighter's actual head or glove mesh. All arena meshes, textures, and sounds remain generated in code. **Blood defaults to graphic `full` mode**; Settings can select `full`, `reduced`, or `off` without changing authoritative trauma or HUD information. Settings also provide master audio volume, haptics on/off, and reduced motion. Coarse-pointer clients (Discord mobile) get on-screen controls: a floating joystick for footwork, punch pads whose left or right half picks the hand, and hold buttons for body, power, and guards. Audio unlocks only after user interaction and suspends while hidden; haptics are feature-detected and limited to bounded authoritative impact events. Reduced motion removes particles/shake while preserving match state and private get-up information.
 
 Before a public release, review Discord's current violent-content rules, age rating/restriction controls, store/application disclosures, and regional requirements. Do not add external/borrowed assets, commercial boxing-game UI, audio, animation traces, real-fighter or celebrity likenesses, sanctioning-body/brand marks, logos, or recognizable trade dress. All fighter art, interface, motion, terminology, and sound must remain original.
 
@@ -600,7 +600,7 @@ git diff --exit-code -- src/intelstream/hands/static
 
 `npm run build` typechecks, writes exactly `index.html`, `assets/hands.js`, and `assets/hands.css` into `src/intelstream/hands/static`, and runs the scanner. Those generated files are committed so production Python installations do not require Node. Change TypeScript/CSS in `web/hands`, rebuild, inspect the output, commit source and generated files together, and require the final `git diff --exit-code` after a clean rebuild. Never hand-edit the generated bundle.
 
-The fixed three-file deployment contract embeds the Boxer rig and its five source textures in `hands.js`; the resulting production script is intentionally about 5.6 MB (about 2.9 MB gzip). This startup-cost tradeoff keeps the Activity self-contained and avoids runtime asset requests.
+The fixed three-file deployment contract embeds the mesh-only Boxer rig and its five source textures (re-encoded as JPEG by the generator) in `hands.js`; the resulting production script is about 2.36 MB (about 1.28 MB gzip). This startup-cost tradeoff keeps the Activity self-contained and avoids runtime asset requests. `scripts/hands_pose_strip.js` renders a pose frozen at a list of times into one frame strip for motion review. `npm run dev` also serves `?model-lab=1&pose=<name>&cam=<angle>&trauma=<light|heavy|cut>` as a pose lab for reviewing the runtime animation and injury shading without a match (poses include punches, guards, slips, knockdown, seated, celebrate and wave_off), and `?fixture=1` with `&finisher=head|hand`, `&phase=rest`, `&pin=1|corner`, `&blood=reduced|off` or `&platform=mobile` for presentation review.
 
 For a standalone presentation fixture, run `npm --prefix web/hands run dev` and open the printed URL with `?fixture=1`. For the real two-process localhost flow, terminal one runs the Python bot/Hands server with valid Discord credentials:
 
@@ -614,6 +614,19 @@ Terminal two runs Vite and proxies HTTP plus WebSocket `/api/hands` requests to
 HANDS_DEV_BACKEND=http://127.0.0.1:8080 npm --prefix web/hands run dev
 ```
 
+### Playing a match locally without Discord
+
+`scripts/hands_e2e_server.py` runs the Hands server with a development auth backend that skips the Discord OAuth steps but keeps the production ticket, room, websocket, engine and persistence code paths:
+
+```bash
+uv run python scripts/hands_e2e_server.py --port 8091 --rounds 1 --round-seconds 45
+HANDS_DEV_BACKEND=http://127.0.0.1:8091 npm --prefix web/hands run dev -- --port 5174
+```
+
+Open `http://localhost:5174/?e2e=1&instance_id=<any id>&player=<name>` in two browser windows (different names) to fight. The `e2e` switch only exists in Vite development builds; the development server authenticates anyone who can reach its port, so never expose it.
+
+`scripts/hands_e2e_scenarios.js` automates this with Playwright: `ko` (power punches until a knockdown, private get-up rhythm, stoppage), `reconnect` (one client drops offline mid-round and resumes), `rest` (two rounds with the corner rest), `spectator` (a third client joins read-only), `touch` (one player on an emulated phone), `mash` (hundreds of key presses per second) `latency` (a TCP proxy delays every frame 110 ms each way, and the clients report their measured input acknowledgement latency, which the fighter HUD also shows) `soak` (a full three-round bout sampling heap size, latency and render scale every twenty seconds) `background` (one player's page is frozen through the DevTools lifecycle state for eight seconds, as a backgrounded phone app would be, then resumed) `rematch` (both players use the Rematch button after the result and fight a second bout in the same instance) `rematchloop` (four bouts back to back while sampling heap size and GPU object counts for leaks) `clinch` (both players close in and one ties up; the harness reads the fighters' separation from the client state through the engine's draw-in, the hold and the referee break) and `response` (key press to first rendered frame for the player's own punch and step, when the opponent sees them, and whether the predicted punch ever jumps back, behind a delay proxy set with `E2E_DELAY_MS`, 60 ms each way by default). It spawns the development server itself and prints the clients' status text plus any client or server errors. The default software renderer keeps runs reproducible on machines without a GPU; set `E2E_GPU=1` to render on the machine's GPU for real frame pacing, input latency and screenshots.
+
 `HANDS_DEV_BACKEND` is a Node/Vite development-process setting, not a browser `VITE_*` value and not a production origin. Real OAuth still needs a valid Activity instance; the fixture is only recorded presentation data. Keep `HANDS_DEV_MODE=false` in production.
 
 ### Wheel/package verification

docs/hands-lab-architecture.md

@@ -347,3 +347,13 @@ the palette toward pastel; trauma overlays are scaled for the larger head but
 their positions are approximate; the knockdown head-fall velocity makes the
 0.10 m joint metric read ~0.22 m one tick after contact (filmstrip shows flush
 contact).
+
+---
+
+# Superseded (2026-09-28)
+
+The clip-based animation graph, the retarget-baked GLB, the marker export, and
+the sphere trauma overlays described above were replaced by the runtime pose
+system, object-space injury shading, and mesh-baked gore documented in
+`docs/hands-realism-plan.md`. The lab route, the golden replay, and the
+acceptance metrics still apply; the protocol is now v3 and the ring is square.

docs/hands-realism-plan.md

@@ -0,0 +1,87 @@
+# Hands realism overhaul
+
+Branch `feature/hands-realism`. Goal: make the Hands Discord Activity a realistic,
+responsive boxing game with injuries and gore, on the existing authoritative
+Python engine, websocket rooms, persistence, and ratings.
+
+## Baseline findings (2026-09-28)
+
+Measured against `origin/main` at 992a4f5 with the dev fixture, the model lab,
+and the engine source.
+
+Simulation and protocol
+
+- Punches only hit along the ring x axis. `_resolve_punch` projects onto the
+  binary `facing` sign, so fighters offset along ring depth whiff while the
+  presentation shows them squared up.
+- A second punch pressed during the first is dropped. `ACTION_BUFFER_TICKS`
+  (6) expires before a 13-tick jab clears, so `pending_actions` is cleared
+  before it can dispatch. There is no recovery cancel, so combos cannot flow.
+- Get-up teleports the downed fighter to `x = +-140`, which the client hides
+  with a 0.85 m slide.
+
+Presentation and network
+
+- Movement stutters at 15 Hz. The renderer samples a fixed `latest.tick - 1`
+  and snapshots arrive every second tick, so the pose holds for about four
+  frames and jumps.
+- Input is polled every 40 ms instead of sent on the key edge, and there is no
+  local movement prediction, so footwork lags by round trip plus polling.
+- Punch, guard, movement, reaction, and knockdown clips are retarget-baked
+  from a capsule rig through direction-only child aim. Elbow and wrist twist
+  are uncontrolled and the knockdown never reaches the canvas.
+- Injuries are colored spheres and boxes parented to the head bone. They
+  float beside the textured face. Gibs are red icosahedra; the severed head is
+  a scaled sphere; the referee is a capsule mannequin.
+- Five 105 cd fill spotlights plus bloom wash the image to pastel and blow out
+  the white rope. The broadcast camera sits 7 m back, so fighters occupy
+  roughly a third of the frame height.
+
+## Plan
+
+1. Simulation feel: continuous facing vector with limited turn rate and a
+   facing-relative hit test; input buffer that survives the current punch;
+   late-recovery combo cancels; knockdown separation by the referee instead of
+   a teleport; protocol v3 carrying `facing_x`, `facing_y`, and the last
+   processed input sequence.
+2. Netcode: continuous render clock with adaptive interpolation delay,
+   30 Hz broadcast, edge-triggered action sends, and local movement prediction
+   for the viewer's fighter.
+3. Animation: a runtime pose system on the Texel skeleton (stance, guards,
+   punches that reach the live target, footwork with planted feet and pivots,
+   spring-damper hit reactions, keyframed falls and get-ups) replacing the
+   retarget-baked clips.
+4. Injuries and gore: face and body damage painted into the skin textures
+   (bruising, cuts, swelling displacement, flowing blood), blood on gloves and
+   canvas, stretched droplet sprites, and mesh-based decapitation and
+   dismemberment for the arcade finishers.
+5. Presentation: closer broadcast framing with impact and knockdown cameras,
+   corrected lighting and exposure, layered impact audio, and a skinned
+   referee.
+
+Every phase lands as its own commits with Python and Vitest coverage, a
+rebuilt committed bundle, and screenshots captured through headless Chromium.
+
+## Status (2026-09-29)
+
+All five phases landed on `feature/hands-realism` (PR #293). Beyond the plan, the branch also
+carries: adaptive render resolution with a no-gain revert, crowd excitement, rest-phase corner
+walk with stools and a cutman who climbs in to work the worse eye (engine + client), anti-parallel
+facing fix, knockout presentation (slow-motion replay, close-up, held result panel, winner
+celebration, referee wave-off), portrait framing with a compact scoreboard, per-round and per-bout
+punch stats, rope flex under a pinned fighter, face-down knockdowns after hooks, a real clinch
+tie-up (the engine draws the fighters to a hold distance; one hooks over, the other under), a
+legible showboat taunt, glove trails on fast punches, a rendered root that follows the engine at a
+fixed speed per second, a broken nose under heavy head trauma, a glove touch before the opening
+bell, a shadow-boxing waiting screen, rematches, plain-language failure text and a copyable
+diagnostics panel.
+
+Review harnesses: `?model-lab=1&pose=...` (pose lab), `?fixture=1` with `&finisher=head|hand`,
+`&phase=rest`, `&pin=1|corner`, `&blood=reduced|off`, `&platform=mobile`, `?lab=1` (golden replay), and the Discord-free
+real-stack harness (`scripts/hands_e2e_server.py` plus `scripts/hands_e2e_scenarios.js` with the
+ko, reconnect, rest, spectator, touch, mash, latency, soak, background, rematch, rematchloop and
+clinch scenarios; see the README).
+
+Considered and not done: starting round 1 from the corners (the engine tests and the golden
+replay schedule assume the centre start). A live Discord Activity launch with the server's players
+still has to happen outside this repository's tooling.