namespace NeonSprawl.Server.Game.PositionState;

/// <summary>
/// HTTP JSON body for <c>GET /game/players/{{id}}/position</c>. Consumers should read
/// <see cref="SchemaVersion"/> before interpreting other fields.
/// </summary>
/// <remarks>
/// Example v1 payload:
/// <code>
/// {"schemaVersion":1,"playerId":"dev-local-1","position":{"x":0,"y":0,"z":0},"sequence":0}
/// </code>
/// </remarks>
public sealed class PositionStateResponse
{
    /// <summary>Schema version the server currently emits for this contract; increment when the shape or semantics change.</summary>
    public const int CurrentSchemaVersion = 1;

    /// <summary>Contract version; should match <see cref="CurrentSchemaVersion"/> when produced by this API.</summary>
    public int SchemaVersion { get; init; } = CurrentSchemaVersion;

    /// <summary>Player id (echo of the route for sanity).</summary>
    public required string PlayerId { get; init; }

    /// <summary>Authoritative world position.</summary>
    public required PositionVector Position { get; init; }

    /// <summary>Monotonic-ish ordering hint for future sync; v1 is always 0.</summary>
    public ulong Sequence { get; init; }
}