namespace NeonSprawl.Server.Game.PositionState;

/// <summary>
/// HTTP JSON body for <c>POST /game/players/{{id}}/move</c>. Wire contract v1 (JSON); migrate to protobuf later per project contracts docs.
/// </summary>
/// <remarks>
/// <para><b>Server rule (v1):</b> authoritative position is set to <see cref="Target"/> immediately (snap). <see cref="PositionStateResponse.Sequence"/> increments by one on each successful apply.</para>
/// <para>Example v1 payload:</para>
/// <code>
/// {"schemaVersion":1,"target":{"x":1.5,"y":0,"z":-2}}
/// </code>
/// </remarks>
public sealed class MoveCommandRequest
{
    /// <summary>Schema version for this command shape; must match <see cref="CurrentSchemaVersion"/> for the handler to accept the body.</summary>
    public const int CurrentSchemaVersion = 1;

    /// <summary>Contract version; must equal <see cref="CurrentSchemaVersion"/>.</summary>
    public int SchemaVersion { get; init; }

    /// <summary>World-space destination the server applies (v1: exact snap).</summary>
    public PositionVector? Target { get; init; }
}