acdream/docs/research/2026-07-03-r5-managers/r5-port-plan.md

R5 port plan — MovementManager facade + PositionManager (Sticky/Constraint) + TargetManager

Synthesis of the R5 recon (2026-07-03). Verbatim retail decomp lives in the sibling files (r5-*-decomp.md); ACE cross-reference in r5-ace-crossref.md; current acdream integration seams in r5-acdream-seams.md. This doc is the pseudocode + integration + sub-slice plan (mandatory workflow step 3).

Retirement targets: TS-39 (sticky no-op seams) and AP-79 (the P4 TargetTracker adapter). ConstraintManager is ported for structural completeness of PositionManager but its arming stays unported (see §Constraint scope) — TS-35 stays open.

---

0. The retail structure vs acdream's reality

Retail (CPhysicsObj owns three managers, all lazily created):

CPhysicsObj
├── movement_manager : MovementManager   (facade → MotionInterp + MoveToManager)
├── position_manager : PositionManager    (facade → Interpolation + Sticky + Constraint)
└── target_manager   : TargetManager      (voyeur subscription system)

Per-tick, CPhysicsObj::UpdateObjectInternal (0x005156b0) fans out in THIS order (decomp §positionmanager-sticky callers):

1. DetectionManager::CheckDetection
2. TargetManager::HandleTargetting ← voyeur tick (no separate UseTime)
3. MovementManager::UseTime → MoveToManager::UseTime only
4. CPartArray::HandleMovement
5. PositionManager::UseTime → Interp/Sticky/Constraint UseTime

And UpdatePositionInternal (0x00512c30) composes the frame delta: Frame::cache(&d) → CPartArray::Update(d) (animation) → PositionManager::adjust_offset(&d, quantum) (interp+sticky+constraint ADD into the SAME delta d) → Frame::combine(out, m_position.frame, d) → transition (collision) → commit. Sticky/constraint steering composes with animation motion in the same per-tick delta frame, before collision resolves it.

acdream has no per-entity CPhysicsObj. The per-entity owner today is:

Retail	acdream (remote)	acdream (player)
CPhysicsObj	GameWindow.RemoteMotion (nested class, GameWindow.cs:411)	_playerController (PlayerMovementController) + GameWindow fields
movement_manager	rm.Motion (MotionInterpreter) + rm.MoveTo (MoveToManager)	_playerController.Motion + playerMoveTo
position_manager	absent	absent
target_manager	AP-79 adapter: rm.TrackedTarget* fields + TickRemoteMoveTo	AP-79 adapter: _playerMoveToTarget* fields + OnUpdateFrame block
UpdateObjectInternal tick	TickRemoteMoveTo(rm) (GameWindow.cs:4469)	OnUpdateFrame block (GameWindow.cs:7994) + _playerController.Update

R5 adds the two missing managers per-entity. The MovementManager facade (collapsing Motion+MoveTo into one owner) is the optional capstone (§V4) — the retirement targets don't require it, so it lands last and only if the arc has budget.

---

