acdream/docs/research/2026-07-01-d6-motion-interp-pseudocode.md

# D6 — CMotionInterp motion-normalization port: pseudocode + integration map

Date: 2026-07-01
Phase: **L.1 / L.2b follow-up (D6)** — port retail's raw→interpreted motion
normalization so local velocity for backward/strafe-left comes from the retail
source instead of hand-mirrored controller code.
Standard: **decomp-verbatim.** Retail decomp is the oracle; ACE
`MotionInterp.cs` is the secondary oracle and was confirmed to match retail
**byte-for-byte** on every constant and branch (understand-phase workflow,
2026-07-01).

Oracle anchors (all in `docs/research/named-retail/acclient_2013_pseudo_c.txt`):
- `CMotionInterp::adjust_motion` — `0x00528010`, lines 305343-305400
- `CMotionInterp::apply_run_to_command` — `0x00527be0`, lines 305062-305123
- `CMotionInterp::get_state_velocity` — `0x00527d50`, lines 305160-305204
- `CMotionInterp::apply_raw_movement` — `0x005287e0`, lines 305817-305834
Secondary oracle: `references/ACE/Source/ACE.Server/Physics/Animation/MotionInterp.cs`
(constants L26-32; `adjust_motion` L394-428; `apply_run_to_command` L525-562;
`get_state_velocity` L678-700; `get_leave_ground_velocity` L654-663;
`apply_raw_movement` L506-523).

## Constants (retail = ACE, verified)

| name | value | retail anchor |
|---|---|---|
| BackwardsFactor | `0.649999976` | `007c8910`; WalkBackwards speed `*= -BackwardsFactor` |
| WalkAnimSpeed | `3.11999989` | `007c891c`; forward `v.Y = WalkAnimSpeed * fwdSpeed` |
| RunAnimSpeed | `4.0` | RunForward `v.Y`; also `maxSpeed = RunAnimSpeed * rate` |
| SidestepAnimSpeed | `1.25` | sidestep `v.X`; adjust_motion divisor |
| SidestepFactor | `0.5` | adjust_motion sidestep scale |
| RunTurnFactor | `1.5` | apply_run_to_command TurnRight |
| MaxSidestepAnimRate | `3.0` | apply_run_to_command SideStepRight clamp |

MotionCommand hex: `0x45000005`=WalkForward, `0x45000006`=WalkBackwards,
`0x44000007`=RunForward, `0x6500000d`=TurnRight, `0x6500000e`=TurnLeft,
`0x6500000f`=SideStepRight, `0x65000010`=SideStepLeft.

## The four functions (faithful pseudocode)

### apply_raw_movement (orchestrator) — 0x005287e0
```
if physics_obj == null: return
// copy 7 raw fields into interpreted
interp.current_style    = raw.current_style
interp.forward_command  = raw.forward_command ; interp.forward_speed  = raw.forward_speed
interp.sidestep_command = raw.sidestep_command; interp.sidestep_speed = raw.sidestep_speed
interp.turn_command     = raw.turn_command    ; interp.turn_speed     = raw.turn_speed
// normalize EACH channel with ITS OWN per-channel hold key
adjust_motion(ref interp.forward_command,  ref interp.forward_speed,  raw.forward_holdkey)
adjust_motion(ref interp.sidestep_command, ref interp.sidestep_speed, raw.sidestep_holdkey)
adjust_motion(ref interp.turn_command,     ref interp.turn_speed,     raw.turn_holdkey)
apply_interpreted_movement(arg2, arg3)   // acdream: apply velocity via get_state_velocity
```

### adjust_motion(ref cmd, ref speed, holdKey) — 0x00528010
```
if weenie != null and !weenie.IsCreature(): return    // non-creature: no adjust
switch cmd:
  RunForward:   return                                  // already normalized — NO holdkey path
  WalkBackwards: cmd = WalkForward;   speed *= -BackwardsFactor   // -0.649999976
  TurnLeft:      cmd = TurnRight;     speed *= -1
  SideStepLeft:  cmd = SideStepRight; speed *= -1
// after remap, sidestep anim-rate scale:
if cmd == SideStepRight:
    speed *= SidestepFactor * (WalkAnimSpeed / SidestepAnimSpeed)   // (3.12/1.25)*0.5 ≈ 1.24799995
// hold-key (runs for everything EXCEPT the RunForward early-return):
if holdKey == Invalid: holdKey = raw.current_holdkey
if holdKey == Run: apply_run_to_command(ref cmd, ref speed)
```
GOTCHA: RunForward early-returns and does NOT run the hold-key path. The
sidestep negate happens BEFORE the ×1.248 scale (so SideStepLeft = -1.248*speed).

