AI Opponents: Scanner Design and Difficulty Tiers

// Domain layer — zero Unity or Nakama dependencies
public interface IAIScanner
{
    /// <summary>
    /// Begin scanning the current board. The scanner starts an internal timer
    /// based on the difficulty tier. When the timer expires, it picks a Set
    /// (subject to miss rate) and calls onSetFound.
    /// </summary>
    /// <param name="boardCards">The cards currently visible on the board.</param>
    /// <param name="difficulty">The difficulty tier controlling delay and miss rate.</param>
    /// <param name="onSetFound">
    /// Callback invoked once with a valid three-card array.
    /// Called on the same thread as Tick(). Never called after Cancel().
    /// </param>
    void StartScan(IReadOnlyList<Card> boardCards,
                   AIDifficulty difficulty,
                   Action<Card[]> onSetFound);

    /// <summary>
    /// Cancel the current scan. The onSetFound callback will NOT be called.
    /// Safe to call when the scanner is already idle.
    /// </summary>
    void Cancel();

    /// <summary>
    /// Advance the scanner's internal timer. Called by GameSession each Update.
    /// Pass GameSession's own deltaTime (not Time.deltaTime directly) to keep
    /// the scanner decoupled from Unity for testing.
    /// </summary>
    void Tick(float deltaTime);
}

public enum AIDifficulty { Easy, Medium, Hard, Expert }

{
  "Easy":   { "minDelaySec": 4.0, "maxDelaySec": 8.0, "missRate": 0.20, "falseStartRate": 0.10 },
  "Medium": { "minDelaySec": 2.0, "maxDelaySec": 4.0, "missRate": 0.10, "falseStartRate": 0.05 },
  "Hard":   { "minDelaySec": 0.8, "maxDelaySec": 2.0, "missRate": 0.02, "falseStartRate": 0.02 },
  "Expert": { "minDelaySec": 0.3, "maxDelaySec": 0.8, "missRate": 0.00, "falseStartRate": 0.01 }
}

public class AIScanner : IAIScanner
{
    private readonly System.Random _rng = new System.Random();  // non-deterministic seed
    private AIScannerConfig _config;

    private AIState          _state       = AIState.Idle;
    private float            _timerRemaining;
    private IReadOnlyList<Card> _boardSnapshot;
    private Card[][]         _foundSets;
    private Action<Card[]>   _onSetFound;

    public void StartScan(IReadOnlyList<Card> boardCards,
                          AIDifficulty difficulty,
                          Action<Card[]> onSetFound)
    {
        Cancel();  // clean up any in-progress scan

        var cfg = _config.Get(difficulty);
        float delay = (float)(_rng.NextDouble() * (cfg.MaxDelaySec - cfg.MinDelaySec)
                              + cfg.MinDelaySec);

        _timerRemaining = delay;
        _boardSnapshot  = boardCards;
        _onSetFound     = onSetFound;
        _state          = AIState.Scanning;

        // FindAllSets is fast (<1ms for 21 cards) — call it immediately
        // so we know whether any Sets exist before the timer fires.
        _foundSets = _validator.FindAllSets(boardCards).ToArray();
    }

    public void Tick(float deltaTime)
    {
        if (_state != AIState.Scanning) return;

        _timerRemaining -= deltaTime;
        if (_timerRemaining > 0f) return;

        // Timer expired — decide whether to claim
        var cfg = _config.Get(_currentDifficulty);

        if (_foundSets.Length == 0)
        {
            // No Sets exist; board will expand soon. Do nothing.
            _state = AIState.Idle;
            return;
        }

        if (_rng.NextDouble() < cfg.MissRate)
        {
            // AI misses this opportunity — reset to idle without claiming
            _state = AIState.Idle;
            return;
        }

        // Re-validate before claiming: board may have changed since StartScan
        var chosen = _foundSets[_rng.Next(_foundSets.Length)];
        if (!_validator.Validate(chosen).IsValid)
        {
            // Stale set — board changed, abort
            _state = AIState.Idle;
            return;
        }

        _state = AIState.Found;
        _onSetFound?.Invoke(chosen);
        _state = AIState.Completed;
    }

    public void Cancel()
    {
        _state      = AIState.Idle;
        _onSetFound = null;
        _foundSets  = null;
    }
}

// Inside GameSession
public void Update(float deltaTime)
{
    _aiScanner?.Tick(deltaTime);

    if (_rules.IsTimed)
    {
        _remainingTime -= deltaTime;
        if (_remainingTime <= 0f)
            TransitionTo(MatchState.MatchEnd);
    }
}

// GameSession internal helper — planned
private AIDifficulty GetEffectiveDifficulty()
{
    if (!_rules.RubberBandEnabled) return _rules.BaseDifficulty;

    int aiScore    = _players[_aiPlayerIndex].Score;
    int humanScore = _players[_humanPlayerIndex].Score;
    int gap        = aiScore - humanScore;

    if (gap >= 3) return AIDifficulty.Easy;    // AI intentionally slowed
    if (gap >= 1) return AIDifficulty.Medium;
    return _rules.BaseDifficulty;
}