acdream/docs/research/2026-07-07-remote-creature-deoverlap-handoff.md

Handoff: verbatim port of retail's per-remote physics tick so packed monsters de-overlap

Date: 2026-07-07 · Status: DESIGN SPEC WRITTEN + APPROVED, IMPLEMENTATION NOT STARTED (fresh session). Driving report (user, side-by-side vs retail on the SAME ACE): monsters packed around the player overlap (arms interpenetrating) in acdream; in the retail client they barely overlap. That overlap is why there's "no room to slide out" of a crowd.

Read these first (in order):

1. Design spec: docs/superpowers/specs/2026-07-07-remote-creature-deoverlap-design.md — the full design.
2. This handoff — the executable detail + the exact verified code sites + what to preserve.
3. Physics digest banner (SSOT): claude-memory/project_physics_collision_digest.md (2026-07-07, incl. the "the room is SLIDING, user RETRACTED the jiggle framing" note).

---

0. Session context — what shipped, what this is

This work is a new, distinct thread from the #182 player physics rebuild that shipped THIS session (6 commits 8bb8b204→e3c4c59b, Core 2617 / App 741 green, airborne-stuck confirmed fixed by the user's visual gate: "Works better, don't get stuck in the animation"). That rebuild is landed — do NOT redo it. Its own residual (the grounded ground-jam, #137 family) is a separate Slice 3 tracked in ISSUES #182.

During that gate the user noticed the crowd still feels wrong and diagnosed it side-by-side vs retail: the monsters are packed tighter / overlapping in acdream. That's THIS handoff.

---

1. Verified root cause (decomp + source — do NOT re-derive)

Research workflow wf_d2ff782f-9cb (4 read-only agents, Opus) + my own direct source reads. Retail pc:/0x… anchors are into docs/research/named-retail/acclient_2013_pseudo_c.txt.

Retail runs ONE unified per-object tick and collides every creature locally:

• CPhysics::UseTime (0x00509950, pc:271640) walks every CPhysicsObj in the object table and runs update_object → UpdateObjectInternal on each — no fork player-vs-remote. The player only gets an extra camera callback.
• UpdateObjectInternal (0x005156b0) runs the full transition (collision) for any active object with spheres whose origin moved. CObjCell::find_obj_collisions (0x0052b750, pc:308916) iterates the cell's shadow list; creature-vs-creature collision is exempt only for a viewer or IGNORE_CREATURES mover. So moving remote creatures de-overlap against each other, client-side.
• A remote stays "active" via the motion system feeding velocity each tick (apply_interpreted_movement 0x00528600 → set_local_velocity 0x005114d0 → set_velocity 0x005113f0 sets the 0x80 active bit).

Retail's server position is a GENTLE dead-reckoning TARGET, not a hard-snap:

• SmartBox::HandleReceivedPosition (0x00453fd0) → CPhysicsObj::MoveOrTeleport (0x00516330): teleport-TS / no-cell → hard snap; has-velocity AND player_distance < 96 → InterpolateTo (queue a DR node); has-velocity AND ≥ 96 → far snap.
• InterpolationManager::adjust_offset (0x00555d30) catches up toward the queued position at ≤ 2× the creature's max animation speed × dt. The per-tick collision-resolved position is stored (SetPositionInternal writes sphere_path.curr_pos, NOT the raw target) and persists; the next server update re-aims the catch-up from wherever collision left the creature. A node_fail_counter blips to the server point only after ~5 genuinely-stuck frames.

