using System.Buffers.Binary;

namespace AcDream.Core.Net.Messages;

/// <summary>
/// Retail <c>Sound</c> game message (<c>0xF750</c>): the server tells the client
/// to play one <c>SoundType</c> slot from an object's SoundTable.
///
/// <para>
/// Wire layout, 16 bytes, S→C — three oracles agree:
/// <c>u32 opcode | u32 guid | u32 SoundType | f32 volume</c>. Retail dispatch is
/// <c>CM_Physics::DispatchSB_SoundEvent</c> @ <c>0x006AC760</c> (which reads
/// <c>buf+4</c>, <c>buf+8</c>, <c>buf+0xC</c>); ACE writes exactly those fields
/// in <c>GameMessageSound.cs</c> with a declared length of 16; holtburger's
/// <c>PlaySoundData</c> parses the same triple.
/// </para>
///
/// <para>
/// This message carries every server-driven cue: melee hits and wounds, wield
/// and unwield, pickup and drop, lockpicking, lifestone bind, spell resist,
/// trap triggers, item mana depletion. It was unhandled by acdream until
/// Campaign A slice A3, which is why all of those were silent.
/// </para>
/// </summary>
public readonly record struct SoundEvent(uint Guid, uint SoundType, float Volume)
{
    public const uint Opcode = 0xF750u;
    public const int WireSize = 16;

    public static SoundEvent? TryParse(ReadOnlySpan<byte> body)
    {
        if (body.Length < WireSize
            || BinaryPrimitives.ReadUInt32LittleEndian(body) != Opcode)
            return null;

        return new SoundEvent(
            BinaryPrimitives.ReadUInt32LittleEndian(body[4..]),
            BinaryPrimitives.ReadUInt32LittleEndian(body[8..]),
            BinaryPrimitives.ReadSingleLittleEndian(body[12..]));
    }
}