acdream/docs/research/2026-05-03-remote-anim-cycle/investigation-prompt.md

# Remote-entity animation-cycle bug — investigation prompt

**Hand-off date:** 2026-05-03
**Status:** open. Multiple shipped fixes today reduced the remote-entity motion problem to a single residual symptom — the **leg-cycle on observed remotes does not visibly switch between Walk / Run / Ready** even though every signal says it should. Plus minor blippiness in steady motion.

This document is a self-contained briefing for an agent (or fresh session) picking this up.

---

## What problem are we trying to solve?

When acdream observes another player driven by a parallel **retail** acclient.exe (connected to the same local ACE server), the remote character's **leg animation cycle** does not visibly change when that retail player switches between Run / Walk / Idle. The remote's **body** moves at the right speed (translation works), but the **legs keep playing whatever cycle was active before**.

User test: drive `+Acdream` (or any retail char) through `Press W (run) → release → Press shift+W (walk) → release` while observing in acdream's window. The body moves correctly but the leg cycle stays in idle pose / walk pose / whatever it was.

User-confirmed working perspectives:
- Local +Acdream's transitions in acdream **work** ✓
- +Acdream observed FROM a parallel retail client **work** ✓ (proves our outbound is fine)

So the bug is **specifically** in how acdream renders the visual cycle for an observed remote-driven character.

---

## What we shipped today (commits in chronological order)

```
0997f96  fix(motion): landing fallback + TurnLeft omega sign + vel diagnostic (L.3.2)
9960ce3  fix(motion): preserve signed TurnSpeed for remote turn animations
842dfcd  fix(motion): retail-faithful per-frame remote tick (L.3.2 follow-up)
b1d8e12  research(motion): cdb live trace of retail walk-to-run transition
a45c21e  fix(motion): retail-faithful remote tick — clear body.Velocity, drive via seqVel
c06b6c5  fix(motion): full queue reset on locomotion-cycle direct transitions  [partly reverted]
a2ae2ae  revert: AnimationSequencer locomotion-cycle full-reset and link-skip
357dcc0  fix(motion): SetCycle forces _currNode onto first newly-enqueued node;
         skip SubState commands in UM Commands list iteration
```

**User-confirmed wins from the above:**
- Body translation no longer races (was 2× server pace; now matches)
- Run-in-circles smooth (rectangle-effect gone — body rotates properly between UPs)
- Jump landing position correct (no mid-air force-land)
- Jump landing animation works (Falling → Ready visible)
- Turn-left visibly turns left (was animating right with snap-back)
- Signed TurnSpeed preserved (ACE encodes TurnLeft as `TurnCommand=TurnRight, Speed=negative`)

**User-confirmed remaining bugs:**
1. **Walk↔Run leg cycle on observed remotes does not visibly switch.** Body advances at correct new speed but legs continue playing previous cycle.
2. **Residual small "blip" corrections during steady-state motion** (run, walk, strafe). User describes this as a periodic micro-jitter — small but visible.
3. **(Possible)** ~20% steady-state walk overshoot (`maxSeqSpeed=3.120, serverSpeed≈2.6`) per VEL_DIAG measurements — not yet root-caused. May or may not be related to (2).

---

## What we proved about bug 1 (the cycle-doesn't-switch)

Per the diagnostic infrastructure built today:

| Signal | Result |
|---|---|
| `[FWD_WIRE]` — wire-arrival ForwardCommand transitions | ✅ ACE delivers `WalkForward → RunForward` (and direct walk↔run) correctly |
| `[CMD_LIST]` — Commands list at receive time | Empty for walk/run UMs; contains Ready/Action class for some others |
| `[HASCYCLE]` — does the dat have the requested cycle | ✅ True for both `0x44000007` (Run) and `0x45000005` (Walk) on style `0x8000003D` (NonCombat Humanoid) |
| `[SETCYCLE]` — animCycle picker calls into AnimationSequencer.SetCycle | ✅ Fires with correct (style, motion, speed) |
| `[SEQSTATE]` — per-tick `ae.Sequencer.CurrentMotion` for the observed remote | ✅ Holds the new motion correctly (e.g. shows `0x44000007 speed=2.939` after Run press, then `0x41000003 speed=1.000` after release) |

So:
- ACE wire data is correct.
- Our parser updates `InterpretedState` correctly.
- `OnLiveMotionUpdated` calls `SetCycle` with correct args.
- `SetCycle` updates the sequencer's `CurrentMotion` correctly.
- The cycle data the sequencer would play exists in the dat.

