acdream/src/AcDream.Core.Net/Messages/VendorRequests.cs

using System;
using System.Buffers.Binary;
using System.Collections.Generic;

namespace AcDream.Core.Net.Messages;

/// <summary>
/// Outbound vendor GameActions. Slice 6.3: Buy (<c>0x005F</c>) only — Sell
/// (<c>0x0060</c>) is research-only scope (Slice 6 research doc §A.3), not
/// implemented here.
///
/// <para>
/// Wire layout, confirmed FOUR ways with zero disagreement (research doc
/// §A.1: ACE's reader, Chorizite's generated reader/writer, holtburger's
/// independent client, and the retail decompiled sender —
/// <c>CM_Vendor::Event_Buy</c>, <c>pc:689288</c>, <c>0x006AA0F0</c>):
/// <code>
///   u32   0xF7B1              // GameAction envelope
///   u32   gameActionSequence
///   u32   0x005F               // Buy opcode
///   u32   vendorGuid
///   u32   itemCount
///     per item:
///     i32   amount             // quantity to buy (plain positive int32,
///                               // NOT ItemProfile's packed sign-extended
///                               // supply-count field)
///     u32   objectGuid          // the SHOP ITEM's guid
///   u32   alternateCurrencyId  // TRAILING — 0 for a pyreal vendor
/// </code>
/// </para>
///
/// <para>
/// <b>The trailing <c>alternateCurrencyId</c> field — a deliberate,
/// evidence-backed divergence from ACE.</b> Retail's client
/// (<c>CM_Vendor::Event_Buy</c>) writes this field on EVERY Buy, after the
/// packed item list, every time (<c>pc:689335-689336</c>). ACE's current
/// server-side reader has the matching line PRESENT but COMMENTED OUT
/// (<c>GameActionBuyItems.cs:32</c>,
/// <c>//var altCurrencyWcid = message.Payload.ReadUInt32();</c>) — it simply
/// never reads the trailing bytes. holtburger, a real client written and
/// tested against ACE's actual accepted wire shape, omits the field
/// entirely and round-trips fine against ACE. Both are correct for what
/// they target: ACE demonstrably does not NEED this field today. We port
/// the field anyway because retail — the top oracle per this project's
/// CLAUDE.md — sends it unconditionally, it costs one <c>u32</c>, and it
/// costs ACE nothing to ignore (forward-compatible with any future ACE
/// build that un-comments its read). Do not "fix" this by dropping the
/// field without re-reading
/// <c>docs/research/2026-08-08-slice6-vendor-transactions-research.md</c>
/// §A.1 first — that document's "Resolution of the ACE/holtburger vs.
/// retail disagreement" section is the full reasoning trail.
/// </para>
/// </summary>
public static class VendorRequests
{
    public const uint GameActionEnvelope = 0xF7B1u;
    public const uint BuyOpcode = 0x005Fu;

    /// <summary>
    /// Build a Buy GameAction for <paramref name="items"/> — retail's
    /// <c>CM_Vendor::Event_Buy(vendorGuid, &amp;list, currencyId)</c>. Slice
    /// 6.3's Buy button always passes a ONE-entry list (retail
    /// <c>BuySingleItem</c>, <c>pc:201661</c>, has no staging-list
    /// dependency — see the Slice 6 research doc §B.1); the list shape is
    /// kept general because that is literally the wire message's own shape
    /// (a future "Buy All" staged-purchase path would reuse this builder
    /// unchanged, not because Slice 6.3 needs it today).
    /// </summary>
    public static byte[] BuildBuy(
        uint gameActionSequence,
        uint vendorGuid,
        IReadOnlyList<(int Amount, uint ItemGuid)> items,
        uint alternateCurrencyId)
    {
        ArgumentNullException.ThrowIfNull(items);

        int itemCount = items.Count;
        byte[] body = new byte[24 + (itemCount * 8)];
        BinaryPrimitives.WriteUInt32LittleEndian(body,            GameActionEnvelope);
        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(4),  gameActionSequence);
        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(8),  BuyOpcode);
        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(12), vendorGuid);
        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(16), (uint)itemCount);

        int offset = 20;
        for (int i = 0; i < itemCount; i++)
        {
            (int amount, uint itemGuid) = items[i];
            BinaryPrimitives.WriteInt32LittleEndian(body.AsSpan(offset), amount);
            BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(offset + 4), itemGuid);
            offset += 8;
        }

        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(offset), alternateCurrencyId);
        return body;
    }

    /// <summary>Convenience overload for the single-item Buy Slice 6.3 sends.</summary>
    public static byte[] BuildBuy(
        uint gameActionSequence,
        uint vendorGuid,
        int amount,
        uint itemGuid,
        uint alternateCurrencyId)
        => BuildBuy(
            gameActionSequence,
            vendorGuid,
            new[] { (amount, itemGuid) },
            alternateCurrencyId);
}