acdream/memory/project_session_2026_04_19.md

Session 2026-04-19 — Full retail remote-entity motion port

Big win

Remote characters (viewed from ACdream) now render motion with full retail fidelity — walk, run, strafe, turn, run+turn, and stop all work end-to-end, user-confirmed via live play against ACE + a retail alt.

The port uses PhysicsBody + MotionInterpreter + AnimationSequencer on every remote, mirroring retail's per-entity motion stack. No more RemoteInterpolator shortcut. No timer-based stop heuristics. Pure retail decompile semantics.

Commits this session (main):

• 5bd976e — docs(claude.md): live-server connection + launch workflow
• 795d9c8 — fix(anim): Option B — MotionData-sourced physics velocity
• 00c8a4f — fix(anim): ACE-echo speedMod clobber + sequencer velocity synthesis
• 340dabb — feat(anim): FULL retail remote-entity motion port — walk/run/strafe/turn/stop

All 717 tests green. +233 insertions, -60 deletions net for the big port.

The debugging saga (5+ failed approaches before the right one)

The user was rightly frustrated — we thrashed for hours on remote motion before nailing it. Learnings from every miss, for the benefit of future self:

1. First thought it was a rendering issue — spent time tuning anim framerate / speedMod. Irrelevant.
2. Tried EMA velocity extrapolation for dead-reckoning. Got "stuck-then-glide" because EMA direction lagged turns.
3. Tried queue-based interpolation (InterpolationManager port from ACE). Got "pause at each target" because queue drained between UPs.
4. Tried PosFrames root motion per the research. Zero effect — Humanoid dat's PosFrames are for visual foot placement, NOT world-space body position for grounded characters.
5. Tried AC2D-style heading scalar + formula omega. Shortcut the user explicitly rejected ("AC2D is NOT the retail client").
6. Then: the correct architecture — PhysicsBody + MotionInterpreter per remote, exactly like retail. Worked for walk/run/strafe/stop in one shot.
7. But rotation "snapped" every UP. Added slerp — still snapped. Removed slerp + used formula omega — still snapped. Added observed omega from UP deltas — rotation FROZE entirely.
8. Found the actual bug: PhysicsBody.update_object has MinQuantum = 1/30 s — at our 60fps render tick (~16ms dt), every tick's dt < MinQuantum so update_object returned early, skipping rotation integration entirely. All prior "fixes" were on top of a no-op integration.
9. Fix: manual omega integration per tick, bypassing update_object for rotation. Kept update_object for position (velocity × dt).
10. Final polish: TurnCommand presence as instant on/off switch for ObservedOmega (seeded from π/2 × turnSpeed formula) — rotation begins immediately on turn-start and stops immediately on turn-end instead of coasting via stale observed rate.

Concrete wire-format discoveries (DURABLE)

Critical parser bug (fixed in commit 340dabb): The MovementStateFlag enum bits don't match our earlier parser's assumption. Correct bits per ACE MovementStateFlag.cs:

Field	Wire flag	Earlier parser	Status
CurrentStyle	0x01	0x01	✓
ForwardCommand	0x02	0x02	✓
ForwardSpeed	0x04	0x10	was wrong
SideStepCommand	0x08	0x04	was wrong
SideStepSpeed	0x10	0x20	was wrong
TurnCommand	0x20	0x08	was wrong
TurnSpeed	0x40	0x40	✓

Also: write order is Style, Fwd, Side, Turn then FwdSpd, SideSpd, TurnSpd (commands first, speeds second — not in bit-order).

ACE's stop signals (discovered from live packet captures):

1. UpdateMotion with ForwardCommand flag CLEARED → retail's default ForwardCommand=Invalid (0) value → our handler must map null command to Ready (0x41000003). Previously we treated null as "keep current motion" which made alts run forever.

2. ForwardSpeed=0 on wire → IS a valid speed value (not "omitted default 1.0"). ACE sends this when alt releases W while still having WalkForward cmd. Previously we clamped fs > 0f ? fs : 1f which produced "slow walk that never stops."

3. ACE does NOT send HasVelocity on UpdatePosition for player broadcasts. Velocity field is always absent on player UP (even during active running). Don't treat null-velocity as a stop signal — it's just "no velocity info." This caused an earlier regression where every UP force-stopped the remote.

