Session Lifecycle: State Machine and Orchestration

// Application layer — no Unity or Nakama dependencies

/// <summary>
/// Input side: things you send TO the session.
/// </summary>
public interface IMatchOrchestrator
{
    void StartMatch(GameRules rules, Player[] players, Deck initialDeck);
    void HandleCommand(IGameCommand command);
}

/// <summary>
/// Output side: things you receive FROM the session.
/// </summary>
public interface IGameStateProvider
{
    /// <summary>Complete state snapshot pushed after every state change.</summary>
    IObservable<GameStateSnapshot> StateStream { get; }

    /// <summary>Discrete domain events (SetClaimed, BoardRefilled, etc.).</summary>
    IObservable<MatchEvent> EventStream { get; }
}

public class GameSession : IMatchOrchestrator, IGameStateProvider
{
    public GameSession(ISetValidator validator, IAIScanner? aiScanner = null) { ... }
    // ...
}

public enum MatchState
{
    BoardIdle,          // No cards selected. Waiting for first selection.
    CardSelected1,      // Exactly one card selected.
    CardSelected2,      // Exactly two cards selected.
    Validating,         // Third card selected; validation in progress.
                        // In SP: instant. In MP (planned): includes WaitingForServer
                        // sub-state while the Nakama server processes the claim.
    ValidSetAnim,       // Valid Set confirmed; animation playing. Input LOCKED.
    InvalidSetAnim,     // Invalid Set confirmed; feedback playing. Input LOCKED.
    RefillAnim,         // Board refilling after valid Set. Input LOCKED.
    ExpandBoardAnim,    // Dealing 3 extra cards (no Set found). Input LOCKED.
    MatchEnd            // Game over. No further input accepted.
}

public interface IGameCommand
{
    PlayerId PlayerId { get; }
}

/// <summary>Player taps an unselected card to add it to the current selection.</summary>
public class SelectCardCommand : IGameCommand
{
    public PlayerId PlayerId { get; }
    public int      SlotIndex { get; }
}

/// <summary>
/// Player taps an already-selected card to remove it from the selection.
/// Transitions: CardSelected2 → CardSelected1, or CardSelected1 → BoardIdle.
/// </summary>
public class DeselectCardCommand : IGameCommand
{
    public PlayerId PlayerId { get; }
    public int      SlotIndex { get; }
}

/// <summary>
/// In Pass and Play mode, tapping the player's colour zone finalises the claim.
/// In standard Single Player and Online, claim is automatic on the 3rd SelectCard.
/// </summary>
public class ClaimSelectedCommand : IGameCommand
{
    public PlayerId PlayerId { get; }
}

/// <summary>
/// Internal command generated by animation systems when a transition animation
/// has finished playing. Not sent by player input.
/// </summary>
public class AnimationCompleteCommand : IGameCommand
{
    public PlayerId PlayerId => PlayerId.System;
    public MatchState CompletedState { get; }
}

/// <summary>
/// Immutable DTO. Pushed on StateStream after every state change.
/// Presentation layer must never cache mutable references from this object.
/// </summary>
public sealed class GameStateSnapshot
{
    public BoardSnapshot            Board                 { get; }
    public PlayerSnapshot[]         Players               { get; }
    public int                      DeckCount             { get; }
    public IReadOnlyList<int>       SelectedSlotIndices   { get; }
    public MatchState               CurrentState          { get; }
    public float?                   RemainingTimeSeconds  { get; }  // null if not timed
}

/// <summary>
/// Immutable match configuration. All fields are set at match creation and
/// are read-only for the lifetime of the session.
/// </summary>
public sealed class GameRules
{
    /// <summary>Starting slot count — 12, 15, or 18. Default: 12.</summary>
    public int         InitialBoardSize   { get; }

    /// <summary>Hard cap on board slots. Always 21 — cannot be changed per match.</summary>
    public int         MaxBoardSize       { get; }  // = 21

    /// <summary>Consequence for submitting an invalid Set.</summary>
    public PenaltyMode PenaltyMode        { get; }  // None | Time | Point

    /// <summary>When true, the match has a countdown timer.</summary>
    public bool        IsTimed            { get; }

    /// <summary>Countdown duration in seconds. Ignored when IsTimed == false.</summary>
    public float       TimeLimitSeconds   { get; }
}

public enum PenaltyMode { None, Time, Point }

public void HandleCommand(IGameCommand command)
{
    if (IsLockedState(_state))
    {
        // Discard the command — log a warning for debugging, never throw
        Debug.LogWarning($"[GameSession] Command {command.GetType().Name} discarded " +
                         $"during locked state {_state}.");
        return;
    }

    // Route to the appropriate handler based on command type and current state
    switch (command)
    {
        case SelectCardCommand select:
            HandleSelectCard(select);
            break;
        case ClaimSelectedCommand claim:
            HandleClaim(claim);
            break;
        case AnimationCompleteCommand anim:
            HandleAnimationComplete(anim);
            break;
    }
}

private static bool IsLockedState(MatchState state) => state is
    MatchState.ValidSetAnim    or
    MatchState.InvalidSetAnim  or
    MatchState.RefillAnim      or
    MatchState.ExpandBoardAnim or
    MatchState.MatchEnd;