**But the visible leg cycle does NOT update.** Therefore the bug is **downstream of `ae.Sequencer.CurrentMotion`** — somewhere between the sequencer's internal state and the rendered MeshRefs:
- `AnimationSequencer.Advance(dt)` returning frames from the wrong node
- `BuildBlendedFrame()` reading from a stale `_currNode`
- `_currNode` advancing through stale link/head frames before reaching the new cycle
- Or how the per-part transforms returned by Advance get applied to the entity's `MeshRefs` for remote entities

We attempted a fix in `357dcc0` that forces `_currNode` onto the first newly-enqueued node in SetCycle — user reports **no visible change** after this fix.

---

## What's different between local (works) and remote (doesn't)

Both call **the same `AnimationSequencer.SetCycle` method** in `src/AcDream.Core/Physics/AnimationSequencer.cs:360`. So the sequencer code itself is shared.

Local +Acdream path:
- `PlayerMovementController` → `UpdatePlayerAnimation` (in `GameWindow.cs:6664`) → resolves cycle → `ae.Sequencer.SetCycle(...)`
- Fast-path early-return when cmd+speed unchanged (line 6713-6714)
- `OnLiveMotionUpdated` skips wire-echo SetCycle for the local player guid (line 2707)

Remote (observed retail char) path:
- Wire arrives → `OnLiveMotionUpdated` (`GameWindow.cs:3203`)
- "animCycle picker" at line 2842-2867 chooses the cycle based on Forward / Sidestep / Turn priority
- HasCycle fallback chain at line 2939
- `ae.Sequencer.SetCycle(fullStyle, cycleToPlay, animSpeed)` at line 2988
- Then iterates `update.MotionState.Commands` and routes each through `AnimationCommandRouter` (357dcc0 made this skip SubState class)
- Then ALSO updates `remoteMot.Motion.InterpretedState.ForwardCommand/ForwardSpeed` for body.Velocity computation
- Then ALSO calls `remoteMot.Motion.DoInterpretedMotion(...)` for sidestep/turn axes

**Hypotheses to investigate:**

A) After `SetCycle` fires, some other call in `OnLiveMotionUpdated` re-cycles the sequencer back. We've eliminated the `Commands` list (357dcc0 skip-SubState). Other candidates: `PlayAction` calls inside `RouteWireCommand`, the spawn-time SetCycle at line 2313, or something in `ApplyServerControlledVelocityCycle` (line 3238).

B) `_currNode` actually IS in the right place after SetCycle but `Advance(dt)` doesn't read from it correctly. Maybe a thread-safety issue (SetCycle on net thread, Advance on render thread, partial state visible).

C) `Advance` returns the right frames but `seqFrames` are not applied to the entity's `MeshRefs` for the remote entity specifically. Look at `GameWindow.cs:6510-6589` — the per-part transform application loop. There's no obvious local-vs-remote branch but worth tracing.

D) The MeshRefs themselves get rebuilt each frame and the rebuild reads from a different source for remotes. The `newMeshRefs` list is built per-frame at line 6567.

E) Local player's `ae.Sequencer.SetCycle` is called at a higher rate than remote's (per-input vs per-UM). Maybe the queue stays cleaner with frequent calls, and the bug is exposed only when SetCycle is sparse.

F) **Most likely** based on what we've seen: `Advance` plays through stale link frames before reaching the cycle. Our 357dcc0 fix forces `_currNode` onto the first newly-enqueued node — but for `Ready→Run`, the newly-enqueued sequence is `[Ready→Run link, Run cycle]`. `_currNode` lands on the **link**, the link plays for ~0.5–1 second, then the run cycle starts. User perceives the link's "transition pose" as "still walking / still idle."

---

## Diagnostic infrastructure available

All env-var gated on `ACDREAM_REMOTE_VEL_DIAG=1`:

| Diag | Where | What it shows |
|---|---|---|
| `[FWD_WIRE]` | `GameWindow.cs:2793-2800` | Each ForwardCommand transition received per remote |
| `[CMD_LIST]` | `GameWindow.cs:3119-3133` | Commands list contents at UM receive time |
| `[HASCYCLE]` | `GameWindow.cs:2939-2947` | HasCycle result for the requested cycle |
| `[SETCYCLE]` | `GameWindow.cs:2972-2986` | Each animCycle picker → SetCycle call |
| `[SEQSTATE]` | `GameWindow.cs:6520-6532` | Per-tick `ae.Sequencer.CurrentMotion` (1Hz throttled) |
| `[TURN_WIRE]` | `GameWindow.cs:3050-3057` | TurnCommand wire arrivals with signed speed |
| `[OMEGA_DIAG]` | `GameWindow.cs:5901-5912` | Per-tick omega being applied to body |
| `[VEL_DIAG]` | `GameWindow.cs:3327-3343` | Server-broadcast speed vs maxSeqSpeed per UP |

Also gated on `ACDREAM_INTERP_MANAGER=1` is the entire retail-faithful per-tick remote motion path. Set both env vars when reproducing.