### apply_run_to_command(ref cmd, ref speed) — 0x00527be0
```
speedMod = 1.0
if weenie != null: speedMod = weenie.InqRunRate(out r) ? r : MyRunRate
switch cmd:
  WalkForward:
      if speed > 0: cmd = RunForward       // promote ONLY when moving forward (sign gate)
      speed *= speedMod                     // UNCONDITIONAL — applies to backward too (negative speed)
  TurnRight:
      speed *= RunTurnFactor                // *1.5
  SideStepRight:
      speed *= speedMod
      if abs(speed) > MaxSidestepAnimRate:  // clamp to ±3.0 (ACE resolves the {test ah,0x5} polarity)
          speed = speed > 0 ? MaxSidestepAnimRate : -MaxSidestepAnimRate
```
GOTCHA: WalkForward `speed *= speedMod` is unconditional — so **backward
DOES get run-scaled** (resolves the UN-5 "backward cites nothing" doubt in
acdream's favor). The walk→run promotion is sign-gated: backward keeps a
negative speed so it stays WalkForward (not promoted).

### get_state_velocity() -> local Vector3 — 0x00527d50
```
v = (0,0,0)
if interp.sidestep_command == SideStepRight: v.X = SidestepAnimSpeed * interp.sidestep_speed  // 1.25*s
if      interp.forward_command == WalkForward: v.Y = WalkAnimSpeed * interp.forward_speed       // 3.12*s
else if interp.forward_command == RunForward:  v.Y = RunAnimSpeed  * interp.forward_speed       // 4.0*s
v.Z = 0
rate = MyRunRate; if weenie != null: weenie.InqRunRate(ref rate)
maxSpeed = RunAnimSpeed * rate                          // 4.0 * rate
if v.Length() > maxSpeed: v = normalize(v) * maxSpeed   // PORT ACE'S FORM — decomp operand
                                                        // names are wrong (x87 register aliasing)
```
GOTCHA: backward/strafe-left produce velocity here ONLY because adjust_motion
already converted them to WalkForward/SideStepRight with negated speed. Z (jump)
is added by the caller `get_leave_ground_velocity`, AFTER this clamp.

## acdream current state (what D6 replaces)

Two divergent velocity paths (verified in source):
- **PATH A** — `MotionInterpreter.get_state_velocity` (`MotionInterpreter.cs:599-648`)
  is faithful but only handles WalkForward/RunForward/SideStepRight; returns 0
  for WalkBackward + SideStepLeft because `adjust_motion` is **not ported** (the
  InterpretedState holds the un-normalized command).
- **PATH B** — the controller bypass (`PlayerMovementController.cs`): grounded
  velocity block builds body-local velocity by hand — forward `localY=stateVel.Y`
  (`:986`), backward `localY=-(WalkAnimSpeed*0.65*runMul)` (`:988`), strafe
  `localX=±SidestepAnimSpeed*runMul` (`:994/:996`); `runMul = InqRunRate if Run
  else 1.0` (`:981-983`). The **same formulas are re-copied in the jump block**
  (`:1072`, `:1076-1079`) because LeaveGround→get_state_velocity would zero
  backward/strafe. This duplication is register rows **TS-22** + **UN-5**.

Integration seams:
- Input enters at `PlayerMovementController.Update(dt, MovementInput)` (`:838`);
  section 2 (`:911-1000`) maps input → `_motion.DoMotion`/`DoInterpretedMotion`
  + the hand-built velocity.
- Velocity is consumed by `_body.set_local_velocity` (`:998`, jump `:1090`) →
  physics integration (`:1096-1130`) → `ResolveWithTransition` (`:1136-1160`).
- The **outbound wire** (section 6, `:1329-1399` → MovementResult → GameWindow
  `:8264-8388`) is a SEPARATE construction (the L.2b RawMotionState); it sends
  the RAW commands (WalkForward+HoldKey.Run, backward/strafe @1.0) and ACE/the
  observer runs adjust_motion. D6 must NOT change these wire bytes.

## Behavior changes D6 introduces (retail-faithful; flag for smoke test)

1. **Strafe ~20% faster.** Current `1.25×runRate`; retail `1.25 × 1.248
   (adjust_motion sidestep scale) × runRate = 1.56×runRate`, then clamped via
   `SideStepSpeed ≤ 3.0` (so v.X ≤ 3.75). acdream is currently missing the 1.248
   scale + the 3.0 clamp.
2. **Sidestep ±3.0 clamp becomes active** at high run rates.
3. **Backward unchanged** for typical run rates (already retail-faithful:
   `3.12×0.65×runRate`), now sourced from the real pipeline.
4. **Backward/strafe-left no longer zero** out of `get_state_velocity` (the
   TS-22 bug class is retired at the source, not hand-patched).

## Out of scope for D6 (follow-ups)

- **Turn**: `get_state_velocity` does not produce turn velocity (turn is
  angular). acdream drives Yaw directly (`RemoteMoveToDriver.TurnRateFor`,
  ~90°/135° per sec). D6 keeps direct-Yaw turn; routing turn through interpreted
  angular velocity is a separate slice. `adjust_motion` on the turn channel is
  still ported (for completeness + the wire), but it does not change turn feel.
- **RawMotionState unification**: retail uses ONE raw state for both the wire
  and the velocity pipeline. D6 keeps the L.2b wire construction separate and
  builds/normalizes a velocity-side raw state; unifying the two is a later slice.
- `apply_current_movement` full sequence (style/forward/sidestep/turn/action
  ordering, `CMotionTable::GetObjectSequence`) — the understand-phase extractor
  for this one hit the structured-output cap; re-extract when the animation
  sequencing slice needs it. Not required for the velocity port.

## Design decisions (locked with the user 2026-07-01)

1. **Full unification.** ONE `AcDream.Core.Physics.RawMotionState` (the L.2b
   type) is built from `MovementInput` and drives BOTH the outbound wire packing
   AND the local velocity/turn pipeline (`apply_raw_movement` →
   `get_state_velocity` + turn omega). The separate GameWindow wire-construction
   is retired; `MovementResult` carries the raw state, GameWindow packs it.
2. **`forward_speed = 1.0` on run (decomp-forced).** The raw `forward_speed`
   must be `1.0` when running, because `apply_run_to_command` multiplies by
   run-rate — carrying `runRate` in the raw state would double-scale to
   `runRate²`. So the wire now sends `forward_speed=1.0` (omitted by
   default-difference) + `HoldKey.Run`, NOT the current `runRate`. This is the
   retail-faithful encoding (observer/server derives the run speed). **Acceptance
   = the smoke echo:** send `1.0`, confirm the `UM` echo still shows the player
   at `~runRate` (⇒ ACE recomputes from run skill ⇒ correct). If the echo shows
   `~1.0`, ACE relays literally and the wire half reverts. The L.2b golden tests
   update to the faithful encoding (forward_speed omitted on run).
3. **Turn ported to interpreted, feel unchanged.** Local turn is driven from the
   interpreted `turn_speed` (`adjust_motion`: TurnLeft→TurnRight `×-1`, `×1.5`
   run) via `omega.Z = ±(π/2) × turn_speed` — the SAME formula the remote path
   already uses (`GameWindow.cs:4845`). Numerically identical to today's
   `TurnRateFor` for the local player (both `π/2 × RunTurnFactor`), so no
   turn-feel change; the fixed `TurnRateFor` direct-Yaw is replaced by the
   pipeline. **AP-9 stays** (the `π/2` base rate is still an approximation of the
   per-creature TurnSpeed; wiring that is a separate follow-up).
4. **References caveat.** Only `references/WorldBuilder` is checked out in this
   worktree; ACE/holtburger are not. The retail decomp
   (`docs/research/named-retail/`) is the sole in-repo oracle and was verified
   directly for all four functions. ACE values quoted here are training-memory
   cross-checks that happen to match the decomp — do not cite ACE file:lines.

**Retires / touches:** register **TS-22** deleted (adjust_motion ported;
get_state_velocity no longer returns 0 for backward/strafe-left). **UN-5**
resolved (run-scaling backward IS retail — `apply_run_to_command` unconditional
`*speedMod`). **AP-9** stays (turn base rate). A wire-encoding change row is
added if the echo test confirms `forward_speed=1.0`.

**Implementation slices:**
- **D6.1 (delegated, bounded):** port `adjust_motion` + `apply_run_to_command`
  into `MotionInterpreter` + conformance tests, tests-first, against this doc.
- **D6.2 (lead, delicate):** `apply_raw_movement` orchestrator + build the
  unified `RawMotionState` in `PlayerMovementController` from `MovementInput`,
  route grounded + jump velocity through `get_state_velocity`, drive turn omega
  from interpreted `turn_speed`, thread the raw state through `MovementResult`
  to the GameWindow packer, delete the hand-mirrors (`:988/:994/:996` + jump
  `:1072/:1076-1079`) and the `TurnRateFor` direct-Yaw, update the L.2b golden
  tests. Then smoke (echo + strafe/backward/turn/jump feel).

## Conformance-test targets

- `adjust_motion`: each of the 7 command transforms + the sidestep 1.248 scale +
  the backward -0.65 + the negate-before-scale order + the RunForward no-op +
  the non-creature early return + per-channel holdKey inheritance.
- `apply_run_to_command`: WalkForward promote-when-speed>0 + unconditional
  `*speedMod`; TurnRight ×1.5; SideStepRight ×speedMod + ±3.0 clamp (test the
  boundary at runRate that pushes |speed| past 3.0).
- `get_state_velocity`: backward + strafe-left now non-zero (the TS-22 fix);
  the maxSpeed normalize clamp; strafe = 1.56×runRate clamped to ≤3.75.
- `apply_raw_movement`: 3-channel copy + per-channel adjust + the run-promotion
  of a running-forward raw state.