using System;
using System.Buffers.Binary;

namespace AcDream.Core.Net.Messages;

/// <summary>
/// Inbound primary-attribute update <c>GameMessage</c> for the local player
/// (<c>0x02E3</c>) — the server's authoritative answer to a RaiseAttribute
/// action (and any other server-side attribute change). A standalone
/// GameMessage like <see cref="PrivateUpdateVital"/>, NOT a <c>0xF7B0</c>
/// GameEvent.
///
/// <para>
/// Campaign CA slice CA2 (#431): until this parser existed the client's
/// attribute model was stale from login's PlayerDescription until the next
/// login — every post-raise derived value (skills, vitals maxima, run
/// rate) computed from old attributes.
/// </para>
///
/// <para>
/// Wire layout — three-source agreement (ACE
/// <c>GameMessagePrivateUpdateAttribute.cs:8-16</c>; Chorizite
/// <c>AttributeInfo.generated.cs:26-54</c>; holtburger
/// <c>player/types.rs:22-53</c> <c>UpdateAttribute&lt;false&gt;</c>), full
/// citations in
/// <c>docs/research/2026-08-24-advancement-wire-and-recompute.md</c> §2.5:
/// </para>
/// <code>
/// PrivateUpdateAttribute (0x02E3):
///     u32 opcode = 0x02E3
///     u8  sequence   // ByteSequence, per-attribute counter
///     u32 attribute  // PropertyAttribute (1=Strength..6=Self)
///     u32 ranks
///     u32 start      // StartingValue / InitLevel
///     u32 xp         // ExperienceSpent / CPSpent
/// </code>
/// </summary>
public static class PrivateUpdateAttribute
{
    public const uint Opcode = 0x02E3u;

    /// <summary>Parsed attribute update.</summary>
    public readonly record struct Parsed(
        byte Sequence,
        uint AttributeId,
        uint Ranks,
        uint Start,
        uint Xp);

    /// <summary>
    /// Parse a raw <c>PrivateUpdateAttribute (0x02E3)</c> body. Returns
    /// <c>null</c> on opcode mismatch or truncation.
    /// </summary>
    public static Parsed? TryParse(ReadOnlySpan<byte> body)
    {
        // 4 (opcode) + 1 (seq) + 4 * 4 (uints) = 21 bytes minimum.
        if (body.Length < 21) return null;
        uint opcode = BinaryPrimitives.ReadUInt32LittleEndian(body);
        if (opcode != Opcode) return null;

        int pos = 4;
        byte seq   = body[pos]; pos += 1;
        uint attr  = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]); pos += 4;
        uint ranks = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]); pos += 4;
        uint start = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]); pos += 4;
        uint xp    = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]);
        return new Parsed(seq, attr, ranks, start, xp);
    }
}