erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

feat(L.1b): dual MotionCommand catalog — AceModern runtime + Retail2013 conformance

Browse source 
Splits MotionCommandResolver's single ACE-modern lookup into an
IMotionCommandCatalog seam with two implementations:

- AceModernCommandCatalog (runtime default): built cleanly from the
  DatReaderWriter MotionCommand enum (mirrors ACE + local DAT MotionTables)
  with a documented class-priority tiebreak. The old blind 0x016E-0x0197
  per-range override is DELETED — verified the ACE matrix (LifestoneRecall
  0x0153 to 0x10000153, MarketplaceRecall 0x0166, AllegianceHometownRecall
  0x0171, OffhandSlashHigh 0x0173) resolves correctly straight from the enum
  with no override. Stale shift-start comment corrected to SnowAngelState
  (0x43000115 to 0x43000118), not AllegianceHometownRecall.
- Retail2013CommandCatalog (conformance/reference): full verbatim extraction
  of command_ids[0x198] at 0x007c73e8 (acclient_2013_pseudo_c.txt:1017259-1017667),
  direct wire-low to full index lookup. 408 entries, anchors verified against
  source ([0x150]=0x10000150, [0x153]=0x09000153, [0x197]=0x10000197).

MotionCommandResolver.ReconstructFullCommand stays a static facade delegating
to an AceModern singleton — all ~10 runtime callers unchanged.

Removing the override exposed a pre-existing bug: CombatAnimationPlanner's
late-combat command block uses 2013 numbering, not ACE/DRW. Corrected the one
catalog test assertion pinned to the override's output (wire 0x0170 to
0x09000170 IssueSlashCommand, its true DRW identity) and filed the planner bug
as #159 rather than silently patching out-of-scope code.

Tests: +catalog matrices (ACE/2013), class-priority collisions, boundary
cases, real-DAT availability (gap-doc hit counts reproduced). Build + full
suite green (Core.Tests 1718, no regressions).

Spec: docs/superpowers/specs/2026-06-30-movement-wire-parity-design.md (1)
Research: docs/research/2026-06-26-ace-vs-2013-motion-command-gap.md

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-06-30 22:13:36 +02:00
parent 33ad231d18
commit 2c8620ea94
8 changed files with 612 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

101
src/AcDream.Core/Physics/AceModernCommandCatalog.cs Normal file
View file

