acdream/docs/research/2026-07-30-constraint-leash-constants.md

# #167 ConstraintManager leash — constants recovered + arming flow (Campaign P P5)

**2026-07-30.** Both #167 blockers are now research-solved; only the port
remains. No cdb session was needed: the two "unknown x87 constants" were
recovered by decoding the raw machine code of the matching binary
(`C:\Users\erikn\Downloads\acclient.exe`, v11.4186, PDB-paired — verified
GUID match per the retail debugger toolchain doc).

## 1. The getters, byte-decoded (FACT)

`CPhysicsObj::GetStartConstraintDistance @ 0x0050ebc0` and
`GetMaxConstraintDistance @ 0x0050ec10` are FPU-return getters whose
`fld` operands Binary Ninja elided (the pseudo-C shows a bare
`this->m_position;`). Raw bytes (file offset 0x10ebc0/0x10ec10):

```
3b 0d 58 3d 84 00   cmp  ecx, [0x00843d58]      ; this == player_object?
75 1d               jnz  non_player
8b 41 4c            mov  eax, [ecx+0x4c]        ; m_position.objcell_id
25 ff ff 00 00      and  eax, 0xFFFF
3d 00 01 00 00      cmp  eax, 0x100
73 07               jae  indoor                 ; low16 >= 0x100 = EnvCell
d9 05 <rdata>       fld  dword [outdoor_const]
c3                  ret
indoor: d9 05 <..>  fld  dword [indoor_const]
c3                  ret
non_player:         ; identical cell test, second constant pair
```

Constant values read from `.rdata`:

| | player outdoor | player indoor | remote outdoor | remote indoor |
|---|---|---|---|---|
| Start (0x007c6abc..c8) | **10.0** | **5.0** | 10.0 | 5.0 |
| Max (0x007c6acc..d8) | **50.0** | **20.0** | 50.0 | 20.0 |

Two consequences (FACT):

1. **The player-vs-remote branch is vestigial** — both sides load
   identical values. Effective semantics: `start = outdoor 10 m /
   indoor 5 m`, `max = outdoor 50 m / indoor 20 m` (indoor = cell low16
   ≥ 0x100).
2. **ACE's `GetStartConstraintDistance` is INVERTED**
   (`ACE PhysicsObj.cs:620`: outdoor 5 / indoor 10). ACE's max mapping
   (outdoor 50 / indoor 20) matches the binary. Do NOT copy ACE's start
   mapping. (feedback_acme_oracle / binary-wins rule.)

## 2. The arming flow — `SmartBox::HandleReceivedPosition @ 0x00453fd0` (FACT)

Pseudo-C lines ~92940-93060. After the update-time staleness gates and
`unset_parent`/`SetPlacementFrame` handling:

- **Remote object** (`arg2 != this->player`): call
  `MoveOrTeleport(obj, &recvPos, ts, arg5, arg6)`; **only if it returns
  nonzero** (the position was NOT hard-teleport-applied), arm the leash
  **anchored to the object's own current position**:
  `ConstrainTo(obj, &obj->m_position, start, max)` (0x00454254-72).
- **Player, teleport-newer** (`newer_event(TELEPORT_TS, ts)`):
  `SmartBox::TeleportPlayer(&recvPos)`, then
  `ConstrainTo(player, &recvPos, start, max)` — anchored to the
  **received** position — then `set_velocity(player, {0,0,0}, 1)`
  (0x0045415f-c0).
- **Player, normal**: `ConstrainTo(player, &recvPos, start, max)`
  anchored to the received position; then, if
  `cmdinterp->UsePositionFromServer() && arg5`,
  `InterpolateTo(&recvPos, -GetAutonomyLevel())` (0x004541c9-422c).

The taper/enforcement side (`ConstraintManager::UseTime` feeding
`adjust_offset`, `IsFullyConstrained = ConstraintDistanceMax * 0.9 <
offset`) is already ported in
`src/AcDream.Core/Physics/Motion/ConstraintManager.cs` (R5-V1,
`docs/research/2026-07-03-r5-managers/`); it has simply never been armed.

## 3. Port shape for P5 (INFERENCE — implementation guidance)

1. Add the four-constant getters (outdoor/indoor by full cell id low16)
   at the body/host layer; keep the vestigial player/remote split OUT
   (note it in a code comment with this doc as the cite).