1. Struct/field map (acclient.h → C#)

MovementManager  (0x10): motion_interpreter, moveto_manager, physics_obj, weenie_obj
PositionManager  (0x10): interpolation_manager, sticky_manager, constraint_manager, physics_obj
StickyManager    (0x60): target_id:uint, target_radius:float, target_position:Position,
                         physics_obj, initialized:int, sticky_timeout_time:double
ConstraintManager(0x5c): physics_obj, is_constrained:int, constraint_pos_offset:float,
                         constraint_pos:Position, constraint_distance_start:float,
                         constraint_distance_max:float
TargetManager    (0x18): physobj, target_info:TargetInfo*, voyeur_table:Hash<TargettedVoyeurInfo>,
                         last_update_time:double
TargetInfo      (0xd0): context_id:uint, object_id:uint, radius:float, quantum:double,
                         target_position:Position, interpolated_position:Position,
                         interpolated_heading:Vec3, velocity:Vec3, status:TargetStatus,
                         last_update_time:double
TargettedVoyeurInfo(0x60): object_id:uint, quantum:double, radius:float,
                           last_sent_position:Position

acdream already has TargetInfo (4-field record) + TargetStatus enum in MoveToManager.cs — R5 EXTENDS TargetInfo to the full 10-field shape (add ContextId, Radius, Quantum, InterpolatedHeading, Velocity, LastUpdateTime). The existing MoveToManager.HandleUpdateTarget only reads ObjectId/Status/InterpolatedPosition, so the extension is additive-safe.

---

2. The math — decoded (ACE is the oracle for the x87 mush)

All three adjust_offset bodies and both timeout gates were dense x87 mush in the BN decomp. ACE's ports resolve them cleanly and were confirmed against the mush structure (fld/fmul/fsqrt/fcomp shapes match). Port ACE's structure; cite the retail address.

2a. StickyManager.adjust_offset (retail 0x00555430, ACE StickyManager.cs:91)

// Guard: no-op unless PhysicsObj && target_id != 0 && initialized
target      = GetObjectA(target_id)                       // live resolve
targetPos   = target != null ? target.Position : cached target_position   // fallback to last-known
offset      = self.Position.GetOffset(targetPos)          // world vector self→target
offset      = self.Position.GlobalToLocalVec(offset)      // rotate into own frame
offset.Z    = 0                                            // horizontal-only

radius      = self.GetRadius()
dist        = Position.CylinderDistanceNoZ(radius, self.Position, target_radius, targetPos)
              - 0.3f                                       // StickyRadius const (ACE StickyRadius=0.3f)

if NormalizeCheckSmall(ref offset): offset = Vector3.Zero  // too close → don't chase jitter

speed = 0
minterp = self.get_minterp()
if minterp != null: speed = minterp.get_max_speed() * 5.0f  // 5× own max speed (catch up)
if speed < EPSILON: speed = 15.0f                           // fallback

delta = speed * quantum
if delta >= abs(dist): delta = dist                        // don't overshoot (dist can be NEGATIVE)
offset.Origin *= delta

curHeading    = self.Position.Frame.get_heading()
targetHeading = self.Position.heading(targetPos)
h = targetHeading - curHeading
if abs(h) < EPSILON: h = 0
if h < -EPSILON: h += 360
offset.set_heading(h)                                      // per-tick RELATIVE turn toward target

Net: a speed-clamped horizontal steer + bounded turn toward the stuck target, written into the shared per-tick delta frame. StickyRadius=0.3f, StickyTime=1.0f are the two named constants.

2b. ConstraintManager.adjust_offset (retail 0x00556180, ACE ConstraintManager.cs:62)

// Guard: no-op unless PhysicsObj && is_constrained
if (self.TransientState & Contact):                        // ONLY clamps while grounded
    if constraint_pos_offset < constraint_distance_max:
        if constraint_pos_offset > constraint_distance_start:
            offset.Origin *= (constraint_distance_max - constraint_pos_offset)
                           / (constraint_distance_max - constraint_distance_start)   // linear brake taper
    else:
        offset.Origin = Vector3.Zero                       // fully pinned
// UNCONDITIONAL (grounded or airborne):
constraint_pos_offset = offset.Origin.Length()             // NB: length of the per-tick step, NOT distance-to-anchor

ConstraintPos (the anchor) is stored by ConstrainTo but never read by adjust_offset — the taper uses constraint_pos_offset (last tick's step length) vs start/max. See §ConstraintScope for why acdream never arms this.

2c. ConstraintManager.IsFullyConstrained (retail 0x005560d0, ACE:37)

return constraint_distance_max * 0.9f < constraint_pos_offset;   // ≥90% of leash → "fully constrained"

Read by jump_is_allowed: if true → return 0x47 (block jump). Since acdream never arms the constraint, this stays false → jump never blocked here (= TS-35 current behavior).

2d. TargetManager quantum gates (retail 0x0051aa90 / 0x0051a650)

HandleTargetting():                                        // per-tick, self-throttled
    if PhysicsTimer.CurrentTime - last_update_time < 0.5f: return   // 0.5s throttle
    if target_info != null && target_info.target_position == null: return
    if target_info != null && target_info.status == Undefined
       && target_info.last_update_time + 10.0f < Timer.cur_time:    // 10s staleness
        target_info.status = TimedOut
        PhysicsObj.HandleUpdateTarget(copy(target_info))
    for voyeur in voyeur_table.Values.ToList():
        CheckAndUpdateVoyeur(voyeur)
    last_update_time = PhysicsTimer.CurrentTime

CheckAndUpdateVoyeur(voyeur):
    newPos = GetInterpolatedPosition(voyeur.quantum)       // self.pos + velocity*quantum (dead-reckon)
    if newPos.Distance(voyeur.last_sent_position) > voyeur.radius:   // send-on-significant-move
        SendVoyeurUpdate(voyeur, newPos, Ok)

GetInterpolatedPosition(quantum):
    pos = copy(self.Position); pos.Origin += self.get_velocity() * quantum; return pos

0.5f throttle, 10.0f staleness — retail-tuned quanta (cross-checked ACE; verify against named-retail before treating literally, per ACE's own // ref? caveats).

2e. The voyeur round-trip (peer-to-peer position notification)

Watcher W wants to track target T:
  W.SetTarget(ctx=0, T.id, radius=0.5, quantum=q)
    → W.target_info = new TargetInfo(...)
    → T.add_voyeur(W.id, 0.5, q)                 // W subscribes ON T's voyeur_table
       → T immediately SendVoyeurUpdate(W-voyeur, T.pos, Ok)   // initial snapshot
          → W.receive_target_update(info) → W.ReceiveUpdate(info)
             → W.target_info updated; W.HandleUpdateTarget(info)
                → W.movement_manager.HandleUpdateTarget  (MoveToManager steers)
                → W.position_manager.HandleUpdateTarget   (StickyManager follows)

Each tick, T.HandleTargetting → CheckAndUpdateVoyeur(W-voyeur):
  if T drifted > radius since last sent → SendVoyeurUpdate → W.ReceiveUpdate → W.HandleUpdateTarget

W stops: W.ClearTarget → T.remove_voyeur(W.id)
T despawns: T.exit_world → NotifyVoyeurOfEvent(ExitWorld) → all watchers get ExitWorld
T teleports: T.teleport_hook → NotifyVoyeurOfEvent(Teleported)

This is exactly what the AP-79 adapter approximates (poll target pos, feed HandleUpdateTarget when drift>radius). The voyeur port is a faithful superset: same moveto behavior + correct sticky + timeout/exit/teleport events.

---

3. Two consumers of set_target (both radius 0.5)

Caller	quantum	Meaning
MoveToManager.MoveToObject/TurnToObject	0.0	resend as fast as the 0.5s tick allows
StickyManager.StickTo	0.5	throttled resend

Both go through the SAME CPhysicsObj::set_target → TargetManager::SetTarget, and both receive updates through CPhysicsObj::HandleUpdateTarget → {MovementManager, PositionManager}::HandleUpdateTarget. In acdream the _setTarget/_clearTarget seams (already on MoveToManager) get repointed at the real TargetManager; StickyManager gets its own seam to the same TargetManager.

---

4. acdream integration seams (delegate contracts)

The Core classes stay engine-agnostic via ctor-injected seams (same convention as MoveToManager). Per entity the App layer supplies:

• getPosition : () → Position (world-space, cell + frame)
• getVelocity : () → Vector3
• getRadius : () → float, getHeight : () → float (from setup cylsphere — finally needed here; today MoveToManager passes 0 — see the P4 note)
• getMinterpMaxSpeed : () → float? (null if no interp) — StickyManager speed
• getContact : () → bool (transient Contact bit) — ConstraintManager gate
• getObjectA : uint guid → IPhysicsTargetHandle? — cross-entity resolve (the guid→entity seam; drives voyeur delivery + sticky live-target). Backed by GameWindow's _entitiesByServerGuid.
• handleUpdateTarget : TargetInfo → void — fans to MoveToManager + PositionManager(Sticky)
• clearTarget/interruptCurrentMovement — teardown (already exist on MoveToManager/Motion)
• clock : () → double (real clock, as R4-V5 fixed)

getObjectA returns a small handle exposing the OTHER entity's receive_target_update(TargetInfo) (→ its TargetManager.ReceiveUpdate) + its live Position — enough for SendVoyeurUpdate and sticky's live-target resolve.

---

5. Sub-slice plan

R5-V1 — Core classes + conformance tests (NO wiring; low risk)

New files under src/AcDream.Core/Physics/Motion/ (Position/Sticky/Constraint) and src/AcDream.Core/Physics/Combat/ (TargetManager — retail namespace split):

• PositionManager (facade: adjust_offset chain interp→sticky→constraint, UseTime, StickTo/Unstick/ConstrainTo/UnConstrain/IsFullyConstrained/HandleUpdateTarget).
• StickyManager (§2a math, StickTo/UnStick/UseTime timeout/HandleUpdateTarget/adjust_offset).
• ConstraintManager (§2b/§2c, ConstrainTo/UnConstrain/IsFullyConstrained/adjust_offset).
• TargetManager (§2d/§2e full voyeur system) + TargettedVoyeurInfo + extended TargetInfo.
• InterpolationManager: acdream already has a remote Interp (PhysicsBody interp) — keep it; PositionManager's interp slot delegates to a thin adapter or is left null for the player. (Interp is NOT an R5 retirement target; don't re-port it.)
• Seam interfaces + a test harness with a fake getObjectA wiring two managers to each other. Golden values from ACE + the decoded math above. Tests: sticky steer/clamp/heading, sticky 1s timeout, constraint taper + IsFullyConstrained 90% gate, voyeur subscribe/immediate-snapshot/distance-gate/10s-timeout/exit/teleport, ReceiveUpdate match+heading-fallback, the full W↔T round-trip.
• dotnet build+dotnet test green. Commit. No behavior change (nothing wired).

R5-V2 — Wire TargetManager per-entity; retire AP-79

• Add TargetManager to RemoteMotion + a player-side owner; construct beside the MoveToManager binds. Repoint MoveToManager's _setTarget/_clearTarget/quantum seams at TargetManager.SetTarget/ClearTarget/quantum.
• getObjectA backed by _entitiesByServerGuid (returns a handle to the target's TargetManager). Per-tick: call TargetManager.HandleTargetting() in TickRemoteMoveTo + the player block, BEFORE MoveToManager.UseTime() (retail order).
• Delete the AP-79 tracker fields (TrackedTarget* / _playerMoveToTarget*) and the manual poll blocks — the voyeur round-trip replaces them.
• Register: delete AP-79 row same commit. Visual gate: a server-directed creature chasing the player still tracks + moves identically (the exact behavior AP-79 drove).

R5-V3 — Wire PositionManager (Sticky); retire TS-39; apply mt-0 sticky guid

• Add PositionManager to each entity. Bind MoveToManager.StickTo → PositionManager.StickTo, MoveToManager.Unstick → PositionManager.UnStick.
• Integrate PositionManager.adjust_offset into the per-frame body integration (the composed delta-frame chokepoint — retail's UpdatePositionInternal). This is the load-bearing wiring: sticky steer must ADD to the body's per-tick motion.
• Per-tick PositionManager.UseTime() AFTER MoveToManager.UseTime (retail order).
• Apply the mt-0 wire flags (UpdateMotion.cs already parses them, unconsumed): 0x1 StickToObject → stick_to_object(guid) → PositionManager.StickTo; 0x2 StandingLongJump → MotionInterpreter.StandingLongJump.
• Register: delete TS-39 row same commit. Visual gate: a sticky scenario (server /follow-style sticky moveto or a moving-platform stick) holds the target instead of stopping.

R5-V4 (capstone, optional) — MovementManager facade + #164 + head stance dispatch + docs

• Collapse per-entity Motion+MoveTo into a MovementManager owner (structural; must keep the 183-case + funnel + moveto suites green UNMODIFIED).
• #164: action-replay Autonomous bit (params 0x1000 from per-action autonomy flag, raw 305982) in MotionInterpreter.MoveToInterpretedState action loop.
• Head stance-change dispatch for mt 6-9 (verification item 1 / the S3 exclusion at RetailObserverTraceConformanceTests.cs:33).
• Final register/ISSUES/roadmap/memory + successor handoff.

---

Constraint scope (why TS-35 stays open)

ConstraintManager is the server-position rubber-band leash, armed ONLY from SmartBox::HandleReceivedPosition (arm on every inbound position packet, anchor = self or server-received position) with two constants from GetStart/MaxConstraintDistance (0x0050ebc0 / 0x0050ec10) that are x87 float returns BN elided — literal values unknown (need a live cdb read or Ghidra float-return fix). acdream has no SmartBox leash (its position reconciliation is separate), so:

• Port the class + wire it into PositionManager (IsFullyConstrained routes through it; adjust_offset participates in the chain) for structural faithfulness.
• Do NOT arm it (no ConstrainTo call site) — the leash + jump-blocking + the two unknown constants are out of R5 scope. IsFullyConstrained stays false = TS-35's current behavior. Update TS-35's where to point at the now-real-but-unarmed ConstraintManager; keep the row OPEN. Filing an issue for the leash port + the two unknown constants.

Open verification items (carry into V1 tests / cdb)

1. GetStart/MaxConstraintDistance x87 return constants — unknown (constraint arming, deferred). File as issue.
2. HandleTargetting's 0.5s/10s quanta + StickyTime 1.0s / StickyRadius 0.3f / sticky speed ×5 + 15.0f fallback — ACE values; verify against named-retail.
3. mt-0 header flags: confirm 0x1/0x2 (wire) == decomp 0x100/0x200 shift (recon §4 confirms: same bits, 8-bit motionFlags at bit-8 of the unpack header dword).
4. TargetInfo pass-by-value-vs-ref (ACE's two // ref? markers) — retail copy-constructs (TargetInfo::TargetInfo(&copy, src) at every fan-out); port as copy.

Do-NOT-re-port (already shipped)

MoveToManager (R4, full incl. queue + HandleUpdateTarget consumer), MotionInterpreter (R3, #161 apply-pass), MotionTableManager+GetObjectSequence (R2), CSequence (R1), RemoteWeenie + PhysicsBody.InWorld (R4-V5), InterpolationManager (acdream's remote Interp — not an R5 target).