@ -0,0 +1,101 @@
using System;
using System.Collections.Generic;
using DRWMotionCommand = DatReaderWriter.Enums.MotionCommand;
namespace AcDream.Core.Physics;
/// <summary>
/// Runtime-default <see cref="IMotionCommandCatalog"/>. Built from the
/// <see cref="DRWMotionCommand"/> enum (generated from the protocol XML;
/// mirrors ACE's <c>MotionCommand</c> enum and matches the values actually
/// found in the local DAT <c>MotionTable</c> records). Use this catalog
/// while talking to ACE — it is what
/// <see cref="MotionCommandResolver.ReconstructFullCommand"/> delegates to.
///
/// <para>
/// Reconstruction is a flat <c>wireLow16 -&gt; full32</c> lookup built once
/// at construction. When more than one enum value shares the same low 16
/// bits (a true class collision — class byte differs, low word doesn't),
/// the LOWER class byte wins: Action (0x10) &lt; ChatEmote (0x12/0x13)
/// &lt; Modifier (0x20) &lt; SubState (0x41/...) &lt; ... &lt; Style (0x80).
/// See <see cref="ResolveClassPriority"/>.
/// </para>
///
/// <para>
/// <b>No magic per-range override.</b> The original
/// <c>MotionCommandResolver.ApplyNamedRetailOverrides</c> force-mapped
/// wire 0x016E-0x0197 to <c>0x10000000 | lo</c> on the theory that the
/// generated DRW enum was "shifted." Verified false: building the lookup
/// straight from <see cref="DRWMotionCommand"/> (Chorizite.DatReaderWriter
/// 2.1.7, 409 distinct values, zero same-low16 collisions) already resolves
/// <c>LifestoneRecall</c> (0x0153), <c>MarketplaceRecall</c> (0x0166),
/// <c>AllegianceHometownRecall</c> (0x0171), and <c>OffhandSlashHigh</c>
/// (0x0173) to their correct Action-class full values with no override.
/// The override loop is deleted in this slice (it was masking nothing; the
/// enum was already correct). See
/// <c>docs/research/2026-06-26-ace-vs-2013-motion-command-gap.md</c>.
/// </para>
/// </summary>
public sealed class AceModernCommandCatalog : IMotionCommandCatalog
{
private readonly Dictionary<ushort, uint> _lookup;
public AceModernCommandCatalog()
{
_lookup = BuildLookup();
}
public uint ReconstructFullCommand(ushort wireCommand)
{
if (wireCommand == 0) return 0u;
_lookup.TryGetValue(wireCommand, out var full);
return full;
}
private static Dictionary<ushort, uint> BuildLookup()
{
var byLow = new Dictionary<ushort, List<uint>>(512);
foreach (DRWMotionCommand v in Enum.GetValues(typeof(DRWMotionCommand)))
{
uint full = (uint)v;
ushort lo = (ushort)(full & 0xFFFFu);
if (lo == 0) continue; // Invalid / unmappable
if (!byLow.TryGetValue(lo, out var list))
byLow[lo] = list = new List<uint>(1);
if (!list.Contains(full))
list.Add(full);
}
var result = new Dictionary<ushort, uint>(byLow.Count);
foreach (var (lo, candidates) in byLow)
{
result[lo] = candidates.Count == 1
? candidates[0]
: ResolveClassPriority(candidates);
}
return result;
}
/// <summary>
/// Given a set of full 32-bit MotionCommand values that all share the
/// same low 16 bits, return the one whose class byte (bits 24-31) is
/// numerically lowest — retail's class priority (Action 0x10 beats
/// Modifier 0x20 beats SubState 0x41 beats Style 0x80, etc). Exposed
/// as a static so it can be exercised directly by tests even when the
/// live enum has no real collisions to exercise it through
/// <see cref="BuildLookup"/>.
/// </summary>
public static uint ResolveClassPriority(IReadOnlyList<uint> candidates)
{
uint best = candidates[0];
for (int i = 1; i < candidates.Count; i++)
{
uint candidate = candidates[i];
if ((candidate >> 24) < (best >> 24))
best = candidate;
}
return best;
}
}

27
src/AcDream.Core/Physics/IMotionCommandCatalog.cs Normal file
View file

@ -0,0 +1,27 @@
namespace AcDream.Core.Physics;
/// <summary>
/// Reconstructs a full 32-bit retail MotionCommand from the 16-bit wire
/// value broadcast in <c>InterpretedMotionState.Commands[]</c> (the server
/// truncates the class byte — see <see cref="MotionCommandResolver"/> for
/// why that byte must be restored before routing).
///
/// <para>
/// Two implementations exist because the wire-numbering used by ACE / the
/// local DATs and the wire-numbering used by the Sept 2013 EoR retail
/// decomp diverge for ~130 command names (a contiguous low-word "+3" shift
/// starting at <c>SnowAngelState</c>). See
/// <see cref="AceModernCommandCatalog"/> (runtime default) and
/// <see cref="Retail2013CommandCatalog"/> (conformance/reference), and
/// <c>docs/research/2026-06-26-ace-vs-2013-motion-command-gap.md</c> for the
/// full divergence analysis.
/// </para>
/// </summary>
public interface IMotionCommandCatalog
{
/// <summary>
/// Reconstruct the full 32-bit MotionCommand from a 16-bit wire value.
/// Returns 0 if no entry matches.
/// </summary>
uint ReconstructFullCommand(ushort wireCommand);
}

86
src/AcDream.Core/Physics/MotionCommandResolver.cs
View file

