namespace SVSim.BattleNode.Protocol;

/// <summary>
/// Wire value of <c>result</c> on a WS <c>BattleFinish</c> frame.
/// <para>
/// Maps to the client's <c>NetworkBattleReceiver.RESULT_CODE</c> enum at
/// <c>NetworkBattleReceiver.cs:963-986</c>. The client extracts this via
/// <c>NetworkBattleReceiver.cs:1170-1172</c>:
/// <code>
///   case NetworkParameter.result:
///     _receiveData.result = (RESULT_CODE)ConvertToInt(data.Value);
/// </code>
/// then dispatches through <c>NetworkBattleManagerBase.JudgeResultReceive</c>
/// (lines 1412-1488). The wire codes are categorized by HOW the battle ended
/// (life / deckout / retire / disconnect / timeout) and are named from the
/// OPPONENT'S perspective:
/// </para>
/// <list type="bullet">
///   <item><c>LifeLose</c> = "opponent's life ran out" → PLAYER WIN UI</item>
///   <item><c>LifeWin</c> = "opponent's life win condition met" → PLAYER LOSE UI</item>
/// </list>
/// <para>
/// Prior to 2026-06-02 the docstring here claimed the values were 0/1/2 mapping
/// LOSE/WIN/CONSISTENCY — that was the HTTP <c>/finish</c> response shape, not the
/// WS frame. The previous values are kept for backwards compat with the
/// Retire/Kill scripted flow (which has shipped emitting <c>Win = 1</c>, parsed
/// client-side as <c>RESULT_CODE.NoContest</c> and rendered as "battle ended in
/// no contest" — a working-but-not-quite-right scripted-bot terminator).
/// </para>
/// <para>
/// Always serialize as the int value, not the name; see the
/// <c>JsonNumberEnumConverter</c> on <see cref="Bodies.BattleFinishBody.Result"/>.
/// </para>
/// </summary>
public enum BattleResult
{
    /// <summary>Pre-2026-06-02 value, kept for the existing Retire/Kill Scripted flow.
    /// Wire-equivalent of <c>RESULT_CODE.NotFinish = 0</c>. Don't use for new code.</summary>
    Lose = 0,
    /// <summary>Pre-2026-06-02 value, kept for the existing Retire/Kill Scripted flow.
    /// Wire-equivalent of <c>RESULT_CODE.NoContest = 1</c>. Don't use for new code.</summary>
    Win = 1,
    /// <summary>Pre-2026-06-02 value, kept for the existing Retire/Kill Scripted flow.
    /// Wire-equivalent of <c>RESULT_CODE.Invalid = 2</c>. Don't use for new code.</summary>
    Consistency = 2,

    /// <summary>Opponent's life ran out (PLAYER WIN). Pushed by Scripted mode on
    /// the player's <c>TurnEndFinal</c> emit. Matches the prod TK2 capture at
    /// <c>data_dumps/captures/battle-traffic_tk2_regular.ndjson:274</c>.</summary>
    LifeLose = 102,

    /// <summary>Opponent's life-win condition met (PLAYER LOSE). Not currently emitted
    /// by Scripted mode — the bot can't kill the player — but listed for completeness.</summary>
    LifeWin = 101,
}