The repo has `tools/cdb-scripts/` set up for live tracing of retail acclient.exe via cdb.exe. Two trace scripts already proven working:
- `walk_run_motion_trace.cdb` + `walk_run_motion_trace.log` — captured the exact retail walk→run sequence and proved retail uses `MotionTableManager::add_to_queue` without `truncate_animation_list`.

To launch retail tracing: have user start retail and connect, then in PowerShell:
```
& "C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\cdb.exe" `
  -pn acclient.exe -cf "tools\cdb-scripts\walk_run_motion_trace.cdb" *>&1 |
  Tee-Object -FilePath "tools\cdb-scripts\walk_run_motion_trace.log.console"
```
Auto-detaches at 200 hits via `.detach` (do NOT use `qd` per CLAUDE.md gotcha — silently ignored). NEVER `Stop-Process` cdb — takes retail down with it.

---

## What retail actually does (from cdb live trace)

For a walk→run direct transition retail's call sequence is:

```
[79]  CPhysicsObj::DoInterpretedMotion: motion=45000005   walk start (shift+W)
[82]  CMotionTable::DoObjectMotion: motion=45000005
[83]  MotionTableManager::add_to_queue: arg1=45000005 arg2=00000001  ← walk added looping

[89]  CPhysicsObj::DoInterpretedMotion: motion=44000007   run start (release shift)
[92]  CMotionTable::DoObjectMotion: motion=44000007
[93]  MotionTableManager::add_to_queue: arg1=44000007 arg2=00000001  ← run added looping

