namespace NeonSprawl.Server.Game.PositionState;

/// <summary>
/// HTTP JSON body for <c>GET /game/players/{{id}}/position</c> and successful <c>POST /game/players/{{id}}/move</c>.
/// Consumers should read <see cref="SchemaVersion"/> before interpreting other fields.
/// </summary>
/// <remarks>
/// Example v1 payload (initial seed; <see cref="Sequence"/> increases after each successful move, NS-16):
/// <code>
/// {"schemaVersion":1,"playerId":"dev-local-1","position":{"x":-5,"y":0.9,"z":-5},"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>Increments by one on each successful move apply (NS-16); <c>0</c> for the seeded dev player until the first move.</summary>
    public ulong Sequence { get; init; }
}