So retail's de-overlap is PROACTIVE (movement collision-stopped before interpenetration) and PERSISTENT (never snapped-into-overlap). ACE broadcasts each creature's own overlapping pathed position; the CLIENT spreads them. (ACE/holtburger source are NOT checked out — empty submodule dirs; the decomp + the #182 live cdb trace settle client-responsibility.)

acdream's two divergences (both verified against source):

1. NPC (monster) UpdatePosition HARD-SNAPS to the raw server position — GameWindow.cs:5925-5926: if (!snapSuppressedByStick) rmState.Body.Position = worldPos; (suppressed only while a sticky melee lease is armed). A packed monster teleports into the overlapping server position every UP, overwriting the swept de-penetration. The sweep resolves movement, not a static overlap it gets snapped into.
2. A two-path fork retail doesn't have (GameWindow.cs:10076):
   • Path A — grounded player remotes (IsPlayerGuid && !Airborne, :10076-10311): advance via RemoteMotionCombiner.ComputeOffset interp catch-up, ResolveWithTransition NOT called (:10274-10281 "collision is the sender's problem" — factually wrong per the decomp).
   • Path B — NPCs/monsters + airborne player remotes (:10312-10698): DO call ResolveWithTransition (:10558, moverFlags: EdgeSlide, self-skip movingEntityId: kv.Key) — so a monster already collides against other creatures. But it drives the body from get_state_velocity() (synth locomotion), and the NPC hard-snap (#1) overwrites the result.

KEY INSIGHT: the collision math already exists and is faithful. The bug is the reconciliation (hard-snap) + the movement model (synth-velocity instead of catch-up) + the fork.

---

2. SCOPE REFINEMENT — read this before planning (discovered reading Path B)

The fix is bigger than "replace the hard-snap." Path B drives the body from get_state_velocity() (the animation locomotion velocity), NOT the interp catch-up toward the server target. For a monster to de-overlap, its per-tick movement must chase the server target (so the sweep resolves that movement against neighbors and stops it at contact). So the faithful fix reworks Path B's movement model: synth-velocity → interp catch-up (ComputeOffset, like Path A) → sweep → store resolved. Retail's UpdatePositionInternal uses a REPLACE dichotomy (the catch-up REPLACES the anim root motion when the queue is active; the anim just animates the legs). This is a delicate change to the FROZEN R4/R5 remote-DR arc — treat it with care.

---

3. Exact code sites (all verified against source THIS session)

RemoteMotion type — GameWindow.cs:441: .Body (:443 the sim PhysicsBody), .Movement (:453 R5 MovementManager; .Motion => Movement.Minterp :455, .MoveTo :478), .Host (:485 EntityPhysicsHost → TargetManager + the faithful Motion.PositionManager Sticky/Constraint facade), .Interp (:581 the InterpolationManager catch-up queue), .Position (:590 the RemoteMotionCombiner, NOT the retail facade).

A. Remote UpdatePosition handler (OnLivePositionUpdated), GameWindow.cs:~5640-5980:

• :5655 entity.SetPosition(worldPos) (unconditional render snap, undone later per-branch).
• :5665-5672 ShadowObjects.UpdatePosition(entity.Id, worldPos, …) — keep (server-truth shadow sync; retail change_cell/AddShadowObject). NOTE: this syncs the collision broadphase target to server truth even though the rendered body de-overlaps — verify this doesn't re-pack.
• :5724 if (IsPlayerGuid(update.Guid)) → the player-remote branch ALREADY implements retail MoveOrTeleport (airborne no-op :5776; landing :5791; far>96 snap+clear :5827-5832; near Interp.Enqueue(worldPos, heading, isMovingTo:false, currentBodyPosition:…) :5843-5847). This is the model to extend to NPCs.
• The else (NPC) branch, :5879-5975: computes ServerVelocity synth (:5863/:5889, keep for [VEL_DIAG]); :5925-5926 the HARD-SNAP rmState.Body.Position = worldPos (suppressed while snapSuppressedByStick); :5952 rmState.CellId = p.LandblockId; :5967+ orientation hard-snap (also stick-gated). THIS is what Slice 1 replaces with the MoveOrTeleport Enqueue.

B. Path B tick (NPC/legacy), GameWindow.cs:~10312-10698:

• :10457-10460 rm.Body.set_local_velocity(rm.Motion.get_state_velocity(), …) when OnWalkable — the synth-velocity movement source to REPLACE with the interp catch-up.
• :10484-10492 manual omega/orientation integration (ObservedOmega) — keep.
• :10512 preIntegratePos = rm.Body.Position.
• :10521-10526 sticky delta via rm.Host.PositionManager.AdjustOffset(pmDelta, dt) + ApplyPositionManagerDelta — keep, composes with the catch-up (retail adjust_offset order).
• :10527-10528 calc_acceleration() + UpdatePhysicsInternal(dt) (integrates the synth velocity).
• :10549-10583 the SWEEP ResolveWithTransition(preIntegratePos, postIntegratePos, rm.CellId, 0.48f, 1.835f, 0.4f, 0.4f, isOnGround:!rm.Airborne, body:rm.Body, moverFlags:EdgeSlide, movingEntityId:kv.Key) — KEEP; this is the creature-vs-creature de-overlap (Slice 3 makes the 0.48/1.835 Setup-derived).
• :10585 rm.Body.Position = resolveResult.Position + :10586-10587 CellId writeback.
• :10606+ the #173 airborne reflect (old AD-25 airborne-only bounce) — leave for now (or later fold into PhysicsObjUpdate.HandleAllCollisions like the player path; NOT Slice 1).

C. Path A tick (player remote, ComputeOffset, NO sweep), GameWindow.cs:10076-10311:

• :10173 rm.Position.ComputeOffset(dt, rm.Body.Position, seqVel, ori, rm.Interp, maxSpeed, terrainNormal) — the catch-up model (REPLACE dichotomy). :10274-10281 the "ResolveWithTransition NOT called" opt-out. Slice 2 adds the sweep here and unifies with Path B.

D. RemoteMotionCombiner.ComputeOffset, RemoteMotionCombiner.cs:59-115: interp catch-up (interp.AdjustOffset toward the queue head) REPLACES the frame when non-zero; else seqVel anim fallback projected on the terrain plane. This is the movement primitive both paths should use.

E. Substrate (KEEP, already retail-shaped): shadow registry RegisterLiveEntityCollision GameWindow.cs:4171 (:4276 RegisterMultiPart, IsCreature :4271); CollisionExemption CollisionExemption.cs:59-129 (creature-vs-creature exempt only for viewer/ignore-creatures mover — an NPC mover with EdgeSlide is NOT exempt, so it DOES collide with other creatures).

---

4. The plan (slices) — see §2.2/§2.5 of the design spec

Slice 1 — NPC de-overlap (the reported symptom). The two changes are COUPLED, land together:

1. NPC UP handler (:5925-5926 + orientation :5967+): replace the hard-snap with the retail MoveOrTeleport routing — mirror the player-remote branch (:5822-5848): far>96 → snap + clear queue; near → Interp.Enqueue; teleport/parent → snap. Keep the snapSuppressedByStick escape (it's retail's "armed stick owns the frame, server correction can't fight it", TS-41/44). Keep the orientation hard-snap (retail hard-snaps orientation on UP).
2. Path B tick (:10457-10528): replace the get_state_velocity movement with the interp catch-up as the movement source (use rm.Position.ComputeOffset / rm.Interp.AdjustOffset toward the queued server target, REPLACE dichotomy), compose the sticky delta, KEEP the sweep (:10558) and store resolveResult.Position. The anim (legs) still plays via the sequencer. ServerVelocity stays for diagnostics only.
   • Gate: monsters de-overlap side-by-side vs retail; no remote jitter/rubber-band/desync; sticky melee (#171) unbroken; walk/run/jump/land unchanged; Core 2617 / App 741 green.

Slice 2 — unify the fork: collapse Path A into the same catch-up+sweep model (player remotes gain the sweep → packed players de-overlap too). Per Code Structure Rule 1 (no new feature body in the

10k-line GameWindow), extract a RemotePhysicsUpdater class (src/AcDream.App/Physics/ or Rendering/) owning the unified per-remote UpdateObjectInternal chain (interp delta → sweep → commit); GameWindow's loop shrinks to RemotePhysicsUpdater.Tick(rm, dt). Extract the MoveOrTeleport routing into a shared method so NPC + player-remote reconciliation is ONE impl. Retire the "remotes skip the transition" adaptation (:10089/:10275, filed #40, ISSUES.md ~:4899).

Slice 3 — Setup-derived mover sphere: replace the hard-coded 0.48f/1.835f (:10551-10556) with the creature's Setup sphere / ObjScale so differently-sized creatures de-overlap at true radii.

---

5. What to PRESERVE (regression watch — the R4/R5 arc has many hard-won fixes)

• The sweep + transition internals (ResolveWithTransition and below), shadow registry, CollisionExemption — untouched (already faithful).
• The R5 managers (MovementManager/MoveToManager/TargetManager + Motion.PositionManager Sticky/Constraint) — TICKED by the unified update, not rewritten.
• Sticky melee #171 (snapSuppressedByStick escape + the sticky delta at :10521-10526) — MUST survive; it's the "monster facing while attacking" fix.
• The airborne remote path (!IsGrounded no-op :5776, landing transition :5791, gravity integration between UPs) — MUST survive.
• The omega/orientation manual integration (:10484-10492) and orientation hard-snap — keep.
• The node_fail_counter blip watchdog in InterpolationManager — keep (retail's stuck→snap escape; without it a genuinely-blocked remote freezes).
• The #182 local-player rebuild (this session) — orthogonal, untouched.

6. Gotchas

• Don't double-move: the catch-up REPLACES the synth-velocity (retail's REPLACE dichotomy), it is NOT additive on top of get_state_velocity.
• The two Slice-1 changes are coupled — Enqueue is useless unless Path B consumes the queue; a half-change (Enqueue without the catch-up movement) breaks DR (body stops tracking the server).
• ShadowObjects.UpdatePosition (:5665) still syncs the broadphase to server truth — verify the de-overlapped rendered body and the server-truth collision target don't fight (retail's shadow follows the collided position; check whether acdream should sync the shadow to the collision-resolved position instead of raw server truth). Potential subtle bug — probe it.
• The sweep only de-overlaps MOVING creatures (it resolves movement, not static overlap). Retail never lets deep static overlap form (proactive). The converging-pair test must drive real movement.

7. Validation

• Conformance test (RemotePhysicsUpdaterTests, easiest after the Slice-2 extraction): two registered creature shadows given converging catch-up targets → assert they settle at contact-distance (sum of radii), not overlapping; a MoveOrTeleport routing test (near→enqueue, far→snap, teleport→snap); a persistence test (a de-penetrated position survives the next server UP).
• Suites green: Core 2617 / App 741 (no regression to remote anim, DR smoothness, sticky #171, the #182 player fix).
• Visual gate (acceptance): side-by-side vs the retail client on the SAME ACE — packed monsters spread to retail spacing (arms no longer interpenetrating); remotes don't jitter/rubber-band/desync; sticky-melee facing (#171) unbroken; remote walk/run/jump/land unchanged.
• Apparatus: ACDREAM_REMOTE_VEL_DIAG=1 (existing, UP/seq pace); add a [remote-deoverlap] probe (rendered pos vs raw server UP + neighbor overlap depth) if a residual needs it.

8. Risk

Touches the frozen R4/R5 remote-DR arc. The synth-velocity model was tuned against live ACE pace over the R4/R5 sessions; replacing it with the catch-up model risks regressing remote walk/run smoothness, the slope "staircase" fix, and the sticky melee. Mitigate: stage NPC-first + gate before Slice 2; preserve every escape (§5); keep the sweep/registry/managers; the node_fail_counter prevents a stuck-remote freeze.

9. Register bookkeeping (do in the landing commits)

• Retire the "remotes skip the transition / server already collision-resolved" adaptation (GameWindow.cs:10089/:10275, #40) — its "Risk if assumption breaks" IS the arms-overlap. Retire in the Slice-2 commit that adds the sweep to Path A.
• Add rows for: the NPC MoveOrTeleport near-distance constant (96 m), the sticky-suppression retention, and (if kept) the shadow-follows-server-truth vs collision-resolved decision.

10. Retail anchors (addresses, for grep named-first in the fresh session)

CPhysics::UseTime 0x00509950 · update_object 0x00515d10 · UpdateObjectInternal 0x005156b0 · UpdatePositionInternal 0x00512c30 · transition 0x00512dc0 · find_obj_collisions 0x0052b750 · MoveOrTeleport 0x00516330 · HandleReceivedPosition 0x00453fd0 · InterpolateTo 0x005104f0 / InterpolationManager::InterpolateTo 0x00555b20 · adjust_offset 0x00555d30 · UseTime 0x00555f20 · set_local_velocity 0x005114d0 · apply_interpreted_movement 0x00528600.

11. Pointers

• Design spec: docs/superpowers/specs/2026-07-07-remote-creature-deoverlap-design.md.
• Physics digest (SSOT + DO-NOT-RETRY): claude-memory/project_physics_collision_digest.md.
• The #182 player rebuild (shipped this session, orthogonal base): plan docs/superpowers/plans/2026-07-07-player-physics-update-verbatim-rebuild.md; the histogram tools/analyze_resolve_capture.py.
• Research: workflow wf_d2ff782f-9cb (4-agent read-only sweep; findings distilled into §1-§3 here).