acdream/docs/superpowers/specs/2026-06-30-movement-wire-parity-design.md

Movement / Animation Wire-Parity Slice — Design

Date: 2026-06-30 Phase: L.2b (movement wire/contact authority) + L.1b (command router + motion-state cleanup) Standard: decomp-verbatim, tests-first. No approximations, no "feels like retail."

Source documents (read first)

• docs/research/2026-06-26-movement-animation-retail-parity-audit.md — the 12 confirmed divergences (D1–D12) and the Phase 0–5 plan.
• docs/research/2026-06-26-ace-vs-2013-motion-command-gap.md — the ACE-vs-2013 command-catalog divergence (130 common names with different values; the +3 low-word shift beginning at SnowAngelState).
• Oracle: docs/research/named-retail/acclient_2013_pseudo_c.txt (Sept 2013 EoR build) + docs/research/named-retail/acclient.h. Live confirmation via the Ghidra HTTP bridge at http://127.0.0.1:8081 (decompile-by-address).
• Plans of record this slice serves: docs/plans/animation-system-audit.md (L.1) and docs/plans/2026-04-29-movement-collision-conformance.md (L.2).

Goal

Make the outbound movement wire bytes (MoveToState 0xF61C, Jump 0xF61B, AutonomousPosition 0xF753) and the inbound→animation command catalog byte-for-byte / value-for-value faithful to retail, proven by tests whose golden values are derived directly from the 2013 decomp packers and cross-checked against holtburger.

This slice fixes the packing and the catalog. It does not port the motion-interpreter input-state construction (adjust_motion / apply_raw_movement) — that is the next slice (D6 / audit Phase 2), explicitly deferred below.

Scope

In scope

• D1 — RawMotionState::Pack default-difference flag packing (replaces presence-based flags).
• D3 — MoveToStatePack trailing byte = contact | standingLongjump.
• D4 — JumpPack layout (extent, velocity, full Position, four timestamps; drop the spurious objectGuid/spellId).
• Catalog gap — dual command catalog (AceModernCommandCatalog runtime default + Retail2013CommandCatalog conformance), built behind an IMotionCommandCatalog seam; full 2013 command_ids[0x198] extraction; DAT-availability tests.
• Phase 0 oracle tests — written first and failing, encoding the four retail Pack functions and the catalog matrices.

Out of scope (later L.1/L.2 slices — see "Deferred / unresolved")

D2 (runtime actions-list/current_style emission), D5 (heartbeat-clock stamping — audit only this slice), D6 (adjust_motion/apply_raw_movement input-state), D7 (animation/motion application reorder), D8 (MoveToManager/force-walk), D9 (inbound types 8/9), D10 (spawn-time MoveTo), D11 (sequence/autonomy propagation), D12 (jump/contact gates).

Decisions (locked with the user 2026-06-30)

