acdream/docs/superpowers/specs/2026-07-07-player-physics-update-verbatim-rebuild-design.md

Design: verbatim rebuild of the per-frame player physics update loop

Date: 2026-07-07 · Status: DESIGN APPROVED (implementation deferred to a fresh session) Driving issue: #182 (player-vs-monster crowd collision) + the airborne "stuck in the falling animation" regression it exposed. Brainstorm decisions (user): verbatim rebuild (highest fidelity); scope = the per-frame update LOOP, keep everything already faithful; stage the velocity model first and measure; do the implementation in a NEW session.

---

1. Problem (from the user, live)

1. Crowd jam — packed in a group of monsters, the player gets stuck and can't push through / wiggle out. Retail lets you shove monsters aside and keep moving.
2. Airborne stuck — jumping up into a crowd, retail lets you land/glide across the monster tops; acdream hangs in the falling animation unable to rise or fall.

The #182 CSphere-family port (committed 96ae2740) was faithful but aimed a layer too low: it fixed the per-contact sphere response, did NOT fix the crowd feel, and introduced the airborne-stuck regression (before #182 the hand-rolled de-penetration shoved the player up onto monsters).

2. Evidence — the traces (the load-bearing part; do not re-derive)

Retail, player-attributed cdb trace (tools/cdb/retail-crowd-jump3.cdb)

Filtered to the local player's CPhysicsObj (captured from set_local_velocity), during a jump-into-a-crowd repro:

pValidate=1482  pCOLLIDED=188 (12.7%)  pSLID=130 (8.8%)  pLand=76   → ~78% OK

• The retail local client fully runs player-vs-creature collision — 76 CSphere::land_on_sphere (airborne creature landings), 188 COLLIDED, 130 SLID — and still nets ~78% OK. NOT server-authoritative. (An earlier v2 unfiltered read of land_on_sphere=0 was a false lead — the attributed trace refuted it.)
• The player glides across / lands on the crowd via local physics.