Architecture: how remote motion works now

Per remote entity:

RemoteMotion {
    PhysicsBody Body;           // position + velocity integration
    MotionInterpreter Motion;   // motion state machine (forward/side/turn cmds)
    Vector3 ObservedOmega;      // angular velocity (seeded from π/2 × turnSpeed)
}

On UpdateMotion:

• ForwardCommand → MotionInterpreter.DoInterpretedMotion(cmd, speed). Absent flag → Ready (= stop).
• SideStep cmd → DoInterpretedMotion(sideCmd, sideSpd). Absent → StopInterpretedMotion(SideStepRight/Left).
• Turn cmd → DoInterpretedMotion(turnCmd, turnSpd) AND seed ObservedOmega = ±π/2 × turnSpd. Absent → stop + zero ObservedOmega.
• Animation cycle selection: forward if active, else sidestep, else turn, else Ready.

On UpdatePosition:

• Hard-snap Body.Position + Body.Orientation (retail FUN_00514b90 set_frame).
• If HasVelocity + |v| < 0.2 → StopCompletely + SetCycle(Ready).

Per-tick in TickAnimations:

1. Motion.apply_current_movement() → writes Body.Velocity via get_state_velocity (retail FUN_00528960).
2. Manual omega integration: Orientation *= quat(ObservedOmega × dt). Must be manual because Body.update_object has MinQuantum=1/30s which skips our 60fps ticks.
3. Body.update_object(now) → Euler integrates Position += Velocity × dt.
4. entity.Position = Body.Position; entity.Rotation = Body.Orientation.

What's still open

1. Jump for remotes. Not yet wired through MotionInterpreter.jump

   • LeaveGround. Remote jumping currently does nothing visible. Low priority — user didn't report it as blocking.

2. Retail observer view of ACdream player. User's last comment before calling it: "we also need to investigate ACdream's movement in retail client. Does not look perfect." This is the next session's starting point. We haven't triaged yet; user should describe what the retail observer sees (speed mismatch? strafe invisible? turn not broadcasting? jump missing?). Then we investigate our outbound MoveToState wire and per-tick broadcast triggers.

3. Minor polish — the following are not blocking but worth cleaning if we touch this code again:

   • TargetOrientation field on RemoteMotion is now unused (legacy from the slerp approach); can be removed.
   • PrevServerRot / HasPrevRot fields same story.
   • ObservedVelocity on RemoteMotion is preserved but stale; can be removed if HUD doesn't use it.

Durable rules for next time

• ALWAYS check actual wire bits against ACE's enum definitions. The MovementStateFlag mapping was wrong for months. Diagnostic dumps pay for themselves in minutes.
• When a packet field is "absent," retail typically resets to default (Invalid/zero). Do NOT treat absent as "keep state." The bulk-copy semantics of FUN_0051F260 reset each field from the unpacked struct.
• PhysicsBody.update_object is built for 30fps sub-stepping, NOT 60fps render ticks. Using it for per-frame rotation means 50% of frames are no-ops. For high-frequency integration, bypass.
• Soft-snap + hard-snap fight each other. Pick one mechanism and commit. Retail hard-snaps on UP and relies on formula omega matching server rate.
• The "AC2D is a valid reference" trap: the user will reject any shortcut that isn't from the retail decompile. Dispatch opus agents to read chunk_*.c for every motion/physics question.

Pickup for next session

First thing: ask the user what looks wrong from the retail observer's view. Specifically:

1. Walking/running speed + leg cadence.
2. Strafing visible or invisible to retail.
3. Turning — smooth or snap on retail side.
4. Start/stop — glide past stop?
5. Jump — rendering at all?
6. Idle stance.

From there, investigate our outbound wire path:

• PlayerMovementController.Update → what MoveToState does it emit?
• MoveToState wire builder in AcDream.Core.Net.
• Sequence counters (instance, serverControl, teleport, forcePosition).
• Any missing flags ACE expects on our outbound (HoldKey, RawMotionFlags, etc.).

Cross-check against references/holtburger/crates/holtburger-core/ src/client/movement/system.rs which is a known-working AC client sender.