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

using System.Buffers.Binary;

namespace AcDream.Core.Net.Messages;

/// <summary>
/// Outbound allegiance GameActions. Swear, Break, and Kick all carry a
/// single <c>uint32</c> target-guid payload inside the standard
/// <c>0xF7B1</c> GameAction envelope.
///
/// <para>
/// Wire layout — byte-verified against
/// <c>docs/research/2026-08-11-fa-allegiance-wire.md</c> §3.2 (lane C),
/// three-way agreed with ACE + Chorizite there (the retail anchor is the
/// opcode literal store inside each <c>CM_Allegiance::Event_*</c> sender,
/// the strongest possible provenance):
/// <code>
///   u32 0xF7B1
///   u32 gameActionSequence
///   u32 subOpcode (0x001D, 0x001E)
///   u32 targetGuid
/// </code>
/// total 0x10 bytes for both. No change was needed here in Campaign FA
/// slice FA1 (2026-08-11) — the pre-existing shape already matched.
/// </para>
///
/// <para>
/// Server replies with <c>GameEventAllegianceUpdate</c> (0x0020) and
/// <c>GameEventAllegianceAllegianceUpdateDone</c> (0x01C8) on success,
/// or a <c>WeenieError</c> on failure (already sworn, already maxed
/// vassals, target not online, etc — see lane C §2 master table for the
/// full list).
/// </para>
/// </summary>
public static class AllegianceRequests
{
    public const uint GameActionEnvelope = 0xF7B1u;
    public const uint SwearOpcode = 0x001Du;
    public const uint BreakOpcode = 0x001Eu;

    /// <summary>
    /// <c>0x001F AllegianceUpdateRequest</c> — the allegiance panel's
    /// subscribe/unsubscribe toggle, the structural twin of the fellowship
    /// <c>0x00A6 FellowshipUpdateRequest</c> repaired elsewhere in this
    /// slice. Retail's <c>CM_Allegiance::Event_UpdateRequest(u32)</c>
    /// (<c>@0x006A72BA</c>, lane C §1.2) is NOT a one-shot query — send
    /// <c>1</c> on <c>gmAllegianceUI::PostInit</c>'s tail
    /// (<c>@0x004911C6</c>) and on <c>RecvNotice_PlayerDescReceived</c>
    /// (<c>@0x00490D59</c>), <c>1</c> on <c>OnVisibilityChanged</c>'s
    /// visible branch (<c>@0x004912DD</c>), <c>0</c> on its hidden branch
    /// (<c>@0x00491311</c>). ACE's own handler
    /// (<c>GameActionAllegianceUpdateRequest.cs:12</c>) reads the value
    /// and ignores it — always replying once regardless — but retail
    /// servers do not, so this must be sent correctly (lane C §7.1
    /// message #3).
    /// </summary>
    public const uint AllegianceUpdateRequestOpcode = 0x001Fu;

    /// <summary>Pledge yourself to the given patron.</summary>
    public static byte[] BuildSwear(uint gameActionSequence, uint patronGuid)
    {
        return Build(gameActionSequence, SwearOpcode, patronGuid);
    }

    /// <summary>
    /// Break your pledge to <paramref name="targetGuid"/>. Target can be
    /// your patron (breaking from) OR your vassal (breaking them away).
    /// Retail's Break button (element <c>0x10000264</c>) always targets
    /// your own patron — see <see cref="BuildKick"/> for the vassal-facing
    /// sibling button.
    /// </summary>
    public static byte[] BuildBreak(uint gameActionSequence, uint targetGuid)
    {
        return Build(gameActionSequence, BreakOpcode, targetGuid);
    }

    /// <summary>
    /// Kick a vassal out of your allegiance. Wire-identical to
    /// <see cref="BuildBreak"/> — both are <c>Event_BreakAllegiance(u32)
    /// @0x006A69DA</c> (opcode <c>0x001E</c>); retail's Kick button
    /// (<c>gmAllegianceUI::CloseKickConfirmationDialog @0x00490B00</c>)
    /// targets the selected vassal (<c>m_iidPossibleKickedVassal</c>)
    /// where Break targets <c>AllegianceProfile::GetPatron(self)</c> (lane
    /// C §1.4). Named separately purely so FA2's panel command surface can
    /// distinguish "break from patron" from "kick a vassal" without both
    /// call sites reading like the same action; the golden vector is
    /// identical to <see cref="BuildBreak"/>'s.
    /// </summary>
    public static byte[] BuildKick(uint gameActionSequence, uint vassalGuid)
    {
        return Build(gameActionSequence, BreakOpcode, vassalGuid);
    }

    /// <summary>
    /// Declare the allegiance panel's visibility/subscription state to the
    /// server (<c>0x001F AllegianceUpdateRequest</c>). See
    /// <see cref="AllegianceUpdateRequestOpcode"/> for the four retail send
    /// sites and their arguments.
    /// </summary>
    public static byte[] BuildAllegianceUpdateRequest(uint gameActionSequence, bool on)
    {
        return Build(gameActionSequence, AllegianceUpdateRequestOpcode, on ? 1u : 0u);
    }

    private static byte[] Build(uint seq, uint sub, uint targetGuid)
    {
        byte[] body = new byte[16];
        BinaryPrimitives.WriteUInt32LittleEndian(body,            GameActionEnvelope);
        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(4),  seq);
        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(8),  sub);
        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(12), targetGuid);
        return body;
    }
}