@ -1,12 +1,8 @@
using System;
using System.Collections.Generic;
using DRWMotionCommand = DatReaderWriter.Enums.MotionCommand;
namespace AcDream.Core.Physics;
/// <summary>
/// Reconstructs the 32-bit retail <see cref="DRWMotionCommand"/> value from
/// a 16-bit wire value broadcast in <c>InterpretedMotionState.Commands[]</c>.
/// Reconstructs the 32-bit retail MotionCommand value from a 16-bit wire
/// value broadcast in <c>InterpretedMotionState.Commands[]</c>.
///
/// <para>
/// The server serializes MotionCommands as <c>u16</c> (ACE
@ -19,11 +15,19 @@ namespace AcDream.Core.Physics;
/// </para>
///
/// <para>
/// This is implemented as an eager lookup table built from all values of
/// <see cref="DRWMotionCommand"/> via reflection. If the wire value matches
/// more than one enum value (different class bits), we prefer the
/// lowest-class-numbered variant that has a non-zero class byte — roughly
/// matching retail priority (Action &lt; Modifier &lt; SubState &lt; Style).
/// As of the L.1b command-catalog slice, this static facade delegates to a
/// single shared <see cref="AceModernCommandCatalog"/> instance — the
/// runtime-default catalog built from the DatReaderWriter
/// <c>MotionCommand</c> enum (matches ACE + the local DATs). All ~10
/// existing runtime callers (<c>AnimationCommandRouter</c>,
/// <c>CombatAnimationPlanner</c>, 8x <c>GameWindow</c>) are unaffected by
/// this refactor — the public signature and behavior for the ACE/runtime
/// path is unchanged. A second catalog,
/// <see cref="Retail2013CommandCatalog"/>, is available for
/// conformance/reference work against the Sept 2013 EoR decomp's own
/// (differently-numbered) command table; callers that need that catalog
/// must construct it directly via the <see cref="IMotionCommandCatalog"/>
/// seam — this facade only ever returns ACE/runtime values.
/// </para>
///
/// <para>
@ -42,66 +46,26 @@ namespace AcDream.Core.Physics;
/// <c>docs/research/deepdives/r03-motion-animation.md</c> §3 — complete
/// command catalogue.
/// </description></item>
/// <item><description>
/// <c>docs/research/2026-06-26-ace-vs-2013-motion-command-gap.md</c> —
/// the ACE-vs-2013 catalog divergence that motivated the dual-catalog
/// seam (the shift begins at <c>SnowAngelState</c>, 0x43000115 -&gt;
/// 0x43000118, not at <c>AllegianceHometownRecall</c>).
/// </description></item>
/// </list>
/// </para>
/// </summary>
public static class MotionCommandResolver
{
// Lookup table built eagerly at type-init. Sparse: only values that
// appear in the DRW enum (which came from the generated protocol XML)
// are present. ~450 entries typical.
private static readonly Dictionary<ushort, uint> s_lookup = BuildLookup();
private static readonly AceModernCommandCatalog s_aceModern = new();
/// <summary>
/// Given a 16-bit wire value, return the full 32-bit MotionCommand
/// (class byte restored). Returns 0 if no matching enum value exists.
/// (class byte restored) per the ACE/runtime catalog. Returns 0 if no
/// matching value exists.
/// </summary>
public static uint ReconstructFullCommand(ushort wireCommand)
{
if (wireCommand == 0) return 0u;
s_lookup.TryGetValue(wireCommand, out var full);
return full;
}
private static Dictionary<ushort, uint> BuildLookup()
{
var result = new Dictionary<ushort, uint>(512);
var values = Enum.GetValues(typeof(DRWMotionCommand));
foreach (DRWMotionCommand v in values)
{
uint full = (uint)v;
ushort lo = (ushort)(full & 0xFFFFu);
if (lo == 0) continue; // Invalid / unmappable
// If a value with this low-16-bit already exists, keep the one
// with the lower class byte (Action=0x10 beats SubState=0x41
// beats Style=0x80). This matches retail: the server tends to
// emit Actions and ChatEmotes far more often than Styles, so
// the Action-class reconstruction is the common case.
if (!result.TryGetValue(lo, out var existing)
|| (full >> 24) < (existing >> 24))
{
result[lo] = full;
}
}
ApplyNamedRetailOverrides(result);
return result;
}
private static void ApplyNamedRetailOverrides(Dictionary<ushort, uint> result)
{
// The generated DRW enum is shifted by three entries starting at
// AllegianceHometownRecall. The named Sept 2013 retail command_ids
// table is authoritative here:
// named-retail/acclient_2013_pseudo_c.txt lines 1017626-1017658
// and command-name table lines 1068272-1068313.
//
// These values cover recall, offhand, attack 4-6, and fast/slow punch
// actions. Without the override, wire command 0x0170 reconstructs to
// IssueSlashCommand instead of OffhandSlashHigh, so offhand swing
// animations route as UI commands and never play.
for (ushort lo = 0x016E; lo <= 0x0197; lo++)
result[lo] = 0x10000000u | lo;
return s_aceModern.ReconstructFullCommand(wireCommand);
}
}