[104] CMotionTable::StopObjectMotion: motion=44000007    run end (release W)
```

`MotionTableManager::truncate_animation_list` was on bp the entire trace and **never fired**. Retail just appends new motions to the queue and lets `MotionTableManager::CheckForCompletedMotions` (`0x0051BE00`) and `MotionTableManager::remove_redundant_links` (`0x0051BF20`) handle the natural progression — neither of which we have ported.

This suggests our `AnimationSequencer.SetCycle` rebuild semantics (ClearCyclicTail + enqueue link + enqueue cycle) is fundamentally different from retail's "append-only" `MotionTableManager`. May not matter for visual output as long as our queue manipulations land in the same end state, but it's a structural mismatch worth exploring if the tactical fixes don't pan out.

---

## File locations

- **`src/AcDream.Core/Physics/AnimationSequencer.cs`** — SetCycle (line 360), Advance (690), BuildBlendedFrame (1254), ClearCyclicTail (1117), AdvanceToNextAnimation (1150), EnqueueMotionData (1101), LoadAnimNode (1037)
- **`src/AcDream.App/Rendering/GameWindow.cs`** — OnLiveMotionUpdated (3203), TickAnimations (5851), animCycle picker block (2842-2988), the seqFrames-to-MeshRefs application loop (6510-6635), UpdatePlayerAnimation (6664)
- **`src/AcDream.Core/Physics/AnimationCommandRouter.cs`** — RouteWireCommand (53), Classify (29)
- **`src/AcDream.Core/Physics/MotionInterpreter.cs`** — get_state_velocity (587), GetMaxSpeed (968), apply_current_movement (653), HitGround (924)
- **`src/AcDream.Core/Physics/PositionManager.cs`** — ComputeOffset (37) (the per-tick combiner)
- **`src/AcDream.Core/Physics/InterpolationManager.cs`** — Enqueue, AdjustOffset (224), stall detection
- **Reference decomp:** `docs/research/named-retail/acclient_2013_pseudo_c.txt` (1.4M-line pseudo-C with full PDB names)
- **Symbols index:** `docs/research/named-retail/symbols.json` (greppable name → address)
- **Verbatim retail headers:** `docs/research/named-retail/acclient.h` (struct field offsets)

---

## Concrete next steps for the bug

1. **Add a per-tick diag that prints `_currNode.Anim.Id` + `_framePosition` for the observed remote.** This will conclusively answer whether `_currNode` is on the new cycle, on a stale link, or somewhere else. Implement near the existing SEQSTATE diag in `GameWindow.cs:6520`. Ask user to do the precise test sequence (W only, then shift+W only, no turns/no mouse) and read the log.

2. **Add a diag that prints `seqFrames[0].Origin` and `seqFrames[0].Orientation`** (the result of Advance) before applying to MeshRefs. If the values change meaningfully between cycles → bug is in MeshRefs application. If they're stuck → bug is in Advance/BuildBlendedFrame.

3. **Compare the call ORDER of SetCycle for local vs remote.** Maybe local's UpdatePlayerAnimation calls SetCycle then immediately also re-resolves cycle data and passes it through. Or local has frame-resolution state we lack for remotes.

4. **Try the retail-faithful additive `add_to_queue` semantics:** modify SetCycle to skip ClearCyclicTail and just append new motion data. The `MotionTableManager::CheckForCompletedMotions` cleanup we don't port might be needed — but a primitive version (drop nodes whose `IsLooping=true` count exceeds 1, keeping the newest) might suffice as a starting point.

5. **Trace retail's CSequence::update / update_internal calls live** with cdb to see what frames ARE returned per tick for a remote running and transitioning. We have the cdb toolchain set up; pattern existing scripts in `tools/cdb-scripts/`.

6. **If all else fails, dispatch a research agent** with the prompt below.

---

## For the next research agent — exact assignment

> Read this entire document.
>
> Read `src/AcDream.Core/Physics/AnimationSequencer.cs` end-to-end, focusing on:
> - `SetCycle` (line 360-560) — what state it mutates and in what order
> - `Advance` (line 690-784) — how it consumes the queue and what it returns
> - `BuildBlendedFrame` (line 1254-1313) — how the visible per-part transforms are computed
> - `ClearCyclicTail` (line 1117-1140) and `AdvanceToNextAnimation` (line 1150-1166) — node lifecycle in the queue
>
> Then read `src/AcDream.App/Rendering/GameWindow.cs:5851-6635` — the `TickAnimations` method including the dead-reckoning blocks, sequencer Advance call, and the seqFrames-to-MeshRefs application loop.
>
> Answer:
>
> 1. After `SetCycle` is called for `RunForward` (with `linkData != null` and `cycleData != null`), what is the precise queue state, the value of `_currNode`, and the value of `_framePosition` immediately after SetCycle returns? Trace step by step including ClearCyclicTail's effect on `_currNode`. Cite line numbers.
>
> 2. On the next render tick when `Advance(dt=0.0167)` is called, what does it do? Specifically, does it advance through the link frames first, or skip them, or play them and stop at the cycle? What pose does `BuildBlendedFrame` return at the end?
>
> 3. Is there any code path between `SetCycle` returning and the next `Advance` call that could RESET `_currNode` back to a stale node? List every SetCycle call site (there are ~12 in GameWindow.cs) and identify any that fire on the per-tick path (not just on UM receive).
>
> 4. Is there any difference in how `seqFrames` is consumed for the local player vs a remote-observed entity in the loop at lines 6566-6635? Both use `if (seqFrames is not null) { origin = seqFrames[i].Origin; ... }`. Find any conditional branch that bypasses seqFrames for remotes.
>
> Output: a concise (<800 word) report with line citations and a clear hypothesis for the root cause of the visible-cycle-doesn't-switch bug. Do NOT modify any code.

---

## Quick reproduction recipe

1. Start local ACE server (user has this running on `127.0.0.1:9000`).
2. Start a parallel **retail** acclient.exe and connect with a different character (NOT `+Acdream`).
3. Build acdream: `dotnet build src/AcDream.App/AcDream.App.csproj -c Debug`
4. Launch acdream from the main repo dir with both env vars:
   ```powershell
   $env:ACDREAM_INTERP_MANAGER = "1"
   $env:ACDREAM_REMOTE_VEL_DIAG = "1"
   $env:ACDREAM_DAT_DIR   = "$env:USERPROFILE\Documents\Asheron's Call"
   $env:ACDREAM_LIVE      = "1"
   $env:ACDREAM_TEST_HOST = "127.0.0.1"
   $env:ACDREAM_TEST_PORT = "9000"
   $env:ACDREAM_TEST_USER = "testaccount"
   $env:ACDREAM_TEST_PASS = "testpassword"
   dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 |
     Tee-Object -FilePath launch.log
   ```
5. From the retail client, drive the test character: stand 2s, press W (run) 4s, release, press shift+W (walk) 4s, release.
6. Observe the test character in the acdream window. Bug: leg cycle does NOT visibly switch between idle / run / walk poses.
7. Read diags from `launch.log` (UTF-16 — use `Get-Content -Encoding Unicode`).

---

## Notes on what NOT to do

- **Do not pass `skipTransitionLink: true` unconditionally to SetCycle** — tried in commit `c06b6c5` (link skip), broke landing-from-jump, sit-down, and every other transition that needs its dat link to play. Reverted in `a2ae2ae`.
- **Do not full-reset the queue on every motion change** — same commit, also reverted. Side effect: removed end-animations everywhere.
- **Do not "scale body.Velocity by observed serverSpeed/predictedSpeed"** — tried during the day, user explicitly rejected as a hack. Always use predicted velocity from `get_state_velocity` (= `RunAnimSpeed × ForwardSpeed`).
- **Do not `Stop-Process cdb`** while it's attached to retail — takes retail down with it (CLAUDE.md). Use `.detach` inside bp actions for graceful exit.