acdream/docs/research/2026-05-06-locomotion-cycle-transitions/investigation-prompt.md

Locomotion-cycle transitions on observed remotes — investigation prompt

Hand-off date: 2026-05-06 Status: open. ISSUES.md #39 captured the Run↔Walk-forward variant; this prompt expands to the full locomotion transition matrix and lays out a TTD-driven investigation against retail to ground the fix.

This document is a self-contained briefing for an agent (or fresh session) picking this up. The TTD toolchain landed in commit e3e5bf5 (#44) and is the primary investigative tool here.

---

What problem are we trying to solve?

When acdream observes a remote-driven player character (typically a parallel retail acclient.exe connected to the same local ACE), the visible leg-cycle animation does not always switch when the actor changes locomotion mode. The body translates at the right speed (server-driven velocity is fine), but the legs keep playing whichever cycle was active before.

The full set of transitions where the bug may surface:

#	Transition	Wire change	Likely cause
1	Run forward ↔ Walk forward (Shift toggle while W held)	HoldKey + ForwardSpeed only	ACE doesn't broadcast UM (no ForwardCommand change); cycle refinement must come from UP-derived velocity
2	Run backward ↔ Walk backward (Shift toggle while S held)	HoldKey + ForwardSpeed only	Same as #1, backward axis
3	Forward ↔ Backward (W→S or S→W direct flip)	ForwardCommand changes (e.g. WalkForward → WalkBackward)	ACE broadcasts a UM; cycle should update from UM directly
4	Fast strafe-left ↔ Slow strafe-left (Shift toggle while A held)	HoldKey + SideSpeed only	Same as #1 / #2 — speed-bucket only
5	Fast strafe-right ↔ Slow strafe-right (Shift toggle while D held)	HoldKey + SideSpeed only	Same
6	Strafe-Left ↔ Strafe-Right (A↔D direct flip)	SideCommand changes	ACE broadcasts UM
7	Forward ↔ Strafe (W↔A, W↔D, etc.)	ForwardCommand or SideCommand changes	UM broadcast

#39 in ISSUES.md focused on #1. This investigation widens scope to the whole matrix because the underlying wire pattern is the same shape: half the transitions broadcast a UM, the other half rely on UP-derived velocity. A correct fix should handle both classes uniformly.

---

What we already know (don't re-discover)

From the prior 2026-05-03 investigation (docs/research/2026-05-03-remote-anim-cycle/) and #39 in docs/ISSUES.md:

• ACE only broadcasts a fresh UpdateMotion when the wire's ForwardCommand byte changes — i.e. on direction-key state changes. Toggling Shift while W held changes ForwardSpeed and HoldKey but NOT ForwardCommand, so ACE does NOT broadcast a UM for the demote/promote.
• Speed changes still propagate via UpdatePosition (UP). Position-delta velocity changes between Run-pace and Walk-pace, confirmed via [VEL_DIAG] serverSpeed varying ~2.5 m/s (walk) ↔ ~9 m/s (run).
• Retail's inbound code uses UP-derived velocity to refine the visible cycle when no UM tells it. Acdream has the equivalent function — ApplyServerControlledVelocityCycle in GameWindow.cs:3274 — but it's gated if (IsPlayerGuid(serverGuid)) return; for player remotes, exactly the case where the gap matters.
• The fix sketch is small (~10 lines): un-gate ApplyServerControlledVelocityCycle for player remotes when currentMotion is a locomotion cycle. Add a LastUMUpdateTime grace window so fresh UMs win over UP-velocity refinement.
• Outbound from acdream is fine — the matrix in #39 confirms retail observers see acdream's transitions correctly. The bug is purely in acdream's RECEIVE path.

What's NOT yet confirmed (and is the primary goal of this investigation):

• Which exact retail function does the cycle refinement when no UM arrives? Hypothesis: CPhysicsObj::unpack_movement → MovementManager::unpack_movement → some velocity-aware cycle picker. We need to identify the function name and what state it reads.
• What grace window does retail use between UM and UP-derived refinement? Our hypothesis is ~500 ms but it may be different.
• Does retail use SideSpeed or SideCommand changes the same way for strafe transitions?

---

TTD-driven workflow

The toolchain shipped in #44 (commit e3e5bf5). Bootstrap is one-time per machine — see CLAUDE.md "TTD recordings (offline replay)" or tools/ttd-record.ps1 header.

Recording scenario

You need two retail acclient.exe instances running on the same local ACE — one as the recorded process, one as the actor. Acdream can be involved as a third client for cross-checking but is not strictly required for the recording itself.

Setup:

1. Launch retail #1 on testaccount / +Acdream (or any character).
2. Launch retail #2 on a second account / character. It must be on the same landblock so retail #1 can see it.
3. Position retail #2 in retail #1's view, ~10 m away.
4. In an elevated PowerShell, attach TTD to retail #1 (the observer):

   tools\ttd-record.ps1 -RingMaxMB 512
   

5. Wait for Recording is now active. Retail #1 will be ~10× slower — that's expected.

Scenario (drive on retail #2, ~60 seconds total):

Phase 1 — Forward speed:    Hold W (2 s) → +Shift → -Shift → +Shift → -Shift → release W (idle 1 s)
Phase 2 — Backward speed:   Hold S (2 s) → +Shift → -Shift → +Shift → -Shift → release S (idle 1 s)
Phase 3 — Forward↔Back flip: Hold W (2 s) → release W → Hold S (2 s) → release S
Phase 4 — Strafe-Left speed: Hold A (2 s) → +Shift → -Shift → +Shift → -Shift → release A
Phase 5 — Strafe-Right speed: Hold D (2 s) → +Shift → -Shift → +Shift → -Shift → release D
Phase 6 — Strafe L↔R flip:  Hold A (2 s) → release A → Hold D (2 s) → release D
Phase 7 — Forward↔Strafe:   Hold W (2 s) → release W → Hold D (2 s) → release D

After phase 7, Ctrl+C the TTD recording. Trace lands at ~/.ttd/traces/acclientNN.run.

Query strategy

The recording captured ~7 phases in ~60 sec. Each phase produced specific UM and/or UP traffic. Goal: for each phase identify what retail's receive code did to update the visible cycle.

Start with a .cdb script under tools/ttd-queries/locomotion.cdb:

.echo === Top motion-receive entry points ===
dx -r2 @$cursession.TTD.Calls("acclient!CPhysicsObj::unpack_movement").Take(20)
dx -r2 @$cursession.TTD.Calls("acclient!MovementManager::unpack_movement").Take(20)

.echo === Cycle-update functions called ===
dx -r2 @$cursession.TTD.Calls("acclient!*set_animation*").GroupBy(c => c.Function).Select(g => new { Name = g.First().Function, Count = g.Count() }).OrderByDescending(x => x.Count)
dx -r2 @$cursession.TTD.Calls("acclient!*SetCycle*").GroupBy(c => c.Function).Select(g => new { Name = g.First().Function, Count = g.Count() }).OrderByDescending(x => x.Count)
dx -r2 @$cursession.TTD.Calls("acclient!*play_*").GroupBy(c => c.Function).Select(g => new { Name = g.First().Function, Count = g.Count() }).OrderByDescending(x => x.Count)

.echo === Velocity / position-update handlers ===
dx -r2 @$cursession.TTD.Calls("acclient!*UpdatePosition*").GroupBy(c => c.Function).Select(g => new { Name = g.First().Function, Count = g.Count() }).OrderByDescending(x => x.Count)
dx -r2 @$cursession.TTD.Calls("acclient!CPhysicsObj::set_velocity").Take(15)

.echo === DONE ===
q

Run it:

tools\ttd-query.ps1 -Script tools\ttd-queries\locomotion.cdb

Then iterate. Use the function-name hits to guide the next query — inspect call args (Take(N) instead of Count()), navigate to specific TTD positions and dump struct fields with dt acclient!ClassName <addr>.

The named-retail decomp at docs/research/named-retail/acclient_2013_pseudo_c.txt has the source for every retail function. Grep it by class::method to read what the function does, then use TTD to confirm what it does at runtime.

Specifically what to look for

For each phase in the recording, answer:

1. Did a UM arrive? Look for calls to the receive entry points around that phase's time window. UM dispatch should fire on direction-key changes (phases 3, 6, 7) but NOT on Shift-only toggles (phases 1, 2, 4, 5).
2. What function refined the cycle when no UM arrived? Hypothesis is something in the velocity-aware path. Find the symbol, read the decomp, document the conditions.
3. What threshold/grace logic is in place? Retail must have some way to prevent UP-velocity refinement from fighting a fresh UM. Usually a timestamp comparison.

---

The fix

The fix lives in src/AcDream.App/Rendering/GameWindow.cs:3274 (ApplyServerControlledVelocityCycle). Current code returns early for player remotes. The fix is to:

1. Un-gate the early return when the current motion is a locomotion cycle. Locomotion cycles to detect: 0x44000007 (Run forward), 0x45000005 (Walk forward), backward equivalents, sidestep variants. Keep the gate when the motion is non-locomotion (e.g. emotes, attacks).
2. Add a LastUMUpdateTime per remote. Touch it in the UM handler path. In ApplyServerControlledVelocityCycle, skip refinement if (now - LastUMUpdateTime) < graceMs. Start with graceMs = 500 and tune against the TTD findings.
3. Use UP-derived velocity to pick the speed bucket. Existing logic in ServerControlledLocomotion.PlanFromVelocity already does this — verify thresholds match retail's bucketing (TTD will tell you the exact boundaries retail uses).

For direction-flip transitions (phases 3, 6, 7), the UM handler path should already work — the visible cycle should update from the UM directly. Confirm in-client that those transitions are clean BEFORE shipping the velocity-fallback fix; if they're broken too, that's a separate UM-handler bug that needs its own investigation.

---

Acceptance criteria

In acdream observing a retail-driven character:

• Phases 1, 2, 4, 5 (Shift toggles): visible leg cycle switches Run↔Walk / Fast↔Slow within ~200 ms of the wire change.
• Phases 3, 6, 7 (direction flips): visible cycle updates within ~100 ms (UM is direct-path, faster than UP).
• No regression on already-working cases:
  • acdream-on-acdream (matrix row in #39)
  • retail observers viewing acdream (works today)
  • Idle ↔ Run transitions
  • Idle ↔ Walk transitions
  • Combat-mode locomotion (if testable)
• No spurious cycle thrashing during turning while running — ObservedOmega-driven body rotation must not trigger velocity-bucket changes mid-cycle.

---

Files to read first

In this order:

1. docs/ISSUES.md — issue #39 (Run↔Walk specific) and #44 (TTD toolchain)
2. docs/research/2026-05-03-remote-anim-cycle/investigation-prompt.md — prior investigation, what's been tried, what works
3. CLAUDE.md — "Retail debugger toolchain" section (live cdb + "TTD recordings (offline replay)" subsection)
4. memory/project_retail_debugger.md — durable lessons + TTD addendum
5. memory/project_retail_motion_outbound.md — what retail's outbound motion path looks like (cdb live trace from 2026-05-01)

Then:

6. src/AcDream.App/Rendering/GameWindow.cs — OnLiveMotionUpdated (~line 3203) and ApplyServerControlledVelocityCycle (~line 3274)
7. src/AcDream.Core/Physics/ServerControlledLocomotion.cs — speed bucket thresholds in PlanFromVelocity
8. docs/research/named-retail/acclient_2013_pseudo_c.txt — grep by the symbol names you discover from the TTD trace
9. references/ACE/Source/ACE.Server/Network/GameMessages/Messages/GameMessageUpdateMotion.cs — what ACE actually sends for each transition (ground truth for wire content)

---

Watchouts

• The named-retail leaf MoveToStatePack::UnPack returned 0 hits in TTD. Don't query it directly; start at CPhysicsObj::unpack_movement or MovementManager::unpack_movement and walk down the call chain. Release-build inlining + virtual dispatch hide leaf decoders from TTD's static call counting (#44 lesson).
• Verify positioning IN-CLIENT before recording. A trace where retail #1 can't see retail #2 is wasted bytes. Walk both characters to within visible range, confirm the actor is rendered on the observer's screen, THEN attach TTD. The 30-min validation experiment on 2026-05-06 wasted its main probe because of this — don't repeat.
• Outbound encoding quirk in our wire path (CLAUDE.md "Outbound motion wire format"): acdream sends WalkForward (0x05) + HoldKey.Run for run, which ACE auto-upgrades to RunForward (0x07) when relaying to remote observers. So the inbound parser sees fwd=0x07 for "remote is running." Don't get confused if outbound code shows 0x05 but inbound shows 0x07 — that's normal ACE behavior.
• TTD ring buffer with 512 MB max + ~60 sec recording should fit the whole scenario without rollover. If you record longer, consider bumping to 1024 MB or chopping the scenario into multiple recordings.
• Don't kill the TTD process with Stop-Process — it kills retail too. Use Ctrl+C in the TTD window or TTD.exe -stop <pid> from another elevated shell.

---

Definition of done

This investigation is done when:

1. The TTD trace + queries identify the exact retail function(s) that refine the cycle from UP-derived velocity. Function name(s) + address(es) documented in docs/research/2026-05-06-locomotion-cycle-transitions/findings.md.
2. The threshold/grace logic retail uses is documented (timing values, conditions).
3. ApplyServerControlledVelocityCycle un-gating shipped in acdream with the corresponding test and visual verification on all 7 phases.
4. ISSUES.md #39 closed with the commit SHA.
5. Memory project_retail_motion_outbound.md (or a new note for the inbound side) gets the durable lessons appended.

---

Time estimate

• Recording: ~30 min (setup, two retail clients, scenario execution)
• Initial query passes + decomp cross-reference: ~1–2 hours
• Implementation + iteration: ~2–4 hours
• Visual verification + commit: ~30 min

Total: half a day to a full day depending on how clean retail's path is.

If after the first TTD pass the retail receive code looks fundamentally different from what ApplyServerControlledVelocityCycle is doing, stop and reassess — the fix shape may need to change. Don't try to ram a mismatched approach through.