2. Arm at acdream's inbound-position equivalents of the three branches:
   the remote UpdatePosition acceptance tail (post-`MoveOrTeleport`
   routing in the live-entity network update path) and the local
   player's accepted-Position path (normal + teleport). Anchor per §2.
3. `PhysicsBody.IsFullyConstrained` (register TS-35 stub) becomes a read
   through `PositionManager`/`ConstraintManager`, so
   `jump_is_allowed`'s ported gate fires (WeenieError 0x47) while
   rubber-banding. TS-35 and #167 retire together, same commit.
4. Conformance tests: constant table incl. the ACE-inversion pin
   (outdoor start MUST be 10, not 5); leash-armed jump refusal;
   remote-vs-player anchor difference; teleport-branch velocity zero.

## Open questions

None for the constants/flow. Remaining implementation risk is only
where acdream's position-acceptance seams sit today (J6.3 moved
teleport correlation into Runtime — the implementer must find the
current owner rather than trusting older file cites).

## As-ported (Campaign P Slice P5, 2026-07-30)

The implementation risk flagged above resolved to these CURRENT seam owners
(post-J-slices) — recorded here so the next reader doesn't have to re-derive
them:

- **Constants** — `src/AcDream.Core/Physics/Motion/ConstraintDistance.cs`.
  Keyed purely on the object's own full cell id's low 16 bits (`>= 0x0100` =
  indoor); the vestigial player/remote branch from §1 is deliberately not
  represented as an API parameter.
- **Remote arm** — `src/AcDream.App/Physics/LiveEntityNetworkUpdateController.cs`,
  the inbound `UpdatePosition` handler's remote branch (`update.Guid !=
  _playerServerGuid`), immediately after the `remotePlacementRequired`
  hard-teleport block returns (that block already covers retail's
  `MoveOrTeleport` Branch A / hard-place case; everything reached past it is
  "did not hard-place"). One call site covers BOTH player-remote and NPC
  remotes — retail's `SmartBox::HandleReceivedPosition` doesn't distinguish
  them either, only `GetStart/MaxConstraintDistance`'s now-omitted vestigial
  branch did. Anchored to the live `IPhysicsObjHost.Position` (which reads
  `RemoteMotion.Body.Position` + the tracked cell id), matching retail's
  "anchored to the object's own current position" — since the anchor and
  `_host.Position` read are the same value at call time,
  `ConstraintManager.ConstrainTo`'s initial offset is always 0 regardless of
  whether the routing above just far-snapped or left a near-correction
  queued.
- **Remote per-tick taper + `IsFullyConstrained` push** — already wired
  pre-P5 for the taper (`RuntimeRemotePhysicsUpdater.Tick`/`TickHidden` call
  `PositionManager.AdjustOffset` every tick via the pre-existing R5-V3
  sticky/constraint chain); P5 added the `PhysicsBody.IsFullyConstrained =
  host.PositionManager.IsFullyConstrained()` push at the same two call
  sites, since `MotionInterpreter` only holds a `PhysicsBody` (no host
  reference) and needs a live value to read.
- **Local player arm** — `src/AcDream.Runtime/Gameplay/PlayerMovementController.cs`:
  `SetPositionCore` (teleport: `UnConstrain` then re-`ConstrainTo` after the
  existing `StopCompletelyAtPhysicsObjectBoundary` velocity zero — composed,
  not duplicated) and `CommitPreparedPosition` (mirrors the same pair for
  the deferred player-mode-entry commit path); `BlipPosition` (ForcePosition:
  `ConstrainTo` only, no teardown — matches `SmartBox::BlipPlayer` surviving
  motion/velocity/stick). Anchored to `_body.CellPosition` (the just-applied
  received position).
- **Local player per-tick taper + push** — `PlayerMovementController.Update`
  already called `PositionManager.AdjustOffset` every physics tick pre-P5;
  P5 added the `_body.IsFullyConstrained = PositionManager?.IsFullyConstrained()
  ?? false` push immediately after, at the same chokepoint.
- **TS-35 retirement** — `PhysicsBody.IsFullyConstrained` stayed a plain
  settable bool (not a computed property) so the ~40 pre-existing direct-set
  unit tests keep working; the per-tick pumps above are its single writers
  now, matching the project's per-entity single-owner-write pattern.