acdream/docs/research/2026-07-04-171-sticky-melee-handoff.md

Handoff — #171 group-melee interpenetration + facing drift (R5-V3: StickyManager + arrival radii) — 2026-07-04

Fresh session picks up HERE for #171. Worktree vigorous-joliot-f0c3ad, branch claude/vigorous-joliot-f0c3ad, tree CLEAN after the #170 close-out (4cad626f). The fix scope below is USER-APPROVED ("Ok I approve", 2026-07-04). Pickup prompt: docs/research/2026-07-04-171-pickup-prompt.md.

Symptom (user report, #170 gate session)

In a pack melee vs the player, acdream monsters end up partly inside each other with slightly stale facings, vs retail on the same local ACE. The #170 chase itself (turn → sustained run → plant → swing) is CLOSED and gate-passed — do not reopen that machinery.

Root causes (code-grounded, investigated 2026-07-04)

1. Sticky melee is a no-op — register TS-39. ACE arms EVERY melee chase with Sticky | UseFinalHeading | MoveAway | FailWalk (references/ACE/Source/ACE.Server/WorldObjects/Monster_Navigation.cs:406-419). The retail arrival chain: MoveToManager::BeginNextNode (sticky bit set, queue empty) reads SoughtObjectId/Radius/Height BEFORE CleanUp zeroes them (that ordering IS already ported — MoveToManager.cs ~700-714) and calls PositionManager::StickTo(tlid, radius, height); from then on StickyManager::adjust_offset (0x00555430) runs per tick and holds a ~0.3 m edge gap + facing against the moving target. Every MovementManager::PerformMovement head calls unstick_from_object → PositionManager::UnStick (our MoveToManager.PerformMovement:414 invokes the seam). acdream's StickTo/Unstick seams are UNBOUND (GameWindow EnsureRemoteMotionBindings + the player wiring bind neither) → attackers complete-and-freeze at stale arrival poses until the next wire re-arm. This is the direct cause of BOTH observed symptoms.

2. Arrival radii are zero. Retail/ACE arrive EDGE-TO-EDGE: ACE PhysicsObj.MoveToObject (references/ACE/…/Physics/PhysicsObj.cs:936-956) reads the TARGET's PartArray.GetRadius()/GetHeight() and passes them into MoveToObject_Internal; the mover's own radius feeds GetCurrentDistance's cylinder_distance when UseSpheres (ACE default TRUE, DistanceToObject default 0.6). acdream:

   • GameWindow.EnsureRemoteMotionBindings binds `getOwnRadius/getOwnHeight

     () => 0f` — the comment IS the R5-V3 pin ("setup cylsphere radius lands with R5-V3");

   • GameWindow.RouteServerMoveTo never sets MovementStruct.Radius/Height (target radii) → 0. Net: every attacker closes ~one body-radius deeper than retail → dogpile.

3. Server-side caveat: ACE has no monster-vs-monster avoidance; UP hard-snaps plant bodies where ACE says (retail hard-snaps identically). Some overlap is server-authoritative and visible on retail too — acceptance is retail parity, not zero overlap.

Ruled out: the between-snap collision sweep. Remotes run the full ResolveWithTransition (GameWindow ~10100) and CollisionExemption keeps creature cylinders collidable for non-viewer movers.

Approved fix scope (= the R5-V3 slice, roadmap-aligned)

1. Port StickyManager verbatim (grep docs/research/named-retail/ acclient_2013_pseudo_c.txt for StickyManager:: first — StickTo, UnStick, adjust_offset 0x00555430, HandleUpdateTarget; cross-check references/ACE/Source/ACE.Server/Physics/Managers/StickyManager.cs). Groundwork ALREADY in tree (MoveToMath): CylinderDistanceNoZ (signed — the adjust_offset gap math), GlobalToLocalVec, NormalizeCheckSmall — all documented as adjust_offset consumers. ConstraintManager (the sibling PositionManager member) was ported R5-V1 (TS-35, unarmed — #167 is SEPARATE, do not arm it here).
2. PositionManager: the facade that owns Sticky + Constraint (references/ACE/…/Managers/PositionManager.cs). Retail per-tick anchors pinned this session from the named decomp:
   • PositionManager::adjust_offset called inside CPhysicsObj::UpdatePositionInternal @0x00512d0e (BEFORE process_hooks);
   • PositionManager::UseTime called in UpdateObjectInternal @0x005159b3 (AFTER CPartArray::HandleMovement). Wire the acdream equivalents at the matching points of the remote tick (GameWindow TickAnimations) and the player path.
3. Bind the seams: MoveToManager.StickTo → PositionManager.StickTo; MoveToManager.Unstick → PositionManager.UnStick — in EnsureRemoteMotionBindings AND the player wiring (EnterPlayerModeNow area, ~13128). The TargetManager voyeur fan-out already delivers target info; the R5-V2 comment at GameWindow ~4327 says exactly this: "PositionManager sticky joins the fan-out in V3" — StickyManager is a voyeur consumer in retail (its own HandleUpdateTarget).
4. Thread real radii: own radius/height from the entity's Setup (the spawn path already reads setup.Radius/setup.Height for collision registration, GameWindow ~4187); target radius/height at the RouteServerMoveTo MoveToObject branch (resolve the target entity's setup — retail reads the TARGET object, not the wire). Sweep BOTH the remote and player MoveToManager bindings.
5. Register bookkeeping (same commit): retire TS-39; retire/narrow the radius pin note; new rows for any adaptation introduced.
6. Conformance: extend RemoteChaseEndToEndHarnessTests with a sticky scenario — arm a sticky MoveToObject, arrive, then MOVE the target sideways: assert the follower tracks (gap ≈ stick distance, facing follows) and UnStick fires on the next PerformMovement head. The harness already models the full tick order; add a PositionManager step where retail has it.

Gotchas

• Revert-prone area (remote motion). Follow the workflow: grep named decomp FIRST, pseudocode, port verbatim, ACE cross-check, harness, then wire. No redesigns; the two prior #170 reverts were redesigns.
• The harness gotcha from #170: any new harness body MUST replicate the live RemoteMotion construction (InWorld=true, RemoteWeenie, Contact|OnWalkable|Active) or the TS-40 guard strips links and everything wedges (RemoteChaseDrainBisectTests documents the shape).
• Per-entity probes must print the guid (memory: feedback_probe_identity_attribution — the #170 misread).
• StickyManager::adjust_offset sign semantics: inside the gap the signed distance goes NEGATIVE and the per-tick delta inverts (backs off) — ACE StickyManager.cs:156, already noted on MoveToMath.CylinderDistanceNoZ.
• Do NOT arm ConstraintManager (#167 — two unknown x87 constants).
• Visual gate at the end: pack melee side-by-side vs retail; the user strafes around the pack; attackers should reshuffle + keep facing like retail.

Where things are (quick map)

• MoveToManager.cs: PerformMovement:411 (Unstick head), BeginNextNode sticky arrival ~700-714, GetCurrentDistance (UseSpheres cylinder math).
• MoveToMath.cs: CylinderDistance, CylinderDistanceNoZ, GlobalToLocalVec, NormalizeCheckSmall.
• GameWindow.cs: EnsureRemoteMotionBindings ~4251 (seams + radius 0f pin), RouteServerMoveTo ~4457 (MovementStruct — Radius/Height unset), remote tick TickAnimations (PositionManager wiring points), player wiring ~13128.
• ConstraintManager.cs (R5-V1) — PositionManager sibling, reference for the port style.
• Register rows: TS-39 (sticky seams), TS-35 (ConstraintManager), TS-41/42 (#170 rows, adjacent machinery).