1. First slice = catalog + outbound wire (not catalog-only, not + motion core).
2. Golden-byte oracle = decomp-derived + holtburger cross-check, confirmed via the Ghidra bridge. No live retail capture for this slice (captures are reserved for Phase 2, where retail's input state is the genuine unknown).
3. Catalog mechanism = Option A — IMotionCommandCatalog interface; static MotionCommandResolver.ReconstructFullCommand(ushort) is retained, delegating to an AceModernCommandCatalog singleton so all ~10 runtime call sites are unchanged. Tests instantiate Retail2013CommandCatalog explicitly.
4. 2013 table depth = full extraction (~408 command_ids[0x198] entries with provenance), not a test-matrix stub.

Component design

1. Command catalog (L.1b)

Seam. New interface in AcDream.Core.Physics:

public interface IMotionCommandCatalog
{
    /// Reconstruct the full 32-bit MotionCommand from a 16-bit wire value.
    /// Returns 0 if no entry matches.
    uint ReconstructFullCommand(ushort wireCommand);
}

AceModernCommandCatalog : IMotionCommandCatalog — the runtime default. Built from the DatReaderWriter / ACE MotionCommand enum (these share values; ACE's enum is the authoritative ACE-modern catalog and matches the local DATs). Reconstruction = wire-low → full lookup, with collisions resolved by the documented retail class priority (lower class byte wins: Action 0x10 < SubState 0x41 < Style 0x80 …) applied at build time, producing a flat IReadOnlyDictionary<ushort,uint>.

• Verify and (likely) delete the magic override. The current MotionCommandResolver.ApplyNamedRetailOverrides force-maps 0x016E–0x0197 to 0x10000000 | lo. Once AceModernCommandCatalog is built cleanly from the ACE enum, assert the ACE test matrix passes (0x0153→0x10000153, 0x0166→0x10000166, 0x0171→0x10000171, 0x0173→0x10000173). If it passes without the override loop, delete the loop (unexplained magic range; see the magic-number-audit memory). If a specific command still resolves to the wrong class, add a per-command, cited override — never a blind range.
• Fix the wrong comment. The shift starts at SnowAngelState (0x43000115 → 0x43000118), not AllegianceHometownRecall.

Retail2013CommandCatalog : IMotionCommandCatalog — conformance/reference. Built from the full 2013 command_ids[0x198] table at 0x007c73e8 paired with the command-name table at 0x008041ec..0x0080444c. Deterministic extraction from acclient_2013_pseudo_c.txt (and/or the Ghidra bridge), emitted as a generated/static name→value table in the source with a provenance header citing both addresses. ~408 entries.

MotionCommandResolver keeps public static uint ReconstructFullCommand(ushort) delegating to a private static readonly AceModernCommandCatalog s_aceModern. All current callers (AnimationCommandRouter, CombatAnimationPlanner, 8× GameWindow) are untouched.

DAT-availability tests. A command animates only if the entity's MotionTable has a Links or Modifiers entry for the full 32-bit value. Tests (MotionCommandCatalogTests, real-DAT-backed via Chorizite.DatReaderWriter):

• ACE mode: 0x0153→0x10000153 LifestoneRecall, 0x0166→0x10000166, 0x0171→0x10000171, 0x0173→0x10000173.
• 2013 mode: 0x0150→0x10000150 LifestoneRecall, 0x0163→0x10000163, 0x016E→0x1000016E, 0x0170→0x10000170.
• Availability: LifestoneRecall (ACE 0x10000153) and HouseRecall exist in local DAT MotionTables; MarketplaceRecall / AllegianceHometownRecall / PKArenaRecall / OffhandSlashHigh exist only under the ACE-shifted IDs (reproduces the gap doc's link-hit scan as a fixture assertion).

2. RawMotionState model + default-difference packing (D1)

Data type AcDream.Core.Physics.RawMotionState — a value type mirroring the retail struct (acclient.h RawMotionState::PackBitfield, decomp 0x0051ed10):

field	retail default	bit
current_holdkey	HoldKey.None (1)	0x001
current_style	0x8000003D	0x002
forward_command	0x41000003	0x004
forward_holdkey	HoldKey.Invalid (0)	0x008
forward_speed	1.0f	0x010
sidestep_command	0	0x020
sidestep_holdkey	HoldKey.Invalid (0)	0x040
sidestep_speed	1.0f	0x080
turn_command	0	0x100
turn_holdkey	HoldKey.Invalid (0)	0x200
turn_speed	1.0f	0x400
actions (list)	empty	num_actions<<11 (bits 11–15)

Pure data, no GL/Net dependency. Lives in Core.Physics so the Phase-2 motion interpreter (also Core.Physics) can populate it without a Core.Net dependency. A RawMotionState.Default exposes the retail defaults.

Packer in AcDream.Core.Net (Core.Net may reference Core.Physics; the reverse is forbidden by Code Structure Rule #2). Ports RawMotionState::Pack verbatim:

1. Build flags dword: set bit only when the field differs from its default (forward_speed != 1.0f, current_holdkey != None, etc.), OR in num_actions << 11. Note the bitfield is bits 0–15 only — bits 16–31 are unused (retail num_actions is 5 bits, max 31). The current MoveToState.cs comment "bits 11–31 = command list length" is wrong; correct it to bits 11–15 = num_actions.
2. Write the flags dword.
3. Write each set field in bit order (holdkey, style, fwd_cmd, fwd_holdkey, fwd_speed, ss_cmd, ss_holdkey, ss_speed, turn_cmd, turn_holdkey, turn_speed).
4. Write each action: u16 command then u16 (stamp & 0x7FFF) | (autonomous ? 0x8000 : 0) (decomp lines 293945–293960).

MoveToState.Build is refactored to take a RawMotionState (plus position, sequences, contact, standingLongjump) instead of the flat nullable param list.

Behavioral effect vs ACE: the only runtime change is removing over-sent defaults (forwardSpeed=1.0, currentHoldKey=None, default per-axis hold keys). ACE's UnPackNet defaults omitted fields, so this is strictly more correct. The slice does not change which RawMotionState values the caller constructs (that is D6) — it threads the same values the caller passes today through the new struct. Smoke-test against ACE confirms no regression.

3. MoveToState trailing byte (D3)

From MoveToStatePack::Pack (0x005168f0, lines 284717–284722): the trailing byte is ((longjump_mode != 0 ? 0x02 : 0) | (contact != 0 ? 0x01 : 0)). Then ALIGN to 4.

MoveToState.Build gains explicit bool contact and bool standingLongjump params. standingLongjump is wired to its true current value (false — standing longjump is not implemented yet). The packing is faithful; the input is honest. When standing longjump lands (later), the param flips. This is not a masking shortcut — it is the correct byte with the correct current input.

4. JumpPack (D4)

From JumpPack::Pack (0x00516d10, lines 284934–284963), field order:

1. f32 extent
2. f32 velocity.x, velocity.y, velocity.z
3. Position.Pack (objcell_id + frame)
4. u16 instance_timestamp, server_control_timestamp, teleport_timestamp, force_position_ts
5. ALIGN to 4

JumpAction.Build is rewritten to this layout. The current spurious u32 objectGuid + u32 spellId are removed (no retail evidence). New params: cellId, position, rotation. Caller at GameWindow.cs:8343 supplies them (it already has wireCellId / wirePos / wireRot in scope).

5. AutonomousPosition (D5 audit + timestamp order)

AutonomousPositionPack::Pack (0x00516af0): Position, then u16 instance / server_control / teleport / force_position, then a contact-only byte (contact != 0; no longjump bit), then ALIGN. Current code matches. Add:

• a timestamp-order golden test (instance, serverControl, teleport, forcePosition);
• a contact-byte test.

D5 audit (no behavior change unless decomp proves divergence): read CommandInterpreter::SendMovementEvent (0x006b4680) and SendPositionEvent (0x006b4770) and compare what they stamp (last_sent_position_time vs position vs contact_plane) to acdream's NotePositionSent. Document the finding; change behavior only if the decomp shows a real divergence.

6. Position::Pack verification

Position::Pack is shared by all three messages and currently writes cellId, x, y, z, qw, qx, qy, qz. It works against ACE, but for strict parity: decompile Position::Pack / Frame::Pack by address, confirm the field order, and lock it with a golden test on the Position block. Fix only if the decomp diverges; otherwise the test pins it.

Test inventory (written first, failing)

Core.Net.Tests:

• RawMotionStatePackTests — default state (only the flags dword, value 0); walk-forward speed 1.0 (forward_command + forward_holdkey set, forward_speed omitted); run forward (holdkey + fwd_cmd + fwd_holdkey + fwd_speed); backward; sidestep right/left; turn right/left; non-default current_style; a populated actions list (num_actions bits + per-action u16 pair); contact/longjump trailing byte combinations.
• MoveToStateGoldenTests — full-message golden bytes for walk, run, slow-walk (toggle-run), sidestep, turn, contact, standing-longjump.
• JumpActionTests — retail JumpPack layout, full Position present, no object/spell fields.
• AutonomousPositionTests — timestamp order + contact byte.
• PositionPackTests — Position block byte order.

Core.Tests:

• MotionCommandCatalogTests — ACE-mode + 2013-mode matrices; class-priority collisions; the "override deleted" assertion (or per-command cited override).
• MotionCommandCatalogDatTests — real-DAT availability assertions.

Golden bytes are computed by hand from the decomp Pack functions (cited by address in each test) and cross-checked against holtburger's Rust packers.

Layering & placement

• IMotionCommandCatalog, AceModernCommandCatalog, Retail2013CommandCatalog, RawMotionState → src/AcDream.Core/Physics/.
• RawMotionState packer + the three message builders → src/AcDream.Core.Net/Messages/.
• Caller wiring → src/AcDream.App/Rendering/GameWindow.cs (MoveToState ~8277, Jump ~8343) — minimal: build a RawMotionState, pass new contact/longjump and jump position params. No new feature body in GameWindow (Code Structure Rule #1).
• Tests in the project matching the layer (Rule #6).

Deferred / unresolved (called out, not guessed)

• D6 (next slice): the runtime does not yet construct the exactly-retail RawMotionState (run-vs-walk forward_command, hold-key derivation, backward / sidestep-left speed normalization). This slice makes the packer verbatim; state construction is adjust_motion/apply_raw_movement (audit Phase 2).
• D5 (CONFIRMED 2026-06-30, deferred): the audit found a real divergence — retail's SendMovementEvent (0x006b4680) stamps ONLY last_sent_position_time after an MTS, while SendPositionEvent (0x006b4770, AP) stamps all three (time + position + contact-plane); acdream's NotePositionSent stamps all three after both. Broader: acdream gates APs on a plain interval (HeartbeatDue) where retail uses ShouldSendPositionEvent (0x006b45e0). Left unchanged this slice (code comments added at both call sites); recorded as register row TS-33 and deferred to a dedicated cadence-port follow-up slice (port ShouldSendPositionEvent + split MTS/AP stamping).
• D2: actions-list / current_style packing is structurally supported and tested, but the runtime emits 0 actions; populated emission is Phase 2+.
• D9/D8/D10/D11/D12, D7: later L.1/L.2 slices.

Bookkeeping (mandatory)

• Divergence register: delete the rows for D1, D3, D4 in the same commit that ports each. If any new deviation is introduced, add its row in the same commit.
• Roadmap: update L.2b (wire) and L.1b (catalog) "shipped" notes when landed.
• Memory: if a durable lesson emerges (e.g., the default-difference packing pattern, the dual-catalog seam), capture it.

Acceptance criteria

• Failing oracle tests written first; then green after implementation.
• dotnet build + dotnet test green at each commit.
• Every ported algorithm cites the named retail symbol + address in test/comment.
• ACE smoke pass: login, walk/run/sidestep/turn/jump, observe no server rejection; confirm the over-sent defaults are gone on the wire (dump or capture).
• Divergence register rows for D1/D3/D4 retired; roadmap updated.