113
src/AcDream.Core/Physics/Retail2013CommandCatalog.cs Normal file
View file

@ -0,0 +1,113 @@
namespace AcDream.Core.Physics;
/// <summary>
/// Conformance/reference <see cref="IMotionCommandCatalog"/> built from the
/// Sept 2013 EoR retail decomp's full <c>command_ids[0x198]</c> table — a
/// direct index from 16-bit wire low-word to the 32-bit MotionCommand the
/// 2013 client itself would reconstruct. NOT the runtime default (ACE / the
/// local DATs use a later-client numbering — see
/// <see cref="AceModernCommandCatalog"/>); this catalog exists to prove and
/// pin the 2013 decomp's behavior for conformance tests.
///
/// <para>
/// Provenance: <c>docs/research/named-retail/acclient_2013_pseudo_c.txt</c>,
/// <c>uint32_t const command_ids[0x198]</c> at address <c>0x007c73e8</c>,
/// table body starting at source line 1017259
/// (<c>[0x000] = 0x80000000</c>) through line 1017667
/// (<c>[0x197] = 0x10000197</c>), closing brace at line 1017668. Extracted
/// programmatically (regex over <c>[0xNNN] = 0xVVVVVVVV</c>, not hand-typed)
/// and verified against the anchor values cited inline below.
/// </para>
///
/// <para>
/// <b>Caution — two look-alike tables exist elsewhere in the same file</b>
/// (around source lines 1017962 and 1068315, both also declared
/// <c>command_ids[0x198]</c>). Only the table at line 1017259 /
/// address 0x007c73e8 is used here; do not conflate with the others.
/// </para>
/// </summary>
public sealed class Retail2013CommandCatalog : IMotionCommandCatalog
{
public uint ReconstructFullCommand(ushort wireCommand)
{
return wireCommand < CommandIds.Length ? CommandIds[wireCommand] : 0u;
}
// acclient_2013_pseudo_c.txt:1017259-1017667, address 0x007c73e8.
// 0x198 (408) entries, indices 0x000..0x197, verbatim from the decomp.
// Anchors verified at extraction time:
// [0x000]=0x80000000 [0x003]=0x41000003 [0x005]=0x45000005
// [0x007]=0x44000007 [0x00d]=0x6500000d [0x150]=0x10000150
// [0x153]=0x09000153
private static readonly uint[] CommandIds =
{
0x80000000u, 0x85000001u, 0x85000002u, 0x41000003u, 0x40000004u, 0x45000005u,
0x45000006u, 0x44000007u, 0x40000008u, 0x40000009u, 0x4000000Au, 0x4000000Bu,
0x4000000Cu, 0x6500000Du, 0x6500000Eu, 0x6500000Fu, 0x65000010u, 0x40000011u,
0x41000012u, 0x41000013u, 0x41000014u, 0x40000015u, 0x40000016u, 0x40000017u,
0x40000018u, 0x40000019u, 0x4000001Au, 0x4000001Bu, 0x4000001Cu, 0x4000001Du,
0x4000001Eu, 0x4000001Fu, 0x40000020u, 0x40000021u, 0x40000022u, 0x40000023u,
0x40000024u, 0x40000025u, 0x40000026u, 0x40000027u, 0x40000028u, 0x40000029u,
0x4000002Au, 0x4000002Bu, 0x4000002Cu, 0x4000002Du, 0x4000002Eu, 0x4000002Fu,
0x40000030u, 0x40000031u, 0x40000032u, 0x40000033u, 0x40000034u, 0x40000035u,
0x40000036u, 0x40000037u, 0x40000038u, 0x40000039u, 0x2000003Au, 0x2500003Bu,
0x8000003Cu, 0x8000003Du, 0x8000003Eu, 0x8000003Fu, 0x80000040u, 0x80000041u,
0x80000042u, 0x80000043u, 0x80000044u, 0x80000045u, 0x80000046u, 0x80000047u,
0x80000048u, 0x80000049u, 0x1000004Au, 0x1000004Bu, 0x1300004Cu, 0x1000004Du,
0x1000004Eu, 0x1000004Fu, 0x10000050u, 0x10000051u, 0x10000052u, 0x10000053u,
0x10000054u, 0x10000055u, 0x10000056u, 0x10000057u, 0x10000058u, 0x10000059u,
0x1000005Au, 0x1000005Bu, 0x1000005Cu, 0x1000005Du, 0x1000005Eu, 0x1000005Fu,
0x10000060u, 0x10000061u, 0x10000062u, 0x10000063u, 0x10000064u, 0x10000065u,
0x10000066u, 0x10000067u, 0x10000068u, 0x10000069u, 0x1000006Au, 0x1000006Bu,
0x1000006Cu, 0x1000006Du, 0x1000006Eu, 0x1000006Fu, 0x10000070u, 0x10000071u,
0x10000072u, 0x10000073u, 0x10000074u, 0x10000075u, 0x10000076u, 0x10000077u,
0x10000078u, 0x13000079u, 0x1300007Au, 0x1300007Bu, 0x1300007Cu, 0x1300007Du,
0x1300007Eu, 0x1300007Fu, 0x13000080u, 0x13000081u, 0x13000082u, 0x13000083u,
0x13000084u, 0x13000085u, 0x13000086u, 0x13000087u, 0x13000088u, 0x13000089u,
0x1300008Au, 0x1300008Bu, 0x1300008Cu, 0x1300008Du, 0x1300008Eu, 0x1300008Fu,
0x13000090u, 0x13000091u, 0x13000092u, 0x13000093u, 0x13000094u, 0x13000095u,
0x13000096u, 0x13000097u, 0x13000098u, 0x13000099u, 0x1300009Au, 0x1200009Bu,
0x1000009Cu, 0x1000009Du, 0x1000009Eu, 0x1000009Fu, 0x100000A0u, 0x100000A1u,
0x080000A2u, 0x090000A3u, 0x090000A4u, 0x090000A5u, 0x090000A6u, 0x090000A7u,
0x090000A8u, 0x080000A9u, 0x090000AAu, 0x090000ABu, 0x090000ACu, 0x090000ADu,
0x090000AEu, 0x090000AFu, 0x090000B0u, 0x090000B1u, 0x0D0000B2u, 0x0D0000B3u,
0x0D0000B4u, 0x080000B5u, 0x080000B6u, 0x080000B7u, 0x090000B8u, 0x090000B9u,
0x0D0000BAu, 0x0D0000BBu, 0x0D0000BCu, 0x0D0000BDu, 0x0D0000BEu, 0x0D0000BFu,
0x090000C0u, 0x0C0000C1u, 0x090000C2u, 0x090000C3u, 0x090000C4u, 0x0D0000C5u,
0x090000C6u, 0x090000C7u, 0x090000C8u, 0x090000C9u, 0x130000CAu, 0x130000CBu,
0x130000CCu, 0x100000CDu, 0x100000CEu, 0x100000CFu, 0x100000D0u, 0x100000D1u,
0x100000D2u, 0x400000D3u, 0x120000D4u, 0x090000D5u, 0x090000D6u, 0x090000D7u,
0x090000D8u, 0x090000D9u, 0x090000DAu, 0x090000DBu, 0x090000DCu, 0x090000DDu,
0x090000DEu, 0x120000DFu, 0x400000E0u, 0x400000E1u, 0x100000E2u, 0x100000E3u,
0x400000E4u, 0x400000E5u, 0x400000E6u, 0x090000E7u, 0x800000E8u, 0x800000E9u,
0x430000EAu, 0x430000EBu, 0x430000ECu, 0x430000EDu, 0x430000EEu, 0x430000EFu,
0x430000F0u, 0x430000F1u, 0x430000F2u, 0x430000F3u, 0x430000F4u, 0x430000F5u,
0x430000F6u, 0x430000F7u, 0x430000F8u, 0x420000F9u, 0x430000FAu, 0x430000FBu,
0x430000FCu, 0x430000FDu, 0x090000FEu, 0x090000FFu, 0x09000100u, 0x09000101u,
0x09000102u, 0x09000103u, 0x09000104u, 0x09000105u, 0x09000106u, 0x09000107u,
0x09000108u, 0x09000109u, 0x0900010Au, 0x0900010Bu, 0x0900010Cu, 0x0900010Du,
0x1000010Eu, 0x0900010Fu, 0x09000110u, 0x09000111u, 0x09000112u, 0x09000113u,
0x09000114u, 0x43000115u, 0x13000116u, 0x43000117u, 0x43000118u, 0x43000119u,
0x0900011Au, 0x1000011Bu, 0x1000011Cu, 0x1000011Du, 0x1000011Eu, 0x1000011Fu,
0x10000120u, 0x10000121u, 0x10000122u, 0x10000123u, 0x10000124u, 0x10000125u,
0x10000126u, 0x10000127u, 0x10000128u, 0x10000129u, 0x1000012Au, 0x1000012Bu,
0x1000012Cu, 0x1000012Du, 0x1000012Eu, 0x1000012Fu, 0x10000130u, 0x10000131u,
0x13000132u, 0x40000133u, 0x40000134u, 0x40000135u, 0x40000136u, 0x10000137u,
0x80000138u, 0x80000139u, 0x4300013Au, 0x4300013Bu, 0x4300013Cu, 0x4300013Du,
0x4300013Eu, 0x4300013Fu, 0x43000140u, 0x43000141u, 0x43000142u, 0x43000143u,
0x43000144u, 0x43000145u, 0x43000146u, 0x13000147u, 0x13000148u, 0x13000149u,
0x1300014Au, 0x1300014Bu, 0x1300014Cu, 0x1300014Du, 0x1300014Eu, 0x1300014Fu,
0x10000150u, 0x09000151u, 0x09000152u, 0x09000153u, 0x09000154u, 0x09000155u,
0x09000156u, 0x09000157u, 0x09000158u, 0x09000159u, 0x0900015Au, 0x0900015Bu,
0x0900015Cu, 0x0900015Du, 0x0900015Eu, 0x0900015Fu, 0x09000160u, 0x09000161u,
0x10000162u, 0x10000163u, 0x10000164u, 0x09000165u, 0x09000166u, 0x09000167u,
0x09000168u, 0x09000169u, 0x0900016Au, 0x0900016Bu, 0x0900016Cu, 0x0900016Du,
0x1000016Eu, 0x1000016Fu, 0x10000170u, 0x10000171u, 0x10000172u, 0x10000173u,
0x10000174u, 0x10000175u, 0x10000176u, 0x10000177u, 0x10000178u, 0x10000179u,
0x1000017Au, 0x1000017Bu, 0x1000017Cu, 0x1000017Du, 0x1000017Eu, 0x1000017Fu,
0x10000180u, 0x10000181u, 0x10000182u, 0x10000183u, 0x10000184u, 0x10000185u,
0x10000186u, 0x10000187u, 0x10000188u, 0x10000189u, 0x1000018Au, 0x1000018Bu,
0x1000018Cu, 0x1000018Du, 0x1000018Eu, 0x1000018Fu, 0x10000190u, 0x10000191u,
0x10000192u, 0x10000193u, 0x10000194u, 0x10000195u, 0x10000196u, 0x10000197u,
};
}