# Player physics per-frame loop — verbatim rebuild — Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Port retail `CPhysicsObj::UpdateObjectInternal`'s velocity/collision chain verbatim into acdream's player per-frame loop so a blocked jump into a monster crowd **bleeds its velocity and glides/lands like retail** (fixes #182's airborne "stuck in the falling animation" regression + halves the general crowd jam), keeping the already-faithful transition internals as the collision primitive.
**Architecture:** The retail per-frame chain is `UpdateObject` (dt sub-step driver) → `UpdateObjectInternal` (integrate candidate → `transition` sweep → commit + `cached_velocity`) → `SetPositionInternal` (commit resolved frame + contact/walkable/sliding flags + `handle_all_collisions`) → `handle_all_collisions` (velocity reflect OR zero, driven by `frames_stationary_fall`). The velocity "bleed on block" is **not** the `cached_velocity` field (a separate reporting/DR value) — it is the `frames_stationary_fall` (fsf) counter: `validate_transition` increments it 0→1→2→3 when the sphere fails to advance and at fsf≥2 manufactures an upward contact plane; `handle_all_collisions` **zeros the velocity when fsf > 1**. acdream reflects but never runs the fsf path (registered as TS-3), so a blocked jump reflects a sliver of +Z and hangs. This rebuild completes the fsf round-trip in the kept transition internals and ports the `SetPositionInternal`/`handle_all_collisions` consumer into the player loop, replacing acdream's ad-hoc reflect/land block.
**Tech Stack:** C# / .NET 10, xUnit. Retail oracle: `docs/research/named-retail/acclient_2013_pseudo_c.txt` (named PDB decomp). Measurement: `ACDREAM_CAPTURE_RESOLVE` JSONL capture + a new Python histogram classifier. A/B target (retail cdb, `tools/cdb/retail-crowd-jump3.cdb`): **~78% OK, 12.7% COLLIDED, 8.8% SLID, 0 airborne-stuck.**
---
## 0. Refinement of the design spec (read before starting)
This plan **refines** `docs/superpowers/specs/2026-07-07-player-physics-update-verbatim-rebuild-design.md`. The design's §7 explicitly deferred verifying the mechanism to "the writing-plans step"; that verification (reading `handle_all_collisions` 0x00514780, `UpdatePhysicsInternal` 0x00510700, and the fsf lifecycle end-to-end) changed the slicing:
| Design said | Verified truth (decomp + capture) | Consequence |
|---|---|---|
| Slice 1 = the `cached_velocity = (resolved−old)/dt` model bleeds velocity → airborne-stuck→0 | `cached_velocity` is a **separate reporting field** read only by `get_velocity` (network/DR/camera), never fed to the integrator (`m_velocityVector`). It does **not** bleed the jump. | The airborne-stuck fix lives in `handle_all_collisions` (`fsf>1 → v=0`), which needs the **fsf round-trip** first. Slices reorder: fsf substrate (Slice 1) → `handle_all_collisions` consumer (Slice 2, the design's "Slice 2", now the load-bearing fix). |
| §7 Q1: does retail reflect, or is velocity purely movement-derived? | Retail does **both**: `fsf≤1` → reflect `v += -(v·n)(elasticity+1)·n`; `fsf>1` → `v=0`. Velocity is `m_velocityVector`-integrated. | Keep `PhysicsBody.Velocity` as `m_velocityVector`; **add a separate `CachedVelocity`** field; do not collapse them. |
| §7 Q2: which `SetPositionInternal` overload | `0x00515330` (single `CTransition` arg) — confirmed from `UpdateObjectInternal:283696`. | Port that overload's contact/walkable/sliding + `handle_all_collisions` sequence. |
| §7 Q3: is the general ground-jam explained by the velocity model, or a second divergence? | Measure after Slice 2. Candidate residual = **TS-4** (BSPQuery Path-6 steep persisted sliding-normal / #137 anti-parallel-absorb) — in the *kept* internals. | Slice 3, only if <~78% OK. Do not touch TS-4 pre-measurement. |
**Out of scope (kept — already faithful, per the user "keep everything faithful"):** the transition INTERNALS below `ResolveWithTransition` — BSPQuery, the CSphere/CylSphere collision families (incl. the #182 port), cell membership, terrain, streaming. The ONE exception is completing the fsf stub inside `ValidateTransition` — that stub **is** "the full physics port" TS-3 was explicitly deferred to; completing it is finishing a known gap, not re-porting working code. **`calc_friction` is out of scope** — it carries an orthogonal threshold divergence (retail 0.25 vs acdream 0.0) whose naive fix regresses walking (L.3c); the fsf fix does not require it. **#182 stays the base** (user decision).
---
## 1. The verified retail chain (the port source — cite these in code comments)
All addresses/pc from `docs/research/named-retail/acclient_2013_pseudo_c.txt`.
### `UpdateObjectInternal(dt)` — 0x005156b0, pc:283611
```
if not active (transient_state high bit clear): update particles/scripts; return
if cell == 0: return
jumped_this_frame = 0
candidate = identity frame
UpdatePositionInternal(dt, &candidate) // integrate → candidate
if part_array has spheres AND candidate.origin != m_position.origin: // moved
(set candidate heading from velocity/motion)
trans = transition(m_position, candidate, 0) // COLLISION SWEEP (== ResolveWithTransition)
if trans == null:
set_frame(candidate); cached_velocity = 0
else:
cached_velocity = (trans.sphere_path.curr_pos − m_position) / dt // 0x005158cb-005158ff
SetPositionInternal(trans) // 0x00515330
else: // no spheres OR didn't move
set_frame(candidate); cached_velocity = 0
// tail: detection / target / movement.UseTime / part.HandleMovement / position.UseTime
```
### `UpdatePositionInternal(dt, &newFrame)` — 0x00512c30, pc:280817
```
delta = identity
part_array.Update(dt, &delta) // animation root motion → delta
if not OnWalkable: delta.translation *= 0 // airborne: no anim translation
else: delta.translation *= m_scale
position_manager.adjust_offset(&delta, dt) // sticky
newFrame = m_position.frame ∘ delta // combine
UpdatePhysicsInternal(dt, &newFrame) // velocity + gravity integration
process_hooks()
```
### `UpdatePhysicsInternal(dt, &newFrame)` — 0x00510700, pc:278460
```
velMag2 = |m_velocityVector|²
if velMag2 > 0:
if velMag2 > 2500 (=50²): m_velocityVector = normalize(m_velocityVector)*50
calc_friction(dt, velMag2)
if (velMag2 − 0.0625 (=0.25²)) <= 0.0002 (F_EPSILON): m_velocityVector = 0 // NOT gated on OnWalkable
newFrame.origin += m_velocityVector*dt + 0.5*accel*dt²
else if movement_manager == null:
if OnWalkable: clear Active bit
m_velocityVector += accel*dt // UNCONDITIONAL (both branches)
newFrame = grotate(newFrame, omega*dt)
```
### `calc_acceleration()` — 0x00510950, pc:278533
```
if Contact(0x1) AND OnWalkable(0x2) AND !(state & 0x800000 SLEDDING): accel=0; omega=0; return
if !(state & 0x400 GRAVITY): accel=0; return
accel = (0,0, gravity(-9.8))
```
### `SetPositionInternal(trans)` — 0x00515330, pc:283399
```
curr_cell = trans.sphere_path.curr_cell
if curr_cell == 0: prepare_to_leave_visibility; store_position; GotoLostCell; clear Active; return 1
if this.cell != curr_cell: change_cell(curr_cell) else: update objcell_id (+children)
set_frame(trans.sphere_path.curr_pos.frame) // COMMIT resolved position
contact_plane = trans.collision_info.contact_plane
contact_plane_cell = trans.collision_info.contact_plane_cell_id
Contact bit(0x1) = trans.collision_info.contact_plane_valid ; calc_acceleration()
Water bit(0x8) = trans.collision_info.contact_plane_is_water
if Contact == 0: clear OnWalkable(0x2); if was OnWalkable: movement.LeaveGround(); calc_acceleration()
else: set_on_walkable(contact_plane.N.z >= floor_z(0.6642))
sliding_normal = trans.collision_info.sliding_normal
Sliding bit(0x4) = trans.collision_info.sliding_normal_valid
handle_all_collisions(trans.collision_info, PREV_Contact, PREV_OnWalkable) // prev = transient_state captured at entry
[if HAS_PHYSICS_BSP(0x10000): calc_cross_cells; else shadow-cell updates]
return 1
```
### `handle_all_collisions(ci, prev_contact, prev_on_walkable)` — 0x00514780, pc:282647
```
should_reflect = !(prev_on_walkable AND OnWalkable AND !(state & SLEDDING)) // var_10_1
[report collision-start for each collided object; report_collision_end; environment-collision report]
fsf = ci.frames_stationary_fall
if fsf <= 1:
if should_reflect AND ci.collision_normal_valid AND !(state & 0x20000 INELASTIC):
dot = m_velocityVector · ci.collision_normal
if dot < 0: m_velocityVector += -(dot*(elasticity+1)) * ci.collision_normal // REFLECT
elif should_reflect AND ci.collision_normal_valid: // INELASTIC
m_velocityVector = 0
else: // fsf > 1
m_velocityVector = 0 // ZERO (the bleed)
// encode fsf → transient bits:
if fsf == 1: transient_state |= 0x10 (StationaryFall)
elif fsf == 2: transient_state |= 0x20 (StationaryStop)
elif fsf == 3: transient_state |= 0x40 (StationaryStuck)
else (fsf==0): transient_state &= ~(0x10|0x20|0x40)
return
```
### fsf counter in `validate_transition` — 0x0050aa70, pc:272625-272656
```
if ci.collision_normal_valid: ci.set_sliding_normal(ci.collision_normal)
if (object_info.state & 4)==0 AND (target_object.state & 0x400 GRAVITY)!=0: // mover-not-frozen AND object has gravity
if moved: ci.frames_stationary_fall = 0 // advanced → reset
else:
if fsf == 0: fsf = 1
elif fsf == 1: fsf = 2
else: fsf = 3 // fsf >= 2 → manufacture UP contact
up = (0,0,1)
d = radius − (global_sphere.center · up) // plane through sphere bottom
ci.set_contact_plane(up, water=0); ci.contact_plane_cell_id = check_pos.objcell_id
if (object_info.state & 1)==0: // not already Contact
ci.set_collision_normal(up); ci.collided_with_environment = 1
```
### fsf seed in `transition` — 0x00512dc0, pc:280940-280947
```
after init_path:
if transient_state & 0x40: fsf = 3
elif transient_state & 0x20: fsf = 2
elif transient_state & 0x10: fsf = 1
```
### `UpdateObject(dt)` sub-step driver — 0x00515d10, pc:283960
```
dt = cur_time − update_time
if dt <= F_EPSILON: update_time = cur_time; return
if dt > 2.0 (HugeQuantum): update_time = cur_time; return
while dt > MaxQuantum: UpdateObjectInternal(MaxQuantum); dt -= MaxQuantum
if dt > 0: UpdateObjectInternal(dt)
update_time = cur_time
```
(acdream already inlines this dt-substep as `_physicsAccum` in `PlayerMovementController` — kept as-is; the L.5 MinQuantum gate is a documented pre-existing adaptation, out of scope.)
---
## 2. acdream current state (the seam being rebuilt)
- **Per-frame method:** `PlayerMovementController.Update(float dt, MovementInput input)` — `src/AcDream.App/Input/PlayerMovementController.cs:542-1302`. Caller: `GameWindow.cs:8454`.
- The retail `UpdateObjectInternal` chain is currently **spread** across: §4 integrate (`:820-877`, `_body.UpdatePhysicsInternal(tickDt)` integrating `Position` **in-place**), §5 resolve (`:879-916`, `_physics.ResolveWithTransition(preIntegratePos, postIntegratePos, …)`), apply (`:931-947`), the ad-hoc reflect block (`:949-1056`), and the landing/airborne block (`:1058-1109`).
- `PhysicsBody` (`src/AcDream.Core/Physics/PhysicsBody.cs`): single `Velocity` field (plays `m_velocityVector`), `calc_acceleration`/`UpdatePhysicsInternal`/`calc_friction`/`set_velocity` ports present. **No `CachedVelocity`.** `TransientStateFlags` = Contact/OnWalkable/Sliding/Active only (**no 0x10/0x20/0x40**). `UpdatePhysicsInternal` has a divergence: the small-velocity-zero at `:503-504` is gated on `OnWalkable` (retail is ungated).
- `ResolveResult` (`src/AcDream.Core/Physics/ResolveResult.cs:21`): `readonly record struct` with `Position, CellId, IsOnGround, CollisionNormalValid, CollisionNormal, Ok`. Rich state (ContactPlane, SlidingNormal) flows back through the passed `body` side-effect (`PhysicsEngine.cs:999-1015` seed-in, `:1056-1106` write-out). **`FramesStationaryFall` is not surfaced.**
- `Transition.ValidateTransition(TransitionState)` — `src/AcDream.Core/Physics/TransitionTypes.cs:4575`. fsf stub at `:4596` (`// moved = true (FramesStationaryFall deferred…)`). "moved" analog = `sp.CheckPos != sp.CurPos` (`:4581`). `CollisionInfo.FramesStationaryFall` field at `:245` (dead). All other retail COLLISIONINFO fields have counterparts.
- **Apparatus:** `PhysicsResolveCapture` (`src/AcDream.Core/Physics/PhysicsResolveCapture.cs`), toggled by `ACDREAM_CAPTURE_RESOLVE`, IsPlayer-filtered at `PhysicsEngine.cs:946`. Baseline capture: `acdream-crowd-resolve.jsonl` (repo root, 41832 lines). No histogram classifier exists yet.
---
## 3. File structure
| File | Change |
|---|---|
| `tools/analyze_resolve_capture.py` | **Create.** Histogram classifier for `ACDREAM_CAPTURE_RESOLVE` JSONL → OK/partial/stuck/airborne-stuck buckets over move-intent records. |
| `src/AcDream.Core/Physics/PhysicsBody.cs` | Add `StationaryFall/Stop/Stuck` flags; add `FramesStationaryFall` + `CachedVelocity` fields; remove the OnWalkable gate on the small-velocity-zero. |
| `src/AcDream.Core/Physics/TransitionTypes.cs` | Un-stub the fsf ladder in `ValidateTransition` (`:4575`); add fsf increment/reset + fsf≥2 UP-plane manufacture. |
| `src/AcDream.Core/Physics/PhysicsEngine.cs` | `ResolveWithTransition`: seed `ci.FramesStationaryFall` from `body` transient bits at entry; write `ci.FramesStationaryFall → body.FramesStationaryFall` at exit. |
| `src/AcDream.App/Input/PlayerMovementController.cs` | Replace the ad-hoc reflect/land block (`:949-1109`) with the ported `SetPositionInternal`+`handle_all_collisions` sequence; compute `CachedVelocity`. |
| `src/AcDream.Core/Physics/PhysicsObjUpdate.cs` | **Create.** Static/pure port of `SetPositionInternal` + `handle_all_collisions` operating on a `PhysicsBody` + a resolve outcome, unit-testable in Core without the App layer. |
| `docs/architecture/retail-divergence-register.md` | Retire TS-3; amend AD-25 (split off the player half); add any new adaptation rows. |
| `tests/AcDream.Core.Tests/Physics/*` | New conformance tests: fsf ladder, `handle_all_collisions` reflect/zero, crowd-jump replay against the capture. |
---
## Task 1: Author the resolve-capture histogram classifier (Slice 0 — measurement)
**Files:**
- Create: `tools/analyze_resolve_capture.py`
- [ ] **Step 1: Write the classifier**
Record schema (camelCase JSON, one per line): `input.{currentPos,targetPos,cellId,...}`, `bodyBefore` / `bodyAfter` (`PhysicsBodySnapshot`, incl. `velocity`, `slidingNormal`, `transientState`), `result.{position,cellId,isOnGround,collisionNormalValid,collisionNormal}`. Vector3 = `{x,y,z}`.
```python
#!/usr/bin/env python3
"""Classify ACDREAM_CAPTURE_RESOLVE JSONL into OK / partial / stuck / airborne-stuck.
Buckets (move-intent records only, i.e. targetPos != currentPos):
OK reached target: dist(result.position, targetPos) <= EPS_REACH
partial advanced short: moved > EPS_MOVE and not OK
stuck reverted: moved <= EPS_MOVE (requested motion, none delivered)
airborne-stuck subset of stuck: bodyBefore airborne with jump velocity into a
near-horizontal collision normal (the falling-animation wedge)
Retail target (retail-crowd-jump3.cdb): ~78% OK, 12.7% COLLIDED, 8.8% SLID, 0 airborne-stuck.
"""
import sys, json, math
EPS_REACH = 0.02 # 2 cm — "reached target"
EPS_MOVE = 0.01 # 1 cm — "advanced at all"
JUMP_VZ = 5.0 # bodyBefore.velocity.z above this = a jump/airborne launch
HORIZ_NZ = 0.5 # |collisionNormal.z| below this = near-horizontal (creature side)
def d(a, b):
return math.sqrt((a["x"]-b["x"])**2 + (a["y"]-b["y"])**2 + (a["z"]-b["z"])**2)
def classify(rec):
i = rec["input"]
if d(i["targetPos"], i["currentPos"]) <= EPS_MOVE:
return None # zero-motion rest tick — not a move-intent record
r = rec["result"]
moved = d(r["position"], i["currentPos"])
reached = d(r["position"], i["targetPos"]) <= EPS_REACH
if reached:
return "ok"
if moved > EPS_MOVE:
return "partial"
# reverted / stuck
bb = rec.get("bodyBefore") or {}
vel = bb.get("velocity") or {"x":0,"y":0,"z":0}
n = r.get("collisionNormal") or {"x":0,"y":0,"z":0}
airborne_jump = vel["z"] > JUMP_VZ
horiz_normal = r.get("collisionNormalValid") and abs(n["z"]) < HORIZ_NZ
if airborne_jump and horiz_normal:
return "airborne-stuck"
return "stuck"
def main(path):
counts = {"ok":0, "partial":0, "stuck":0, "airborne-stuck":0}
total_move = 0
with open(path, "r", encoding="utf-8") as f:
for line in f:
line = line.strip()
if not line:
continue
try:
rec = json.loads(line)
except json.JSONDecodeError:
continue
c = classify(rec)
if c is None:
continue
total_move += 1
# airborne-stuck is a subset of stuck for the bucket table but we
# report it separately AND fold it under stuck for the % columns.
if c == "airborne-stuck":
counts["airborne-stuck"] += 1
counts["stuck"] += 1
else:
counts[c] += 1
if total_move == 0:
print("no move-intent records"); return
print(f"move-intent resolves: {total_move}")
for k in ("ok", "partial", "stuck"):
print(f" {k:16s} {counts[k]:6d} {100.0*counts[k]/total_move:5.1f}%")
print(f" {'airborne-stuck':16s} {counts['airborne-stuck']:6d} (frames; subset of stuck)")
print("retail target: ok ~78% partial ~9% stuck ~13% airborne-stuck 0")
if __name__ == "__main__":
main(sys.argv[1] if len(sys.argv) > 1 else "acdream-crowd-resolve.jsonl")
```
- [ ] **Step 2: Validate against the existing baseline**
Run: `py tools/analyze_resolve_capture.py acdream-crowd-resolve.jsonl`
Expected: `move-intent resolves: ~2883`; buckets approximately `ok ~50.9% partial ~26.7% stuck ~22.4% airborne-stuck ~115` — i.e. it reproduces the design §2 acdream column. If the counts diverge materially from the design's numbers, tune `EPS_REACH` / `JUMP_VZ` until the classifier matches the design's hand-derived figures (the design numbers are the ground truth for the classifier's calibration). Record the exact calibrated numbers as the "before" baseline.
- [ ] **Step 3: Commit**
```bash
git add tools/analyze_resolve_capture.py
git commit -m "tools(#182): resolve-capture histogram classifier (A/B baseline for the physics rebuild)"
```
---
## Task 2: PhysicsBody — fsf state, CachedVelocity, and the ungated small-velocity-zero (Slice 1a)
**Files:**
- Modify: `src/AcDream.Core/Physics/PhysicsBody.cs`
- Test: `tests/AcDream.Core.Tests/Physics/PhysicsBodyTests.cs`
- [ ] **Step 1: Write failing tests**
```csharp
[Fact]
public void TransientStateFlags_HasStationaryBits()
{
Assert.Equal(0x10u, (uint)TransientStateFlags.StationaryFall);
Assert.Equal(0x20u, (uint)TransientStateFlags.StationaryStop);
Assert.Equal(0x40u, (uint)TransientStateFlags.StationaryStuck);
}
[Fact]
public void UpdatePhysicsInternal_ZeroesSmallVelocity_EvenWhenAirborne()
{
// Retail UpdatePhysicsInternal (0x00510700) zeroes velocity below 0.25 m/s
// regardless of OnWalkable; gravity re-accelerates the same frame via v += a*dt.
var b = new PhysicsBody { State = PhysicsStateFlags.Gravity };
b.TransientState = TransientStateFlags.None; // airborne
b.set_velocity(new Vector3(0.1f, 0f, 0f)); // < 0.25 m/s, no OnWalkable
b.Acceleration = new Vector3(0, 0, PhysicsBody.Gravity);
b.UpdatePhysicsInternal(1f / 30f);
// horizontal velocity was zeroed; only gravity (v += a*dt) remains on Z
Assert.True(MathF.Abs(b.Velocity.X) < 1e-4f);
Assert.True(b.Velocity.Z < 0f);
}
```
Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~PhysicsBodyTests.TransientStateFlags_HasStationaryBits"`
Expected: FAIL (flags undefined / compile error).
- [ ] **Step 2: Add the flags, fields, and fix the gate**
In `PhysicsBody.cs`, extend `TransientStateFlags` (retail transient_state bits, `handle_all_collisions` pc:282743/282749/282753):
```csharp
[Flags]
public enum TransientStateFlags : uint
{
None = 0,
Contact = 0x00000001, // bit 0 — touching any surface
OnWalkable = 0x00000002, // bit 1 — standing on a walkable surface
Sliding = 0x00000004, // bit 2 — carry sliding normal into next transition
// retail frames_stationary_fall carried across frames (transition seeds fsf from
// these; handle_all_collisions re-encodes fsf into them). pc:282743/272940.
StationaryFall = 0x00000010, // bit 4 — fsf == 1
StationaryStop = 0x00000020, // bit 5 — fsf == 2
StationaryStuck= 0x00000040, // bit 6 — fsf == 3
Active = 0x00000080, // bit 7 — object needs per-frame update
}
```
Add fields near `Velocity` (`:183`):
```csharp
/// Retail cached_velocity (+separate from m_velocityVector): the REALIZED
/// velocity (resolved displacement / dt) written after each transition in
/// UpdateObjectInternal (0x005158cb-005158ff). Read only for reporting / dead-reckoning /
/// camera slope-align (get_velocity 0x005113c0); NEVER fed back into the integrator.
public Vector3 CachedVelocity { get; set; }
/// Retail collision_info.frames_stationary_fall carried on the body between
/// frames. Incremented in ValidateTransition when the sphere fails to advance, consumed by
/// handle_all_collisions (fsf>1 → velocity zeroed). Round-trips via the Stationary* transient
/// bits. validate_transition pc:272625-656; handle_all_collisions pc:282695.
public int FramesStationaryFall { get; set; }
```
In `UpdatePhysicsInternal` (`:503-504`), remove the OnWalkable gate (retail zeros regardless — gravity re-accelerates via the unconditional `v += a*dt`):
```csharp
// Retail UpdatePhysicsInternal 0x005107be: zero velocity below 0.25 m/s
// UNCONDITIONALLY (not gated on OnWalkable). At jump apex this zeros the
// horizontal drift; the unconditional `Velocity += Acceleration*dt` below
// immediately re-applies gravity, so the fall still accumulates.
if (velocityMag2 - SmallVelocitySquared < 0.0002f)
Velocity = Vector3.Zero;
```
Run: `dotnet test ... --filter "FullyQualifiedName~PhysicsBodyTests"`
Expected: PASS (both new tests + the existing suite).
- [ ] **Step 3: Commit**
```bash
git add src/AcDream.Core/Physics/PhysicsBody.cs tests/AcDream.Core.Tests/Physics/PhysicsBodyTests.cs
git commit -m "feat(#182): PhysicsBody fsf state + CachedVelocity; ungate small-velocity-zero (verbatim UpdatePhysicsInternal)"
```
---
## Task 3: Complete the fsf ladder in ValidateTransition (Slice 1b — the kept-internals stub, retiring TS-3's behavior gap)
**Files:**
- Modify: `src/AcDream.Core/Physics/TransitionTypes.cs` (`ValidateTransition` `:4575`; the `moved` signal at `:4581`)
- Test: `tests/AcDream.Core.Tests/Physics/FramesStationaryFallTests.cs` (create)
- [ ] **Step 1: Write failing tests for the fsf ladder in isolation**
The ladder is: given a `Transition` whose step did/did not advance, and whose target has gravity, `ValidateTransition` increments/resets `collision_info.FramesStationaryFall` and at fsf≥2 manufactures an upward contact plane. Test via a minimal `Transition` with a controllable `SpherePath` (CheckPos == or != CurPos) and `ObjectInfo` with the gravity flag.
```csharp
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;
public class FramesStationaryFallTests
{
// Build a Transition whose ValidateTransition input state is OK, with CheckPos
// == CurPos (did NOT advance) so the fsf ladder increments. Helper mirrors the
// FindTransitionalPosition setup used by CellarUpTrajectoryReplayTests.
static Transition BlockedGravityTransition(int seedFsf)
{
var t = TestTransitionFactory.GravityMover(radius: 0.48f); // see Step 2 helper
t.CollisionInfo.FramesStationaryFall = seedFsf;
t.SpherePath.SetCheckPos(t.SpherePath.CurPos, t.SpherePath.CurCellId); // no advance
return t;
}
[Theory]
[InlineData(0, 1)]
[InlineData(1, 2)]
[InlineData(2, 3)]
[InlineData(3, 3)] // saturates at 3
public void ValidateTransition_Blocked_IncrementsFsf(int seed, int expected)
{
var t = BlockedGravityTransition(seed);
t.ValidateTransition(TransitionState.OK);
Assert.Equal(expected, t.CollisionInfo.FramesStationaryFall);
}
[Fact]
public void ValidateTransition_Blocked_AtFsf2_ManufacturesUpContactPlane()
{
var t = BlockedGravityTransition(seedFsf: 2); // will become 3 → manufacture
t.ValidateTransition(TransitionState.OK);
Assert.True(t.CollisionInfo.ContactPlaneValid);
Assert.True(t.CollisionInfo.ContactPlane.Normal.Z > 0.99f); // UP
Assert.True(t.CollisionInfo.CollidedWithEnvironment);
}
[Fact]
public void ValidateTransition_Advanced_ResetsFsf()
{
var t = TestTransitionFactory.GravityMover(radius: 0.48f);
t.CollisionInfo.FramesStationaryFall = 3;
// CheckPos advanced beyond CurPos → moved == true
t.SpherePath.CheckPos = t.SpherePath.CurPos with { /* origin += (1,0,0) */ };
t.ValidateTransition(TransitionState.OK);
Assert.Equal(0, t.CollisionInfo.FramesStationaryFall);
}
}
```
Run: `dotnet test ... --filter "FullyQualifiedName~FramesStationaryFallTests"`
Expected: FAIL (fsf never changes — stub).
- [ ] **Step 2: Add the `TestTransitionFactory.GravityMover` helper**
If no reusable factory exists, add a minimal one in the test project that builds a `Transition` with a `SpherePath` (one sphere radius r at a known CurPos/CurCellId), an `ObjectInfo` whose `State` includes the gravity flag and whose `object.State` sets `PhysicsStateFlags.Gravity`, matching what `FindTransitionalPosition` sets up. Mirror the setup in `CellarUpTrajectoryReplayTests.cs:1252-1297` (`SimulateTicks`). Keep it in `tests/.../Physics/TestTransitionFactory.cs`.
- [ ] **Step 3: Implement the fsf ladder in `ValidateTransition`**
At `TransitionTypes.cs:4581-4597`, replace the stub. Compute `moved` from the retail `arg3` semantics (advanced this call). Then, gated on retail's condition (`(object_info.State & VIEWER/frozen)==0 && object-has-gravity`), run the ladder. Cite pc:272625-272656.
```csharp
// retail validate_transition arg3 == "advanced this step". Our analog: CheckPos moved
// off CurPos on the OK path (pc:272608 accept-move block). Capture it BEFORE the accept
// overwrites CurPos.
bool moved = transitionState == TransitionState.OK && sp.CheckPos != sp.CurPos;
if (transitionState == TransitionState.OK && sp.CheckPos != sp.CurPos)
{
sp.CurPos = sp.CheckPos; sp.CurCellId = sp.CheckCellId; sp.CurOrientation = sp.CheckOrientation;
for (int i = 0; i < sp.NumSphere; i++)
sp.GlobalCurrCenter[i].Origin = sp.LocalSphere[i].Origin + sp.CurPos; // cache_global_curr_center
sp.SetCheckPos(sp.CurPos, sp.CurCellId);
}
// ── frames_stationary_fall ladder (retail validate_transition pc:272625-272656) ──
// Gate: the mover is not frozen (object_info state bit 4 clear) AND the tested object
// has gravity (state 0x400). VIEWER camera sweeps + gravity-less props are exempt.
if (!ObjectInfo.HasFrozenBit && ObjectInfo.ObjectHasGravity)
{
if (moved)
{
CollisionInfo.FramesStationaryFall = 0; // advanced → reset
}
else
{
int fsf = CollisionInfo.FramesStationaryFall;
if (fsf == 0) CollisionInfo.FramesStationaryFall = 1;
else if (fsf == 1) CollisionInfo.FramesStationaryFall = 2;
else
{
CollisionInfo.FramesStationaryFall = 3; // fsf >= 2 → manufacture UP contact
var up = Vector3.UnitZ;
// plane through the sphere bottom: d = radius - (center · up) (pc:272639-272643)
var gs = sp.GlobalSphere[0];
float d = gs.Radius - Vector3.Dot(gs.Center, up);
CollisionInfo.SetContactPlane(new System.Numerics.Plane(up, d), isWater: false);
CollisionInfo.ContactPlaneCellId = sp.CheckPos.ObjCellId;
if (!ObjectInfo.HasContactBit) // not already Contact (state & 1 == 0)
{
CollisionInfo.SetCollisionNormal(up);
CollisionInfo.CollidedWithEnvironment = true;
}
}
}
}
```
Add the `ObjectInfo` accessors used above (`HasFrozenBit`, `ObjectHasGravity`, `HasContactBit`) if absent, reading the retail `object_info.state` / `object.state` bits (frozen = bit 2 of object_info.state per pc:272625 `& 4`; gravity = object state `0x400`; contact = object state `& 1`). Confirm exact acdream field names against `ObjectInfo` in `TransitionTypes.cs`; wire from `PhysicsBody.State` / `TransientState` at `get_object_info` seed time.
Run: `dotnet test ... --filter "FullyQualifiedName~FramesStationaryFallTests"` → PASS. Then full Core suite → green.
- [ ] **Step 4: Commit**
```bash
git add src/AcDream.Core/Physics/TransitionTypes.cs tests/AcDream.Core.Tests/Physics/FramesStationaryFallTests.cs tests/AcDream.Core.Tests/Physics/TestTransitionFactory.cs
git commit -m "feat(#182): un-stub frames_stationary_fall ladder in ValidateTransition (retail 0x0050aa70; addresses TS-3 behavior gap)"
```
---
## Task 4: Round-trip fsf through PhysicsEngine.ResolveWithTransition (Slice 1c)
**Files:**
- Modify: `src/AcDream.Core/Physics/PhysicsEngine.cs` (`ResolveWithTransition` seed-in `~:999`, write-out `~:1056-1106`)
- Test: `tests/AcDream.Core.Tests/Physics/ResolveFsfRoundTripTests.cs` (create)
- [ ] **Step 1: Write failing test**
```csharp
[Fact]
public void ResolveWithTransition_SeedsAndWritesBackFsf()
{
var engine = TestPhysics.EmptyEngine(); // no landblock → NO-LANDBLOCK verbatim branch
var body = new PhysicsBody { State = PhysicsStateFlags.Gravity };
body.TransientState |= TransientStateFlags.StationaryStop; // fsf seed == 2
// A blocked-in-place move against a wall so the sphere can't advance is needed to
// increment; for the seed/writeback round-trip a zero-distance resolve suffices to
// prove the seed reaches ci and ci.fsf is written back to body.
engine.ResolveWithTransition(body.Position, body.Position, body.CellPosition.ObjCellId,
0.48f, 1.835f, 0.6f, 1.5f, isOnGround: false, body: body,
moverFlags: ObjectInfoState.IsPlayer);
// seed 0x20 → fsf 2 carried in; a zero-distance no-op resolve leaves it (no advance,
// but the NO-LANDBLOCK branch may reset). Assert the field is now populated on body.
Assert.True(body.FramesStationaryFall >= 0); // tighten once the branch behavior is pinned
}
```
(Refine the assertion once the exact seed/branch interaction is observed — the load-bearing behavior is proven end-to-end by Task 7's crowd replay; this test guards the plumbing exists.)
- [ ] **Step 2: Implement seed-in + write-out**
At the top of `ResolveWithTransition` where the `Transition`/`CollisionInfo` is initialized (near where `body` seeds ContactPlane in, `~:999`), seed fsf from the body's carried transient bits (retail `transition` 0x00512dc0 pc:280940-947):
```csharp
if (body is not null)
{
// retail transition() seeds collision_info.frames_stationary_fall from the carried
// Stationary* transient bits before find_valid_position. pc:280940-280947.
if (body.TransientState.HasFlag(TransientStateFlags.StationaryStuck)) ci.FramesStationaryFall = 3;
else if (body.TransientState.HasFlag(TransientStateFlags.StationaryStop)) ci.FramesStationaryFall = 2;
else if (body.TransientState.HasFlag(TransientStateFlags.StationaryFall)) ci.FramesStationaryFall = 1;
else ci.FramesStationaryFall = 0;
}
```
At the exit write-back (near `body.SlidingNormal = …`, `~:1106`), publish fsf onto the body so the App-layer consumer can read it:
```csharp
if (body is not null)
body.FramesStationaryFall = ci.FramesStationaryFall;
```
Run: `dotnet test ... --filter "FullyQualifiedName~ResolveFsfRoundTripTests"` → PASS. Full Core suite → green (no behavior change to locomotion: fsf=0 dormant).
- [ ] **Step 3: Commit**
```bash
git add src/AcDream.Core/Physics/PhysicsEngine.cs tests/AcDream.Core.Tests/Physics/ResolveFsfRoundTripTests.cs
git commit -m "feat(#182): round-trip frames_stationary_fall through ResolveWithTransition (seed from transient bits, write back to body)"
```
---
## Task 5: Port SetPositionInternal + handle_all_collisions into a pure Core unit (Slice 2a)
**Files:**
- Create: `src/AcDream.Core/Physics/PhysicsObjUpdate.cs`
- Test: `tests/AcDream.Core.Tests/Physics/HandleAllCollisionsTests.cs`
- [ ] **Step 1: Write failing tests for the reflect/zero decision**
```csharp
public class HandleAllCollisionsTests
{
static PhysicsBody Airborne(Vector3 v) => new PhysicsBody {
State = PhysicsStateFlags.Gravity, TransientState = TransientStateFlags.None, Velocity = v };
[Fact]
public void Fsf0_AirborneWallHit_ReflectsIntoWallComponent()
{
var b = Airborne(new Vector3(3f, 0f, 0f)); // moving +X into a -X wall
var n = new Vector3(-1f, 0f, 0f); // outward normal
PhysicsObjUpdate.HandleAllCollisions(b, framesStationaryFall: 0,
collisionNormalValid: true, collisionNormal: n,
prevContact: false, prevOnWalkable: false, nowOnWalkable: false);
// dot = 3*-1 = -3 < 0 → v += -(-3*(0.05+1))*(-1,0,0) = v + (-3.15,0,0) → x ≈ -0.15
Assert.True(b.Velocity.X < 0f);
}
[Fact]
public void Fsf2_ZeroesVelocity_TheBleed()
{
var b = Airborne(new Vector3(0f, 0f, 18f)); // straight-up jump
var n = new Vector3(-0.96f, -0.25f, -0.15f); // near-horizontal creature normal
PhysicsObjUpdate.HandleAllCollisions(b, framesStationaryFall: 2,
collisionNormalValid: true, collisionNormal: n,
prevContact: false, prevOnWalkable: false, nowOnWalkable: false);
Assert.Equal(Vector3.Zero, b.Velocity); // fsf>1 → v=0 → gravity resumes → glide off
}
[Fact]
public void StayingOnWalkable_DoesNotReflect()
{
var b = new PhysicsBody { Velocity = new Vector3(3f,0f,0f),
TransientState = TransientStateFlags.Contact | TransientStateFlags.OnWalkable };
var n = new Vector3(-1f,0f,0f);
PhysicsObjUpdate.HandleAllCollisions(b, framesStationaryFall: 0,
collisionNormalValid: true, collisionNormal: n,
prevContact: true, prevOnWalkable: true, nowOnWalkable: true);
Assert.Equal(3f, b.Velocity.X); // should_reflect == false → corridor wall-slide unchanged
}
[Fact]
public void Fsf_EncodesIntoTransientBits()
{
var b = Airborne(new Vector3(0,0,1f));
PhysicsObjUpdate.HandleAllCollisions(b, framesStationaryFall: 3,
collisionNormalValid: false, collisionNormal: default,
prevContact: false, prevOnWalkable: false, nowOnWalkable: false);
Assert.True(b.TransientState.HasFlag(TransientStateFlags.StationaryStuck));
}
}
```
Run → FAIL (type missing).
- [ ] **Step 2: Implement the port**
```csharp
using System.Numerics;
namespace AcDream.Core.Physics;
///
/// Verbatim port of the collision-response tail of retail CPhysicsObj::UpdateObjectInternal:
/// SetPositionInternal (0x00515330) → handle_all_collisions (0x00514780). Pure functions over
/// a PhysicsBody + the resolve outcome, so the whole chain is unit-testable in Core without the
/// App per-frame loop. The transition INTERNALS (ResolveWithTransition and below) are untouched.
///
public static class PhysicsObjUpdate
{
///
/// retail handle_all_collisions (0x00514780, pc:282647). Reflects or zeros the body's
/// velocity based on frames_stationary_fall, then re-encodes fsf into the Stationary*
/// transient bits. This is the velocity "bleed on block": fsf>1 → velocity = 0.
///
public static void HandleAllCollisions(
PhysicsBody body, int framesStationaryFall,
bool collisionNormalValid, Vector3 collisionNormal,
bool prevContact, bool prevOnWalkable, bool nowOnWalkable)
{
// var_10_1 (pc:282653-282657): reflect UNLESS staying on walkable ground (and not
// sledding). Restores retail's broader rule — acdream's AD-25 airborne-only
// suppression is retired (the landing-snap fragility it guarded is gone: the landing
// state is now owned by ApplyResolvedPosition below, not a Velocity.Z<=0 gate).
bool sledding = body.State.HasFlag(PhysicsStateFlags.Sledding);
bool shouldReflect = !(prevOnWalkable && nowOnWalkable && !sledding);
if (framesStationaryFall <= 1)
{
if (shouldReflect && collisionNormalValid)
{
if (body.State.HasFlag(PhysicsStateFlags.Inelastic))
{
body.Velocity = Vector3.Zero; // pc:282720-282722
}
else
{
float dot = Vector3.Dot(body.Velocity, collisionNormal);
if (dot < 0f) // moving into surface
{
float k = -(dot * (body.Elasticity + 1f)); // pc:282712
body.Velocity += collisionNormal * k;
}
}
}
}
else
{
body.Velocity = Vector3.Zero; // fsf>1 → THE BLEED (pc:282729)
}
// encode fsf → transient bits (pc:282737-282758)
body.TransientState &= ~(TransientStateFlags.StationaryFall
| TransientStateFlags.StationaryStop
| TransientStateFlags.StationaryStuck);
body.TransientState |= framesStationaryFall switch
{
1 => TransientStateFlags.StationaryFall,
2 => TransientStateFlags.StationaryStop,
3 => TransientStateFlags.StationaryStuck,
_ => TransientStateFlags.None,
};
_ = prevContact; // reserved for report_environment_collision parity (weenie events, later)
}
}
```
Run → PASS. Commit.
- [ ] **Step 3: Commit**
```bash
git add src/AcDream.Core/Physics/PhysicsObjUpdate.cs tests/AcDream.Core.Tests/Physics/HandleAllCollisionsTests.cs
git commit -m "feat(#182): port handle_all_collisions (reflect/zero by frames_stationary_fall) as a pure Core unit"
```
---
## Task 6: Wire the ported chain into PlayerMovementController, replacing the ad-hoc reflect/land block (Slice 2b — the behavioral fix)
**Files:**
- Modify: `src/AcDream.App/Input/PlayerMovementController.cs` (`:931-1109`)
- Test: `tests/AcDream.App.Tests/` (a controller-level test if the harness exists; otherwise rely on Task 7's Core replay + the visual gate)
- [ ] **Step 1: Compute CachedVelocity and route the response through PhysicsObjUpdate**
Replace the apply/reflect/land block (`:931-1109`). New sequence (retail `UpdateObjectInternal` tail + `SetPositionInternal`):
```csharp
// ── Apply the resolve as retail UpdateObjectInternal does (0x005156b0) ──
// cached_velocity = realized displacement / dt (separate from the integrator velocity;
// reporting/DR only). pc:005158cb-005158ff.
if (physicsTickRan && tickDt > 0f)
_body.CachedVelocity = (resolveResult.Position - preIntegratePos) / tickDt;
else
_body.CachedVelocity = Vector3.Zero;
_body.Position = resolveResult.Position;
if (physicsTickRan)
{
_prevPhysicsPos = oldTickEndPos;
_currPhysicsPos = _body.Position;
PositionManager?.UseTime(); // retail UpdateObjectInternal tail (R5-V3, keep)
}
// SetPositionInternal (0x00515330): set contact/walkable from the resolved contact plane,
// then handle_all_collisions. The contact plane + fsf were written onto _body by
// ResolveWithTransition. prevContact/prevOnWalkable are captured BEFORE this block mutates them.
bool prevContact = _body.InContact;
bool prevOnWalkable = _body.OnWalkable;
// Contact bit from contact_plane_valid; then walkable from the plane's slope. (pc:283468-283510)
if (_body.ContactPlaneValid)
{
_body.TransientState |= TransientStateFlags.Contact;
bool walkable = _body.ContactPlane.Normal.Z >= PhysicsGlobals.FloorZ; // set_on_walkable
if (walkable) _body.TransientState |= TransientStateFlags.OnWalkable;
else _body.TransientState &= ~TransientStateFlags.OnWalkable;
}
else
{
bool wasOnWalkable = _body.OnWalkable;
_body.TransientState &= ~(TransientStateFlags.Contact | TransientStateFlags.OnWalkable);
if (wasOnWalkable) _motion.LeaveGround(); // retail movement_manager->LeaveGround (pc:283494)
}
_body.calc_acceleration();
bool nowOnWalkable = _body.OnWalkable;
PhysicsObjUpdate.HandleAllCollisions(
_body, _body.FramesStationaryFall,
resolveResult.CollisionNormalValid, resolveResult.CollisionNormal,
prevContact, prevOnWalkable, nowOnWalkable);
// Motion-manager notifications on the grounded/airborne EDGES (acdream keeps these — they
// are the CMotionInterp HitGround/LeaveGround hooks the retail chain drives elsewhere).
bool justLanded = false;
if (nowOnWalkable && !_wasAirborneLastFrame == false /* was airborne */ )
{
// wasAirborne && nowOnWalkable → land
}
if (nowOnWalkable && _wasAirborneLastFrame)
{
Movement.HitGround();
justLanded = true;
}
if (!nowOnWalkable && !_wasAirborneLastFrame)
_motion.LeaveGround();
_wasAirborneLastFrame = !nowOnWalkable;
UpdateCellId(resolveResult.CellId, "resolver");
```
> **Integration note (verify while writing):** the old block used `resolveResult.IsOnGround` + a `Velocity.Z <= 0` gate to decide landing and to zero `Velocity.Z`. The rebuild derives grounded state from `_body.ContactPlaneValid`/`OnWalkable` (set by `ResolveWithTransition`'s writeback), not `IsOnGround`, and no longer zeros `Velocity.Z` by hand — `handle_all_collisions` (fsf) + `calc_acceleration` (grounded → accel 0) own the settle. Keep `justLanded` feeding whatever downstream (`§6 outbound`, animation) consumed it. Preserve the HitGround-on-land / LeaveGround-on-depart edges exactly; only their *trigger* changes from `IsOnGround && v.z<=0` to `OnWalkable` transitions.
- [ ] **Step 2: Build + full suites**
Run: `dotnet build` (green), then `dotnet test` (Core + App + UI + Net). Expected: green — ordinary locomotion is fsf=0 dormant; the changed landing trigger must not regress the walk/slope/stairs/jump/fall conformance tests. If any locomotion test regresses, bisect within this task (the landing-trigger change is the prime suspect).
- [ ] **Step 3: Commit**
```bash
git add src/AcDream.App/Input/PlayerMovementController.cs
git commit -m "feat(#182): route player collision response through ported SetPositionInternal+handle_all_collisions (retires the ad-hoc reflect/land block)"
```
---
## Task 7: Crowd-jump A/B replay conformance test (Slice 2c — measured proof)
**Files:**
- Test: `tests/AcDream.Core.Tests/Physics/Issue182CrowdJumpReplayTests.cs` (create)
- Fixture: a trimmed slice of `acdream-crowd-resolve.jsonl` covering the airborne-stuck frames → `tests/AcDream.Core.Tests/Fixtures/issue182/crowd-airborne-stuck.jsonl`
- [ ] **Step 1: Write the replay test (pattern from CellarUpTrajectoryReplayTests)**
Seed a `PhysicsBody` from a captured `bodyBefore` at the first airborne-stuck frame (`velocity ≈ (0,0,18)`, near-horizontal collision normal), then drive the ported per-frame chain (Resolve → PhysicsObjUpdate) for N frames and assert the body **leaves the stuck state**: `FramesStationaryFall` climbs past 1 → `Velocity` collapses to ~0 → subsequent frames show downward Z (gravity/glide), not a persisted +Z. Use `SeedBodyFromSnapshot` + `LoadCapturedRecord` from the existing harness.
```csharp
[Fact]
public void BlockedAirborneJump_BleedsVelocity_WithinThreeFrames()
{
var rec = LoadCapturedRecord(r => r.BodyBefore is { } b && b.Velocity.Z > 15f
&& r.Result.CollisionNormalValid && MathF.Abs(r.Result.CollisionNormal.Z) < 0.5f);
var body = SeedBodyFromSnapshot(rec.BodyBefore);
// simulate the blocked frames against the same captured target — the sphere cannot
// advance, so fsf climbs 0→1→2 and handle_all_collisions zeros velocity at fsf>1.
for (int frame = 0; frame < 3; frame++)
SimulateBlockedFrame(body, rec.Input); // Resolve + PhysicsObjUpdate, target == captured target
Assert.True(body.Velocity.Length() < 1.0f, $"velocity did not bleed: {body.Velocity}");
Assert.True(body.FramesStationaryFall >= 2);
}
```
Run → PASS.
- [ ] **Step 2: Whole-capture A/B measurement (manual gate, not a unit test)**
Rebuild the client, reproduce the crowd-jump repro live with `ACDREAM_CAPTURE_RESOLVE=after-crowd.jsonl`, then:
```
py tools/analyze_resolve_capture.py after-crowd.jsonl
```
**Gate:** `airborne-stuck → 0`, and `ok%` climbs toward retail's ~78% (from 50.9%). Record before/after in the commit message / ISSUES #182. If `ok% << 78%` with airborne-stuck at 0, that is the Slice 3 residual (§7 Q3) — proceed to measure TS-4.
- [ ] **Step 3: Commit**
```bash
git add tests/AcDream.Core.Tests/Physics/Issue182CrowdJumpReplayTests.cs tests/AcDream.Core.Tests/Fixtures/issue182/
git commit -m "test(#182): crowd-jump airborne-stuck replay — blocked jump bleeds velocity within 3 frames"
```
---
## Task 8: Register bookkeeping + docs (same commit boundary as Task 6/7)
**Files:**
- Modify: `docs/architecture/retail-divergence-register.md`
- Modify: `docs/ISSUES.md`, `claude-memory/project_physics_collision_digest.md`
- [ ] **Step 1: Retire / amend rows**
- **Retire TS-3** (`:195`) — the fsf accounting is now ported (delete the row; note the retirement in the TS-section header line like the TS-45 note).
- **Amend AD-25** (`:88`) — the player-half reflect suppression is gone (retail's broader rule restored via `handle_all_collisions`). AD-25 **still covers the remote-DR sweep** in `GameWindow.cs` (#173), which is out of this arc's scope. Rewrite AD-25 to reference only the remote-DR site + note the player half was retired by this rebuild; OR split into a new AD row for the remote half. Do NOT delete (the remote sweep still suppresses).
- **Add** any adaptation this port introduces: e.g. `CachedVelocity` is computed but not yet consumed by the wire (reporting still uses the old path) — a small AP row if the wire velocity differs from retail's cached_velocity source; the fsf gate's `HasFrozenBit`/`ObjectHasGravity` derivation if it approximates retail's exact bits.
- [ ] **Step 2: Update ISSUES + digest**
- `docs/ISSUES.md`: move #182 forward (airborne-stuck fixed; note the A/B numbers; residual ground-jam tracked if <78%).
- `claude-memory/project_physics_collision_digest.md`: replace the 2026-07-07 top banner's "designed (deferred)" with "SHIPPED" + the fsf mechanism + the A/B result + a DO-NOT-RETRY note ("the bleed is fsf>1→v=0 in handle_all_collisions, NOT cached_velocity; calc_friction 0.0 vs retail 0.25 is a SEPARATE L.3c divergence, do not fold it in").
- [ ] **Step 3: Commit** (fold into Task 6 or 7's commit if landing together, or a trailing docs commit).
---
## Task 9: STOP for the user visual gate
Do **not** proceed to Slice 3 without the user's visual verification. Present:
1. **Crowd glide/land** (the #182 symptom): jump into a monster crowd — does the player land/glide across the tops and shuffle out, like retail?
2. **Normal-locomotion regression pass:** flat walking, slopes, stairs, jumping, falling, wall-slide — unchanged?
Only the user can confirm these. The suites + A/B histogram are necessary but not sufficient.
---
## Task 10 (conditional): Slice 3 — residual ground-jam
Only if Task 7's A/B shows `ok% << 78%` with airborne-stuck at 0. Measure which bucket dominates (partial vs stuck) and correlate against `slidingNormal` provenance. Prime suspect: **TS-4** (BSPQuery Path-6 steep persisted sliding-normal → #137 anti-parallel-absorb). That is in the *kept* internals — a separate, decomp-anchored fix (brainstorm a sub-slice with the user before touching it, per the roadmap-divergence rule). Do not pre-emptively touch it.
---
## Self-Review
**Spec coverage (design §4.1 functions):**
- `UpdateObjectInternal` chain → Task 6 (consolidated in the controller) + the retail-pseudocode appendix cited in code.
- `UpdatePositionInternal`/`calc_acceleration` → already present in `PhysicsBody`; the OnWalkable-gate divergence fixed in Task 2. `calc_friction` explicitly out of scope (documented, orthogonal L.3c divergence).
- `handle_all_collisions` → Task 5 (pure unit) + Task 6 (wired). **Design §7 Q1 answered: retail reflects (fsf≤1) then zeros (fsf>1).**
- `SetPositionInternal` (0x00515330 confirmed, §7 Q2) → Task 6.
- `transition`/`ResolveWithTransition` reused as-is; fsf seed/writeback added (Task 4) — the only touch to the kept-internals seam, justified as completing the TS-3 stub.
- The velocity-from-movement recompute (§4.2) → `CachedVelocity` (Task 6), correctly kept separate from the integrator per the verified two-velocity model.
**Staging (design §4.5):** Slice 0 (measurement) → Slice 1 (fsf substrate: Tasks 2-4, dormant in locomotion) → Slice 2 (the fix: Tasks 5-7, A/B gate) → visual gate → Slice 3 (conditional residual). The design's "airborne-stuck→0 after Slice 1" gate correctly moves to Slice 2 (Task 7) — a direct consequence of the corrected mechanism.
**Type consistency:** `FramesStationaryFall` (int) and `CachedVelocity` (Vector3) on `PhysicsBody`; `TransientStateFlags.Stationary{Fall,Stop,Stuck}` = 0x10/0x20/0x40; `PhysicsObjUpdate.HandleAllCollisions(body, fsf, cnValid, cn, prevContact, prevOnWalkable, nowOnWalkable)` — signature used identically in Tasks 5 & 6.
**Placeholder scan:** two spots are marked "verify while writing" (the `ObjectInfo` frozen/gravity/contact bit accessors in Task 3; the landing-edge wiring in Task 6) — these are genuinely dependent on exact acdream `ObjectInfo`/controller field names to be read at implementation time, not hand-wavy gaps; the retail semantics + pc anchors are pinned. All code steps show concrete code.
**Risk (design §6):** replaces the core of every jump/fall/step. Mitigations honored: transition internals untouched (except the TS-3 stub completion), fsf dormant in ordinary locomotion, measured A/B before the visual gate, and a hard stop for visual verification.