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

**Date:** 2026-07-07 · **Status:** DESIGN APPROVED (user: "I want retail behavior. So make it work.")
**Driving report (user, side-by-side vs retail on the SAME ACE):** monsters packed around the
player **overlap** in acdream (arms interpenetrating); in the retail client they barely overlap.
This is the crowd "no room to slide out" feel — the room is created by the monsters *not*
occupying the same space.

---

## 1. Verified root cause (decomp + source, not guessed)

Research workflow `wf_d2ff782f-9cb` (4 read-only agents) + direct source reads settle it. Retail
anchors are into `docs/research/named-retail/acclient_2013_pseudo_c.txt`.

### Retail: ONE unified per-object tick that collides every creature locally
- **`CPhysics::UseTime`** (0x00509950, pc:271640) walks **every** `CPhysicsObj` in the object
  table and calls `update_object → UpdateObjectInternal` on each — **no fork** between the player
  and remote creatures. The player only gets an *extra* camera callback.
- **`UpdateObjectInternal`** (0x005156b0) runs the full `transition` (collision sweep) 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* mover or an *IGNORE_CREATURES* mover. So **moving remote creatures de-overlap
  against each other, client-side.**
- A remote creature stays "active" (transient bit 0x80) because the motion/animation system feeds
  velocity every tick via `apply_interpreted_movement` (0x00528600) → `set_local_velocity`
  (0x005114d0) → `set_velocity` (0x005113f0, which sets 0x80).

### Retail: the server position is a GENTLE DR target, not a hard-snap
- **`SmartBox::HandleReceivedPosition`** (0x00453fd0) routes a remote through
  **`CPhysicsObj::MoveOrTeleport`** (0x00516330):
  - newer teleport-TS OR no cell → **hard snap** (`SetPosition`).
  - has-velocity AND `player_distance < 96` → **`InterpolateTo`** (queue a DR node).
  - has-velocity AND `player_distance ≥ 96` → **far snap** (`SetPositionSimple`).
- **`InterpolationManager::adjust_offset`** (0x00555d30) catches up toward the queued server
  position at **≤ 2× the creature's max animation speed × dt**. The per-tick collision-resolved
  position is **stored and persists** (`SetPositionInternal(transition)` writes
  `sphere_path.curr_pos`, not the raw target); 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 (`CREATURE_FAILED_INTERPOLATION_PERCENTAGE=0.3`,
  `MIN_DISTANCE_TO_REACH_POSITION=0.2`).