acdream, ACDREAM_CAPTURE_RESOLVE JSONL capture (same repro, current #182 build)

Of the player's move-intent resolves (2883 of 41832 total):

	acdream	retail
OK (reached target)	50.9%	~78%
partial / slid	26.7%	~9%
stuck (reverted, no advance)	22.4%	~13%
airborne-stuck	115 frames	(glides off)

acdream jams ~2× harder, and the 115 airborne-stuck frames ARE the falling-animation bug. In those frames: velocity (0,0,~18) (a jump), a near-horizontal creature collision normal (e.g. (-0.96,-0.25,-0.15)), the transition reverts (no advance), and the sliding normal flips frame-to-frame — the #137 anti-parallel-absorb wedge.

3. Root divergence (verified against decomp + capture)

Retail CPhysicsObj::UpdateObjectInternal (0x005156b0, pc:283611) recomputes the player's velocity from the ACTUAL collided movement every frame:

newFrame   = UpdatePositionInternal(this, dt)          // integrate velocity + gravity
transition = CPhysicsObj::transition(this, m_position, newFrame, 0)   // collision sweep
if transition == null: set_frame(newFrame); cached_velocity = 0
else:
    offset          = get_offset(m_position, transition.sphere_path.curr_pos)
    cached_velocity = offset / dt          // ← VELOCITY = ACTUAL MOVEMENT / dt  (0x005158cb-005158ff)
    SetPositionInternal(transition)

So when the player is blocked (resolved ≈ old position), cached_velocity → ~0, gravity resumes next frame, and the player falls / settles / glides off the obstacle. The collision naturally bleeds the velocity — there is no reflection step.

acdream uses a different model: PhysicsBody integrates velocity/gravity, then PlayerMovementController (~:1008-1069) reflects the into-wall component on collision (Velocity = v + n·k) and clamps Z on landing. For a straight-up jump into a creature whose collision normal is horizontal, the reflection barely touches +Z, so the jump velocity persists — the player keeps shoving up into the creature and hangs. This is the airborne-stuck, and the same "velocity doesn't bleed on block" shape drives the general 2× jam.

This velocity model is the centerpiece of the fix.

4. Design — verbatim rebuild of the per-frame loop

Port retail's UpdateObjectInternal chain verbatim into a single owner of the per-frame player physics. Reuse the already-faithful transition internals as the collision primitive — do not touch them.

4.1 Retail functions to port (chain of UpdateObjectInternal)

Function	Address	Role
CPhysicsObj::UpdateObjectInternal	0x005156b0	per-frame entry: integrate → transition → commit → velocity
CPhysicsObj::UpdatePositionInternal	(grep)	integrate velocity + gravity + forces → candidate frame
CPhysicsObj::calc_acceleration	0x00510950	gravity / friction / buoyancy
CPhysicsObj::handle_all_collisions	0x00514780	retail's collision velocity response (verify role vs the cached_velocity model)
CPhysicsObj::SetPositionInternal	0x00515330 / 0x00515bd0 / 0x00516040 (3 overloads)	commit the transition's resolved position
CPhysicsObj::transition	(grep)	collision sweep — maps to acdream ResolveWithTransition, reused as-is

4.2 In scope (rebuilt verbatim)

The per-frame player physics loop: velocity + gravity integration (UpdatePositionInternal/calc_acceleration), the transition orchestration (call → commit), the velocity-from-movement recompute (cached_velocity = (resolved − old)/dt), and handle_all_collisions.

4.3 OUT of scope (kept — already faithful, per the user "keep everything faithful")

The transition INTERNALS: ResolveWithTransition and everything under it — BSPQuery, the CSphere/CylSphere collision families (incl. the #182 port), cell membership, terrain, streaming. Retail's transition calls these primitives and so does ours.

4.4 Architecture

A new PhysicsObjUpdater (or a PhysicsBody.UpdateObjectInternal(dt) method) owns the retail chain verbatim. It absorbs: PhysicsBody's ad-hoc gravity/friction integration AND PlayerMovementController's post-resolve bounce/reflect/clamp block (~:1008-1069). PlayerMovementController shrinks to: input → velocity/jump intent → hand off. The retail velocity-from-movement model replaces reflect-and-clamp wholesale. Register a divergence-register row retiring the reflect model + any adaptation rows the port introduces.

4.5 Staging (velocity model first, measured)

• Slice 1: port UpdatePositionInternal + calc_acceleration + the cached_velocity = (resolved−old)/dt recompute, replacing the integrate+reflect path. A/B against the crowd capture: require the airborne-stuck count → 0 and OK% to climb toward retail's ~78%. Gate (suites + a visual pass on ordinary jump/walk/fall) before continuing.
• Slice 2: handle_all_collisions verbatim (once Slice 1 shows what residual the velocity model leaves) + any remaining UpdateObjectInternal orchestration.
• Slice 3+: close the residual ground-jam gap if the velocity model alone doesn't reach ~78% OK; re-measure each slice against the capture.

5. Validation

• Apparatus (built this session, reuse): ACDREAM_CAPTURE_RESOLVE=<path> JSONL of every player resolve; the py histogram (OK / partial / stuck / airborne-stuck; see §2). Retail target: ~78% OK, 12.7% COLLIDED, 8.8% SLID, 0 airborne-stuck. Retail cdb scripts: tools/cdb/retail-crowd-jump{2,3}.cdb (v3 = player-attributed; safe auto-detach via validate_transition terminal + top-level qd).
• Conformance tests: velocity-from-movement (blocked → velocity → ~0); jump + gravity integration; the UpdateObjectInternal sequence; a crowd replay.
• Suites stay green: Core 2603 / App 741 (no regression to walking/stairs/slopes/ walls/streaming — the transition internals are untouched).
• Visual gates: (a) crowd glide/land like retail (the #182 symptom); (b) a regression pass on normal locomotion — flat walking, slopes, stairs, jumping, falling, wall-slide.

6. Risk

Highest-risk option: it replaces the core of every jump/fall/step. Mitigation: the scope boundary (transition internals untouched), the measured slicing (Slice 1 behind an A/B compare), and heavy gating. If Slice 1 regresses ordinary locomotion, bisect within the velocity model before proceeding.

7. Open items for the new session (verify during writing-plans)

1. Read UpdatePositionInternal, calc_acceleration (0x00510950), and handle_all_collisions (0x00514780) fully — confirm the integration + the role of handle_all_collisions vs the cached_velocity model (does retail ALSO reflect, or is velocity purely movement-derived?).
2. Confirm which SetPositionInternal overload the player path uses (3 exist).
3. Decide whether the general ground-jam (22% stuck vs retail 13%) is fully explained by the velocity model or needs a second divergence (de-penetration / sliding-normal provenance — the #137/TS-45 wedge family). Measure after Slice 1.
4. #182 stays as the base (user decision). NOTE: until this rebuild lands, the codebase carries the airborne-stuck regression #182 introduced.

8. Pointers

• Physics/collision SSOT: claude-memory/project_physics_collision_digest.md (updated with the #182 + this-investigation banner).
• #182 issue: docs/ISSUES.md. CSphere pseudocode: docs/research/2026-07-07-csphere-collision-family-pseudocode.md.
• Retail debugger toolchain + the safe-detach recipe: memory/project_retail_debugger.md + CLAUDE.md.