namespace AcDream.Core.Physics;

/// <summary>
/// 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
/// <c>InterpretedMotionState.cs:139</c>), truncating the class byte (Style /
/// SubState / Modifier / Action / ChatEmote / UI / Toggle / Mappable /
/// Command — see r03 §3.1). The client must re-attach the class byte before
/// routing the command into the motion table, because the same low 16 bits
/// can map to different classes (e.g. 0x0003 is <c>Ready</c> as a SubState,
/// but there's no other 0x0003).
/// </para>
///
/// <para>
/// 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>
/// Cited references:
/// <list type="bullet">
///   <item><description>
///     <c>references/ACE/Source/ACE.Server/Network/Motion/InterpretedMotionState.cs::Write</c>
///     L138-L144 — writer emits u16 for every command field.
///   </description></item>
///   <item><description>
///     <c>references/ACE/Source/ACE.Entity/Enum/CommandMasks.cs</c> — the
///     class bit assignments: 0x80=Style, 0x40=SubState, 0x20=Modifier,
///     0x10=Action, 0x13 and 0x12=ChatEmote (with Mappable set), etc.
///   </description></item>
///   <item><description>
///     <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
{
    private static readonly AceModernCommandCatalog s_aceModern = new();

    /// <summary>
    /// Given a 16-bit wire value, return the full 32-bit MotionCommand
    /// (class byte restored) per the ACE/runtime catalog. Returns 0 if no
    /// matching value exists.
    /// </summary>
    public static uint ReconstructFullCommand(ushort wireCommand)
    {
        return s_aceModern.ReconstructFullCommand(wireCommand);
    }
}