**Net retail behavior:** de-overlap is **proactive** (movement is collision-stopped *before*
creatures interpenetrate) and **persistent** (the resolved position is never overwritten by a
snap-into-overlap). ACE broadcasts each creature's own pathed (overlapping) position with no
server-side separation; **the client spreads them.** (ACE/holtburger source not checked out —
empty submodule dirs — but the decomp + the #182 live cdb trace establish client-responsibility.)

### acdream: the two divergences (both verified in source)
1. **NPC (monster) `UpdatePosition` HARD-SNAPS to the raw server position.** `GameWindow.cs:5925-5926`:
   `if (!snapSuppressedByStick) rmState.Body.Position = worldPos;` — only suppressed while a sticky
   melee lease is armed. So a packed monster teleports into the overlapping server position every
   UP, **overwriting** whatever de-penetration the per-tick sweep achieved. The sweep resolves
   *movement*, not a static overlap it gets snapped into, so the overlap persists.
2. **A two-path fork retail doesn't have** (`GameWindow.cs:10076`):
   - **Path A** — grounded **player** remotes (`IsPlayerGuid` && !Airborne, `:10076-10311`): advance
     via the `RemoteMotionCombiner.ComputeOffset` interp catch-up, **`ResolveWithTransition` is
     deliberately NOT called** (`:10274-10281` "collision is the sender's problem" — factually
     wrong per the decomp). Player remotes never de-overlap.
   - **Path B** — NPCs/monsters + airborne player remotes (`:10312-10698`): DO call
     `ResolveWithTransition` (`:10558`) with `moverFlags: EdgeSlide` (not IsViewer/IgnoreCreatures),
     so the `CollisionExemption` gate already lets a monster collide against other creatures. BUT
     the NPC UP hard-snap (#1) overwrites its result, and the swept displacement is only
     `preIntegrate→postIntegrate` (tiny between UPs), so it can't undo a snapped-in static overlap.

**So the collision math is already faithful and present.** The bug is the **reconciliation**
(hard-snap) + the **fork** (player remotes skip the sweep). Retail's gentle catch-up + fork-free
tick is what makes the resolved position persist.

---

## 2. Design — port retail's unified per-remote tick + MoveOrTeleport reconciliation

Make every remote creature run the retail `UpdateObjectInternal` shape: **interp-catch-up delta +
anim velocity → `ResolveWithTransition` sweep → store the collision-resolved position**, with the
server `UpdatePosition` fed in as a **gentle DR target** (MoveOrTeleport), not a hard-snap. This
collapses Path A and Path B into one and lets the per-tick de-overlap persist.

### 2.1 Retail functions being ported (chain)
| Function | Address | Role | acdream target |
|---|---|---|---|
| `CPhysics::UseTime` | 0x00509950 | walk ALL objects, tick each | the `_animatedEntities` per-tick loop `GameWindow.cs:10019` (collapse the fork) |
| `CPhysicsObj::MoveOrTeleport` | 0x00516330 | teleport-snap / near-interpolate(<96) / far-snap(≥96) | the remote `UpdatePosition` handler `GameWindow.cs:5879+` (extend the player-remote routing to NPCs) |
| `InterpolationManager::adjust_offset` | 0x00555d30 | speed-capped catch-up (≤2×max_speed·dt) + fail-counter blip | acdream `InterpolationManager` (`rm.Interp` — already present) |
| `UpdateObjectInternal` | 0x005156b0 | integrate → transition → commit resolved pos | the unified per-remote tick (reuse `ResolveWithTransition`) |

### 2.2 In scope (rebuilt verbatim)
- **NPC `UpdatePosition` reconciliation:** replace the hard-snap (`GameWindow.cs:5925-5926` +
  the orientation/velocity snaps `:5952-5967+`) with the retail `MoveOrTeleport` routing already
  written for player remotes (`:5822-5848`): far (>96 m) → snap + clear queue; near → `Interp.Enqueue`
  the server waypoint; teleport/parent → snap. Keep the sticky-suppression escape (it is retail's
  "stuck → server correction can't fight the armed stick" behavior, TS-41/44).
- **Unify the tick:** every remote (Path A player *and* Path B NPC) advances by the interp
  catch-up (`Interp.AdjustOffset`) **composed into a `MotionDeltaFrame`** (interp + sticky), then
  runs `ResolveWithTransition` and **stores the resolved position** — the pattern Path B already
  uses for the sticky delta at `:10521-10528`. Path A gains the sweep; Path B gains the interp
  catch-up as its movement source (so the swept displacement IS the catch-up).
- **Setup-derived mover sphere:** replace the hard-coded human dims `0.48f/1.835f`
  (`GameWindow.cs:10551-10556`) with the creature's own Setup sphere / `ObjScale` so differently
  sized creatures de-overlap at their true radii (retail sizes the mover sphere from its own Setup
  via `init_sphere`).
- The `node_fail_counter` blip watchdog (already in `InterpolationManager`) — keep; it is the
  retail "genuinely blocked → snap to server after ~5 frames" escape.

### 2.3 OUT of scope (kept — already faithful)
- The **transition internals** (`ResolveWithTransition` and below — BSPQuery, the CSphere/CylSphere
  families incl. the #182 port, `CollisionExemption`, cell membership). Retail's remote tick calls
  these primitives; so does ours. Untouched.
- The **shadow registry** (`ShadowObjects.Register`/`UpdatePosition`, `GameWindow.cs:4171/5665`) —
  every remote creature is already registered + live-synced (retail's `AddShadowObject`/`change_cell`
  equivalent). No new registration.
- The **R5 managers** (`MovementManager`/`MoveToManager`/`TargetManager` + the `Motion.PositionManager`
  Sticky/Constraint facade). A verbatim `UpdateObjectInternal` ticks exactly these — the port ticks
  them, doesn't rewrite them.
- The **#182 local-player rebuild** (this session) — orthogonal; stays as the base.

### 2.4 Architecture (Code Structure Rule 1: no new feature bodies in GameWindow)
`GameWindow.cs` is already >10k lines and owns the remote tick. The unified per-remote update body
goes into a **new `RemotePhysicsUpdater`** (`src/AcDream.App/Physics/` or `Rendering/`) that takes
a `RemoteMotion` + dt + the `PhysicsEngine` and runs the retail `UpdateObjectInternal` chain
(interp delta → sweep → commit). `GameWindow`'s per-tick loop shrinks to: resolve the entity →
`RemotePhysicsUpdater.Tick(rm, dt)` → write `entity.SetPosition(rm.Body.Position)`. The
`UpdatePosition` `MoveOrTeleport` routing is extracted into a `RemotePhysicsUpdater.OnServerPosition`
(or a small `RemoteReconciler`) so the NPC and player-remote paths share ONE implementation.

### 2.5 Staging (measured, de-overlap first)
- **Slice 1 — NPC reconciliation (the reported symptom):** replace the NPC hard-snap with the
  `MoveOrTeleport` gentle catch-up (Enqueue), and drive Path B's body advancement from the interp
  catch-up so its existing sweep resolves the catch-up movement against other creatures. Gate:
  packed monsters visibly de-overlap side-by-side vs retail; no remote jitter/rubber-band regression.
- **Slice 2 — unify the fork:** collapse Path A into the same `RemotePhysicsUpdater.Tick` (player
  remotes gain the sweep → packed *players* de-overlap too). Extract the shared updater
  (§2.4). Gate: remote player crowd de-overlaps; observed-motion (walk/run/jump/land) unchanged.
- **Slice 3 — Setup-derived mover sphere** (§2.2). Gate: large/small creatures de-overlap at true
  radii.

---

## 3. Validation
- **Conformance tests (Core/App):** a `RemotePhysicsUpdaterTests` harness — two registered creature
  shadows converging on a point, driven through the updater, assert they settle at
  contact-distance (sum of radii), not overlapping; a `MoveOrTeleport` routing test (near→enqueue,
  far→snap, teleport→snap); a reconciliation persistence test (a de-penetrated position survives
  the next server UP instead of snapping into overlap).
- **Suites stay green:** Core 2617 / App 741 — no regression to remote animation (walk/run/jump/
  land/turn), dead-reckoning smoothness, sticky melee (#171), or the #182 player fix.
- **Visual gate (the acceptance test):** 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, or desync from the server; sticky-melee facing (#171) unbroken.
- **Apparatus:** `ACDREAM_REMOTE_VEL_DIAG` (existing) for the UP/seq pace; a `[remote-deoverlap]`
  probe optional (rendered pos vs raw server UP + neighbor overlap depth) if a residual needs it.

## 4. Risk
Touches the **R4/R5 remote dead-reckoning arc** (a shipped area): the NPC hard-snap and the
two-path fork. Mitigations: the collision + shadow-registry + R5-manager substrate is UNTOUCHED
(the change is the reconciliation + fork), the sticky-suppression escape is preserved (protects
#171), staged so the NPC de-overlap lands + gates first, and `node_fail_counter` keeps a genuinely
stuck remote from freezing. Perf: N creatures × a sweep per tick — Path B already does this for
NPCs; Slice 2 adds it for player remotes (bounded by the visible-crowd count).

## 5. Register bookkeeping
- Retire the "remotes skip the transition / server already collision-resolved" adaptation (the
  `GameWindow.cs:10089/10275` premise, filed under #40 / ISSUES.md ~:4899) — it's the exact
  divergence whose "Risk if assumption breaks" is the arms-overlap. Same commit that lands Slice 2.
- Any adaptation the port introduces (e.g. the NPC MoveOrTeleport near-distance constant, the
  sticky-suppression retention) gets its row in the same commit.

## 6. Open items to verify during implementation
1. Confirm Path B's `ResolveWithTransition` sweep, once driven by the interp catch-up delta,
   actually de-penetrates a converging neighbor (vs the tiny-displacement no-op) — the
   `RemotePhysicsUpdaterTests` converging pair pins this before the visual gate.
2. Confirm the NPC `Interp.Enqueue` path composes with `TickRemoteMoveTo` / `ServerVelocity` /
   the sticky delta without double-driving the body (the `RemoteMotionCombiner` REPLACE dichotomy).
3. Decide whether Slice 1 needs Path B to *also* route through `Interp` (likely) or whether feeding
   `ServerVelocity` into the existing integrate+sweep suffices — measure with the converging-pair test.