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);
}