From d5fa790ccc7df43063e64b177e95c08109496aaf Mon Sep 17 00:00:00 2001 From: dingo Date: Sun, 12 Apr 2026 13:36:37 -0400 Subject: [PATCH] Add SOR.Ai architecture plan Full design document for the AI player system: project structure, integration approach (AI as a real player through the existing handler pipeline), 23 granular implementation phases across 5 tracks (scaffold, turn pipeline, MCTS, neural engine, polish), difficulty/strategy system, training data pipeline, and self-play calibration strategy. Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude Co-Authored-By: Happy --- Server/docs/SOR.Ai-Architecture-Plan.md | 1798 +++++++++++++++++++++++ 1 file changed, 1798 insertions(+) create mode 100644 Server/docs/SOR.Ai-Architecture-Plan.md diff --git a/Server/docs/SOR.Ai-Architecture-Plan.md b/Server/docs/SOR.Ai-Architecture-Plan.md new file mode 100644 index 0000000..38e116e --- /dev/null +++ b/Server/docs/SOR.Ai-Architecture-Plan.md @@ -0,0 +1,1798 @@ +# SOR.Ai — AI Player Architecture Plan + +## Overview + +`SOR.Ai` is a new server-side project that provides AI-controlled players for free-play (custom lobby) games. +Players can spin up a lobby, add 1–N AI opponents, choose difficulty, and play immediately — no wait queue needed. + +The AI integrates as **"just another player"** from the perspective of all existing infrastructure: it holds a +virtual account, joins lobbies via the existing `CustomLobby` system, and submits game actions through the same +`IMessageHandler` pipeline that human clients use. No changes to `GameEngine`, protocol contracts, or client code +are required. + +--- + +## Table of Contents + +1. [Project Structure](#1-project-structure) +2. [Integration Points](#2-integration-points) +3. [AI Account Model](#3-ai-account-model) +4. [Game Flow — How AI Joins & Plays](#4-game-flow) +5. [Decision Engine Architecture](#5-decision-engine-architecture) +6. [Difficulty System](#6-difficulty-system) +7. [Training & Improvement Strategy](#7-training--improvement-strategy) +8. [Deck Composition for AI](#8-deck-composition-for-ai) +9. [Multi-Player & Team AI](#9-multi-player--team-ai) +10. [New Message Types](#10-new-message-types) +11. [Database Schema Additions](#11-database-schema-additions) +12. [Implementation Phases](#12-implementation-phases) + +--- + +## 1. Project Structure + +``` +Server/src/SOR.Ai/ +├── SOR.Ai.csproj +├── ServiceRegistration.cs — DI wiring, registers all AI services +│ +├── Core/ +│ ├── AiPlayer.cs — Runtime state for one AI-controlled seat +│ ├── AiPlayerSession.cs — Binds an AiPlayer to a GameSession +│ ├── AiPlayerSessionManager.cs — Manages all active AI sessions (keyed by sessionId) +│ └── AiTurnContext.cs — Snapshot of GameState from an AI's perspective +│ +├── Engine/ +│ ├── IAiDecisionEngine.cs — Interface: next action given AiTurnContext +│ ├── HeuristicDecisionEngine.cs — Rule-based engine (Difficulty 1–5) +│ ├── MonteCarloEngine.cs — MCTS-based engine (Difficulty 6–8) +│ ├── NeuralDecisionEngine.cs — ML model wrapper (Difficulty 9–10, future) +│ └── RandomDecisionEngine.cs — Purely random (used for sanity testing / Novice) +│ +├── Heuristics/ +│ ├── ScoringFunctions.cs — Board evaluation: material, position, affinity control +│ ├── ActionCandidateGenerator.cs — Enumerate all legal moves from a GameState +│ ├── ThreatDetector.cs — Identifies units threatening ArchSpirit +│ ├── ResourceOptimizer.cs — SP/ST/MP expenditure strategies +│ └── AffinityController.cs — Tile control and Terramorpha placement logic +│ +├── MCTS/ +│ ├── MctsTree.cs — Monte Carlo Tree Search node + expansion +│ ├── MctsSimulator.cs — Random playout from a given GameState +│ └── MctsEvaluator.cs — Leaf-node evaluation function +│ +├── Training/ +│ ├── SelfPlayOrchestrator.cs — Runs batches of AI-vs-AI games for data generation +│ ├── GameReplayExporter.cs — Converts GameActionLog rows → training samples +│ ├── FeatureExtractor.cs — Converts GameState → numeric feature vector +│ └── TrainingDataWriter.cs — Writes JSONL / Parquet training files +│ +├── Lobby/ +│ ├── AiLobbyService.cs — Handles "add AI to lobby" requests +│ └── AiSlotAssigner.cs — Assigns AI accounts to open seats +│ +└── Handlers/ + ├── GameAddAiHandler.cs — Handles "game.ai.add" message from host + ├── GameRemoveAiHandler.cs — Handles "game.ai.remove" message from host + └── GameAiConfigureHandler.cs — Handles "game.ai.configure" (difficulty, strategy) +``` + +**Project file** (`SOR.Ai.csproj`): + +```xml + + + net8.0 + + + + + + + + + + + + + +``` + +--- + +## 2. Integration Points + +### 2.1 How AI Submits Game Actions + +The AI does **not** open a WebSocket. Instead, `AiPlayerSessionManager` — a hosted background service — +calls game handler methods **directly** (bypassing the transport layer): + +```csharp +// Conceptual: AI calling GameDrawHandler directly +var fakeConn = new AiAuthenticatedConnection(aiAccountId, sessionId); +var fakeMsg = new AiClientMessage("game.draw", seq: 0, payload: Array.Empty()); +await drawHandler.HandleAsync(fakeMsg, fakeConn, ct); +``` + +`AiAuthenticatedConnection` implements `IAuthenticatedConnection` with the AI's virtual account ID. +`AiClientMessage` implements `IClientMessage` with the given message type and payload. + +This means **the AI goes through the full handler pipeline** — transaction locking, state persistence, +push to human players — with no special-casing anywhere in the existing code. + +### 2.2 Receiving State Updates + +Rather than subscribing to Redis push channels, `AiPlayerSessionManager` reacts to its own action +completing. After the human player's turn ends (`game.end_turn` message is processed and the game's +`ActivePlayerAccountId` flips to an AI account), the `GameEndTurnHandler` raises an internal +`AiTurnStartedEvent` via NATS or an in-process `IEventBus`. `AiPlayerSessionManager` subscribes and +schedules the AI's turn. + +``` +Human: game.end_turn + → GameEndTurnHandler runs, advances turn to AI seat + → Publishes AiTurnStartedEvent { SessionId, AiAccountId } + → AiPlayerSessionManager.OnAiTurnStarted fires + → Loads GameState from session + → AiDecisionEngine.ComputeTurn(state, difficulty, aiAccountId) + → Submits sequence of game actions with configurable delay + → Calls game.end_turn on behalf of AI +``` + +### 2.3 Turn Delay (Human Feel) + +Raw AI decisions are instant. A delay is introduced to make the AI feel natural: + +- **Simulated think time**: 800ms–3s before each discrete action (drawn from a configured range per difficulty) +- **Action pacing**: individual actions (play card, move, attack) are submitted 400ms–1.2s apart +- **These are configurable via `AiDifficultyProfile`** (see §6) + +--- + +## 3. AI Account Model + +Each AI "player" is backed by a real `Account` row in the database. A seed migration creates a set of +canonical AI accounts that are reused across games. + +### 3.1 AI Account DB Record + +| Field | Value | +|---|---| +| `Id` | deterministic GUID per difficulty tier (e.g. `ai-novice-001`) | +| `Username` | "Novice AI", "Challenger AI", "Grandmaster AI", etc. | +| `IsAi` | `true` (new boolean column on Account entity) | +| `AiDifficulty` | 1–10 | +| `AiStrategy` | "Aggressive", "Control", "Balanced", "Ramp" | +| `AvatarUrl` | art asset per strategy archetype | + +`IsAi = true` accounts: +- Cannot be ranked-matched against (MatchmakerService excludes them) +- Are not shown in leaderboards +- Have their own pre-built decks (see §8) +- Have ELO tracked separately in `AiEloRecord` table (used for tuning, not displayed) + +### 3.2 Pre-Built AI Accounts + +A seed creates accounts for every combination of `(difficulty 1–10) × (strategy archetype)`: + +``` +ai-novice-aggressive Difficulty 1, Aggressive +ai-novice-control Difficulty 1, Control +ai-easy-balanced Difficulty 2, Balanced +... +ai-grandmaster-control Difficulty 10, Control +``` + +When a host adds an AI to a lobby, the client specifies `{ difficulty, strategy }`. The server +looks up the matching pre-seeded account and inserts it into the `CustomLobby.AdditionalPlayersJson` +(or `GuestAccountId` for the second seat in a 1v1). + +--- + +## 4. Game Flow + +### 4.1 Host Adds AI to a Custom Lobby + +``` +Host (client) + → sends: game.ai.add { lobbyId, difficulty: 3, strategy: "Balanced" } + +GameAddAiHandler + → Validates: only host can add AI + → Validates: lobby must be Open or not Full + → AiSlotAssigner.Assign(lobbyId, difficulty, strategy) + → Looks up matching AI account (e.g. ai-easy-balanced) + → Inserts AI account into AdditionalPlayersJson or GuestAccountId + → AI seat is marked IsAiControlled = true in lobby data + → Pushes CustomLobbyUpdatedPush to all lobby members + → AI seat appears in lobby as a named player with AI badge +``` + +Multiple AIs are supported by calling `game.ai.add` repeatedly (up to `MaxPlayers - 1`). + +### 4.2 Lobby Ready → Game Start + +When the host marks ready and the game starts (existing `GameLobbyReadyHandler`): + +1. `GameSession` is created with AI accounts in their seats (no change to existing code). +2. `AiPlayerSessionManager.OnGameSessionCreated` is called. +3. Manager creates an `AiPlayerSession` for each AI seat in that session. +4. AI seats automatically send `game.ready` after a short delay so the game can begin even if AI is the only non-human. + +### 4.3 AI Turn Execution + +``` +AiPlayerSession.ExecuteTurnAsync(state, difficulty, strategy, ct): + + 1. AiTurnContext ctx = BuildContext(state, aiAccountId) + 2. AiAction[] actions = decisionEngine.ComputeTurn(ctx) + // actions is an ordered list of: draw, play_card, move, attack, end_turn, etc. + 3. For each action in actions: + a. await Task.Delay(ThinkTime(difficulty)) // simulated delay + b. Serialize action to IClientMessage payload + c. Call appropriate handler directly + d. If handler returns error (e.g. game state changed mid-turn), re-evaluate + 4. Finally: call GameEndTurnHandler +``` + +### 4.4 AI in Multi-Player / FFA + +Each AI account is managed as a separate `AiPlayerSession`. Sessions are independent. +When it is AI-seat-3's turn, only AI-seat-3's session fires. Team play AIs do not coordinate +(in Phase 1); coordinated team AI is a future enhancement. + +--- + +## 5. Decision Engine Architecture + +### 5.1 Interface + +```csharp +public interface IAiDecisionEngine +{ + /// + /// Compute the full sequence of actions the AI will take this turn. + /// Returns actions in submission order; the caller is responsible for delays and submission. + /// + IReadOnlyList ComputeTurn(AiTurnContext ctx); +} + +public abstract record AiAction; +public record AiDrawAction : AiAction; +public record AiPlayCardAction(string CardInstanceId, Coord TargetTile, + IReadOnlyList CardTargets) : AiAction; +public record AiMoveAction(string UnitInstanceId, Coord TargetPosition) : AiAction; +public record AiAttackAction(string AttackerInstanceId, string TargetInstanceId) : AiAction; +public record AiActivateAbilityAction(string SourceId, int AbilityIndex, + IReadOnlyList Targets) : AiAction; +public record AiSacrificeAction(string UnitInstanceId) : AiAction; +public record AiAscendAction(string IncomingArchSpiritInstanceId) : AiAction; +public record AiEndTurnAction : AiAction; +``` + +### 5.2 HeuristicDecisionEngine (Difficulty 1–5) + +Pure rule-based. Fast (< 50ms per turn). No lookahead. + +**Turn planning algorithm:** + +``` +1. Draw Phase + → Always draw (nothing to decide) + +2. Main Phase — Iterative Greedy Loop: + a. Score current board state (ScoringFunctions.Evaluate) + b. Generate all candidate actions (ActionCandidateGenerator.All) + c. Score each candidate: simulate action → score new state + d. Pick highest-scoring candidate above threshold + e. Repeat until no candidate improves score OR SP/ST exhausted + f. Apply DifficultyFilter: randomly skip/replace N% of optimal moves + +3. End Turn +``` + +**Board Evaluation (ScoringFunctions.Evaluate):** + +``` +Score = Σ weights × features + +Material: + + (unit Damage × 2 + unit MaxHealth) per own unit on field + - (unit Damage × 2 + unit MaxHealth) per opponent unit on field + + ArchSpirit HP ratio × 500 + +Affinity Control: + + tiles of own ArchSpirit affinity within channeling range × 3 + +Threat: + - units that can reach own ArchSpirit next turn × 30 + +Resource Efficiency: + + (SP remaining / SpCap) × -10 // penalize hoarding too much SP + + SacrificeTokens × 5 + +Positional: + + units adjacent to opponent ArchSpirit × 15 + + units in center board zone × 2 +``` + +Weights are stored in `AiDifficultyProfile` and tuned per difficulty tier (see §6). + +**ActionCandidateGenerator.All(ctx) → List:** + +``` +Channeling candidates: + foreach card in hand where player.CurrentSp >= card.SpCost: + foreach tile where ChannelingRange.Contains(tile) && affinity matches: + yield PlayCardAction(card, tile) + +Movement candidates: + foreach unit on field where unit.CanMove && unit.CurrentMp > 0: + foreach reachable tile (pathfinding): + yield MoveAction(unit, tile) + +Attack candidates: + foreach unit on field where unit.CanAttack: + foreach enemy in attack range: + yield AttackAction(unit, enemy) + +Ability candidates: + foreach unit on field where unit.CanUseAbility: + foreach ability where conditions met: + foreach valid target combination: + yield ActivateAbilityAction(unit, abilityIdx, targets) + +Sacrifice candidates: + foreach unit on field where unit can be sacrificed: + yield SacrificeAction(unit) + +Ascend candidates: + if player has next-tier ArchSpirit in hand && can ascend: + yield AscendAction(archSpirit) +``` + +### 5.3 MonteCarloEngine (Difficulty 6–8) + +Uses **Monte Carlo Tree Search (MCTS)** with random playouts. Can look N turns ahead. + +``` +Root = current GameState for this AI +Iterations = f(difficulty, remainingBudgetMs) + +repeat Iterations: + 1. Selection: traverse tree using UCB1 formula + UCB1 = (wins/visits) + C × sqrt(ln(parent.visits) / node.visits) + 2. Expansion: if node not fully expanded, add one new child (one candidate action) + 3. Simulation: random playout from child state until game over or N turns deep + (uses RandomDecisionEngine for all players including opponents) + 4. Backpropagation: update win/loss counts up the tree + +Best action = child of root with highest visit count (most-explored = most-trusted) +``` + +**Time budgets per difficulty:** +- Difficulty 6: 500ms think budget, 3-turn depth +- Difficulty 7: 1.5s think budget, 5-turn depth +- Difficulty 8: 4s think budget, 7-turn depth + +For multi-action turns (play card + move + attack), MCTS treats the full sequence as a plan and +builds the tree over **turn sequences** (not individual actions). This is done by treating +"all actions until end_turn" as one composite node. + +### 5.4 NeuralDecisionEngine (Difficulty 9–10, Phase 3) + +Wraps a trained neural network model. Architecture TBD (likely a feedforward net or lightweight +transformer on flattened board + hand state). The model predicts: + +- **Policy head**: probability distribution over candidate actions +- **Value head**: estimated win probability from current state + +The engine selects the highest-policy action that doesn't reduce value below a threshold. + +Model inference is performed via **ONNX Runtime** (`Microsoft.ML.OnnxRuntime`), allowing models +trained in Python (PyTorch / TensorFlow) to run in-process in the .NET server. + +--- + +## 6. Difficulty System + +### 6.1 Difficulty Tiers + +| Tier | Name | Engine | Mistake Rate | Think Budget | +|---|---|---|---|---| +| 1 | Novice | Random | 100% random | none | +| 2 | Apprentice | Heuristic | 60% mistakes | 50ms | +| 3 | Journeyman | Heuristic | 40% mistakes | 50ms | +| 4 | Adept | Heuristic | 25% mistakes | 50ms | +| 5 | Expert | Heuristic | 10% mistakes | 50ms | +| 6 | Master | MCTS | 5% mistakes | 500ms | +| 7 | Grandmaster | MCTS | 2% mistakes | 1.5s | +| 8 | Champion | MCTS | 0% | 4s | +| 9 | Legend | Neural | 0% | 200ms inference | +| 10 | Mythic | Neural | 0%, beam search | 500ms inference | + +### 6.2 AiDifficultyProfile + +```csharp +public record AiDifficultyProfile +{ + public int Difficulty { get; init; } // 1–10 + public string DisplayName { get; init; } + public string EngineType { get; init; } // "Random" | "Heuristic" | "MCTS" | "Neural" + + // Mistake injection + public float MistakeRate { get; init; } // 0.0–1.0: probability of replacing optimal with random action + public float SuboptimalRate { get; init; } // 0.0–1.0: probability of picking 2nd-best instead of best + + // MCTS params (if applicable) + public int MctsTimeBudgetMs { get; init; } + public int MctsMaxDepth { get; init; } + + // Simulated delays (humanization) + public int MinThinkTimeMs { get; init; } // before first action each turn + public int MaxThinkTimeMs { get; init; } + public int MinActionDelayMs { get; init; } // between subsequent actions + public int MaxActionDelayMs { get; init; } + + // Scoring weight overrides (heuristic engine) + public float MaterialWeight { get; init; } + public float AffinityControlWeight { get; init; } + public float ThreatWeight { get; init; } + public float PositionalWeight { get; init; } + public float ResourceWeight { get; init; } +} +``` + +Profiles are defined as a static table in `AiDifficultyProfiles.cs` (in-code constants, not DB-stored), +making them easy to tune without migrations. + +### 6.3 Strategy Archetypes + +Strategy affects **which actions the AI prioritizes**, not how good it is: + +| Strategy | Description | Playstyle | +|---|---|---| +| `Aggressive` | Rush opponent ArchSpirit; maximize attack pressure | Front-row units, direct damage | +| `Control` | Protect own ArchSpirit; build affinity control | Back-row units, Terramorpha spam | +| `Balanced` | Mix of attack and defense | General-purpose | +| `Ramp` | Maximize SP/ST accumulation for high-cost plays | Sacrifice-heavy, late-game cards | +| `Swarm` | Channel many low-cost Spirits; overwhelm by count | Cheap spirits, wide field | + +Strategy is encoded as **scoring function weight adjustments** layered on top of the difficulty +profile. An `Aggressive` AI at difficulty 5 and a `Control` AI at difficulty 5 make equally +"good" moves — but in different directions. + +```csharp +// Example: Aggressive adjusts weights +profile = profile with { + MaterialWeight = profile.MaterialWeight * 1.3f, + ThreatWeight = profile.ThreatWeight * 0.5f, // less concerned about own ArchSpirit +}; +``` + +--- + +## 7. Training & Improvement Strategy + +### 7.1 Training Data Sources + +Training data is generated from three sources, in order of quality: + +**Source 1: Human Game Replays** +- All completed `GameSession` rows have a full `ActionLog` (sequence of actions + states) +- `GameReplayExporter` converts each log to a sequence of `(state, action, outcome)` triples +- Outcome = did this player win? (1 = win, 0 = loss) +- Only high-quality games are used: both players above rank 1200, game went > 10 turns + +**Source 2: AI Self-Play** +- `SelfPlayOrchestrator` runs `AiVsAiGameSession` batches (no network, no DB needed — pure `GameEngine` calls) +- MCTS AI (difficulty 7+) plays against itself 10,000+ games per training run +- Self-play generates diverse board states including rare positions humans rarely reach +- Runs as a background job, controlled by admin API: `POST /admin/ai/self-play/start { numGames, difficulty }` + +**Source 3: Bootstrapped Heuristic Rollouts** +- For cold-start (before any data exists), heuristic AI at difficulty 5 generates initial training set +- Lower quality but quick to generate; replaced by better sources over time + +### 7.2 Feature Extraction + +`FeatureExtractor.Extract(GameState state, string aiAccountId) → float[]` + +The feature vector is a fixed-size array encoding the full game state: + +``` +Board Features (9×9 grid): + [0..80] Tile affinity type (one-hot per tile, 6 values each → 486 floats) + [486..566] Tile occupant: own/enemy/empty (3 values per tile → 81×3 = 243) + [729..809] Occupant unit type index (normalized) + [810..890] Occupant HP ratio + [891..971] Occupant Damage (normalized) + +Own Player State: + [972] CurrentSp / SpCap + [973] CurrentSt / 10 + [974] Hand size / HandSizeCap + [975] Deck size / MaxDeckSize + [976] Own ArchSpirit HP ratio + [977] Own ArchSpirit tier / 3 + [978] Field unit count / 10 + [979] TurnNumber / 30 + +Opponent State (same fields, offset by constant): + [980..987] (same structure) + +Global: + [988] ActivePlayerIsAi (1.0 if AI is active player, 0.0 otherwise) + [989] GameMode FFA=0, Teams=0.5, MultiTeam=1.0 + +Total: ~990 floats +``` + +### 7.3 Model Architecture (Phase 3) + +A lightweight **feedforward neural network**: + +``` +Input layer: 990 units +Dense layer: 512 units, ReLU +Dense layer: 256 units, ReLU +Dense layer: 128 units, ReLU + +Split into two heads: + Policy head: 128 → num_actions (softmax over candidate action types) + Value head: 128 → 1 (sigmoid, win probability) +``` + +Training objective: +- **Policy loss**: cross-entropy between predicted policy and action chosen in replay +- **Value loss**: MSE between predicted win probability and actual game outcome + +Trained in Python using PyTorch, exported to ONNX, deployed to `/Server/models/sor-ai-v{N}.onnx`. +`NeuralDecisionEngine` loads the ONNX model via `Microsoft.ML.OnnxRuntime` at service startup. + +### 7.4 Training Pipeline + +``` +1. Data Collection (continuous) + GameReplayExporter runs as background job nightly: + SELECT * FROM game_action_logs + JOIN game_sessions ON ... + WHERE sessions.status = 'Completed' + AND sessions.ended_at > last_export_timestamp + → Write JSONL to /data/training/raw/{date}.jsonl + +2. Feature Extraction (offline, Python) + python scripts/extract_features.py --input raw/ --output features/ + Reads JSONL, calls FeatureExtractor equivalent in Python, writes Parquet + +3. Model Training (offline, Python) + python scripts/train.py --data features/ --epochs 50 --output models/ + Trains PyTorch model, validates on held-out set + +4. Export & Validate + python scripts/export_onnx.py --model models/best.pt --output sor-ai-v{N}.onnx + Run benchmark: AiVsAiBenchmark plays 1000 games new vs old model; new must win > 55% + +5. Deploy + Copy sor-ai-v{N}.onnx to server/models/ + Admin calls: POST /admin/ai/reload-model { version: N } + NeuralDecisionEngine.ReloadModel() hot-swaps without restart +``` + +### 7.5 Difficulty Calibration + +After each self-play / training cycle, run **calibration games** against human players: + +- Pull a random sample of 100 recent ranked games (human ELO distribution) +- Run AI at each difficulty tier against a simulated human from a comparable rank +- Measure AI win rate: target ~40–60% win rate for each difficulty tier against the matching rank band + +Calibration thresholds (target AI win rate vs human ELO band): + +| Difficulty | Target ELO range | Target AI win% | +|---|---|---| +| 1 | Unranked (any) | 10–25% | +| 2 | 800–1000 | 30–45% | +| 3 | 1000–1100 | 35–50% | +| 4 | 1100–1200 | 40–55% | +| 5 | 1200–1350 | 45–55% | +| 6 | 1350–1500 | 45–55% | +| 7 | 1500–1700 | 45–55% | +| 8 | 1700–1900 | 45–55% | +| 9 | 1900–2100 | 45–55% | +| 10 | 2100+ | 45–55% | + +If win rate drifts outside target, adjust `MistakeRate` / MCTS budget / scoring weights accordingly. +Calibration runs are automated via `AiCalibrationJob` (admin-triggered). + +--- + +## 8. Deck Composition for AI + +### 8.1 AI Deck Creation + +AI players need pre-built decks. These are not in the player collection system; they are seeded +directly in the `Deck` table with `AccountId` = the AI's virtual account. + +Each AI account gets **one deck per viable ArchSpirit + affinity combination**, covering major +strategic archetypes: + +``` +ai-novice-balanced: + ArchSpirit: "Ignis Pup" (Fire, Tier 1) + Deck: 30-card fire-affinity mix of Spirits and Repentance cards + (Simple, no complex ability chains) + +ai-master-control: + ArchSpirit: "Hydra Sentinel" (Water, Tier 1) + Deck: 30-card water-control deck with Terramorpha + defensive Spirits + (Uses advanced affinity tile locking) + +ai-grandmaster-aggressive: + ArchSpirit: "Blazing Warchief" (Fire, Tier 1) + Deck: 30-card aggro deck, cheap Spirits, rush down opponent +``` + +Deck seeds are defined as code constants in `AiDeckDefinitions.cs` and applied via a DB seed +migration. AI decks bypass normal deck validation requirements (IsValid flag forced true). + +### 8.2 Deck Matching to Strategy + +`AiSlotAssigner` picks the AI account whose strategy matches the host's request. For the first +implementation, one deck per strategy tier is sufficient. Future iterations may allow AI to +choose a deck based on opponent's ArchSpirit (counter-deck logic). + +--- + +## 9. Multi-Player & Team AI + +### 9.1 FFA (Free-For-All) + +Each AI seat is independently managed by a separate `AiPlayerSession`. The AI evaluates all +opponents as threats; scoring functions weight all enemy ArchSpirits equally (no preferred target +in base version; future: target weakest). + +### 9.2 Team Mode + +In team games, AI evaluates friendly units as **protected** (does not attack them) and enemy +units as **threats**. The AI is not aware of teammate's planned actions — it plays optimistically. + +Future Phase 2: implement `TeamAiCoordinator` that shares intention signals between team-AI +sessions (e.g. "I will attack this unit, don't duplicate effort"). + +--- + +## 10. New Message Types + +Add to `GameMessages.cs`: + +```csharp +// Host → Server: add an AI player to a custom lobby +public record GameAddAiRequest(string LobbyId, int Difficulty, string Strategy); +public record GameAddAiResponse(string AiAccountId, string AiDisplayName, int SeatIndex); + +// Host → Server: remove an AI player from a custom lobby +public record GameRemoveAiRequest(string LobbyId, string AiAccountId); +public record GameRemoveAiResponse(bool Success); + +// Host → Server: change AI difficulty or strategy before game starts +public record GameConfigureAiRequest(string LobbyId, string AiAccountId, + int? Difficulty, string? Strategy); +public record GameConfigureAiResponse(bool Success); + +// Push → all lobby members: lobby AI slots changed +public record CustomLobbyAiSlotsChangedPush(string LobbyId, + IReadOnlyList CurrentAiSlots); + +public record AiSlotInfo(string AccountId, string DisplayName, + int Difficulty, string Strategy, int SeatIndex); +``` + +Message type strings: +- `"game.ai.add"` → `GameAddAiHandler` +- `"game.ai.remove"` → `GameRemoveAiHandler` +- `"game.ai.configure"` → `GameAiConfigureHandler` + +--- + +## 11. Database Schema Additions + +### 11.1 Account.IsAi Column + +```sql +ALTER TABLE accounts ADD COLUMN is_ai BOOLEAN NOT NULL DEFAULT FALSE; +ALTER TABLE accounts ADD COLUMN ai_difficulty INT NULL; +ALTER TABLE accounts ADD COLUMN ai_strategy TEXT NULL; +``` + +`Account` entity: +```csharp +public bool IsAi { get; set; } +public int? AiDifficulty { get; set; } +public string? AiStrategy { get; set; } +``` + +### 11.2 AiEloRecord Table + +Tracks AI performance separately from ranked ELO (not shown to players): + +```sql +CREATE TABLE ai_elo_records ( + id UUID PRIMARY KEY, + ai_account_id UUID NOT NULL REFERENCES accounts(id), + elo_score INT NOT NULL DEFAULT 1200, + wins INT NOT NULL DEFAULT 0, + losses INT NOT NULL DEFAULT 0, + updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() +); +``` + +### 11.3 CustomLobby AI Slot Tracking + +Add to `CustomLobby`: + +```sql +ALTER TABLE custom_lobbies ADD COLUMN ai_slots_json JSONB NULL; +``` + +`AiSlotsJson` is an array of: +```json +[ + { "accountId": "ai-easy-balanced", "seatIndex": 2, "difficulty": 3, "strategy": "Balanced" } +] +``` + +--- + +## 12. Implementation Phases + +Phases are deliberately narrow so each can be handed off as a single focused coding session. +Each phase lists **exact files to create or modify**, the **DI wiring required**, and a +**"done" definition** — a concrete test you can run to confirm the phase is complete before +moving on. + +Phases are grouped into tracks: +- **Track A (1.x)** — Project scaffold, database, and lobby plumbing. No AI logic yet. +- **Track B (2.x)** — Turn execution pipeline. Random AI first, then heuristic. +- **Track C (3.x)** — Competitive MCTS AI + training data collection. +- **Track D (4.x)** — Neural AI + offline training pipeline. +- **Track E (5.x)** — Polish, adaptive difficulty, ecosystem features. + +--- + +### Phase 1.1 — Project Scaffold + +**Goal**: `SOR.Ai` compiles, is wired into `SOR.Host`, and registers its own empty +`ServiceRegistration`. Nothing runs yet — this is pure plumbing. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +├── SOR.Ai.csproj +└── ServiceRegistration.cs +``` + +**`SOR.Ai.csproj`** — follow the same pattern as all other class libraries: +- `Sdk="Microsoft.NET.Sdk"`, `net8.0` +- `` +- Project references: `SOR.Database`, `SOR.Game`, `SOR.Networking.Abstractions`, `SOR.Shared` + +**`ServiceRegistration.cs`:** +```csharp +namespace SOR.Ai; + +public static class ServiceRegistration +{ + public static IServiceCollection AddAiService( + this IServiceCollection services, + IConfiguration configuration) + { + // phases will add registrations here + return services; + } +} +``` + +**Files to modify:** + +- `Server/SOR.slnx` — add `SOR.Ai` project entry +- `Server/src/SOR.Host/SOR.Host.csproj` — add `` to `SOR.Ai` +- `Server/src/SOR.Host/Program.cs` — call `builder.Services.AddAiService(builder.Configuration)` + immediately after `AddGameService`, guarded by the same `ENABLED_SERVICES` check pattern + +**Done when**: `dotnet build Server/SOR.slnx` produces zero errors and zero warnings. + +--- + +### Phase 1.2 — AI Transport Abstractions + +**Goal**: Define `AiAuthenticatedConnection` and `AiClientMessage` — the two types that let AI +code call game handlers directly without a WebSocket. These are the foundation everything else +builds on. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Transport/ + ├── AiAuthenticatedConnection.cs + └── AiClientMessage.cs +``` + +**`AiAuthenticatedConnection`** implements `IAuthenticatedConnection` (from +`SOR.Networking.Abstractions`). It holds: +- `string UserId` — the AI's virtual account ID (passed in constructor) +- `Guid SessionId` — the game session it belongs to +- All other members of the interface no-op or throw `NotSupportedException` + +**`AiClientMessage`** implements `IClientMessage`. It holds: +- `string Type` — the message type string (e.g. `"game.draw"`) +- `int Seq` — always 0 (no reply routing needed for AI) +- `ReadOnlyMemory Payload` — pre-serialized JSON payload bytes + +The payload is serialized by the caller using `JsonSerializer.SerializeToUtf8Bytes(request)`, +matching exactly how `SOR.Gateway` deserializes incoming WebSocket frames. + +**No DI registration needed** — these are `new`-able value types, instantiated per action. + +**Done when**: Both types compile and the `IAuthenticatedConnection` / `IClientMessage` contracts +are fully satisfied (no NotImplementedExceptions that handlers would hit during normal turn flow). + +--- + +### Phase 1.3 — Database: AI Account Schema + +**Goal**: Add the `IsAi`, `AiDifficulty`, and `AiStrategy` columns to the `Account` entity and +produce a migration. No seed data yet — that comes in 1.4. + +**Files to modify:** + +- `Server/src/SOR.Database/Entities/Identity/Account.cs` + — add three properties: + ```csharp + public bool IsAi { get; set; } + public int? AiDifficulty { get; set; } + public string? AiStrategy { get; set; } + ``` + +- `Server/src/SOR.Database/Contexts/SorIdentityDbContext.cs` + — add `.HasDefaultValue(false)` config for `IsAi` in `OnModelCreating` + +- `Server/src/SOR.Database/Entities/Game/CustomLobby.cs` + — add `public string? AiSlotsJson { get; set; }` (JSONB column, nullable) + +- `Server/src/SOR.Matchmaking/MatchmakerService.cs` + — add `.Where(e => !e.Account.IsAi)` (or equivalent join filter) so AI accounts + are never entered into the ranked queue + +**Migration**: run `dotnet ef migrations add AddAiAccountFields` targeting +`SorIdentityDbContext` and a separate migration targeting `GameDbContext` for +`CustomLobby.AiSlotsJson`. Follow the existing migration project structure. + +**Done when**: migrations apply cleanly against a local dev DB and the Matchmaking +service query is confirmed to exclude `IsAi = true` accounts via a unit or integration test. + +--- + +### Phase 1.4 — AI Account Seeds + +**Goal**: Seed one AI `Account` row per `(difficulty, strategy)` combination into the DB. +These accounts are the "virtual players" that will join lobbies. Decks come in Phase 1.5. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Seeding/ + └── AiAccountSeeder.cs +``` + +**`AiAccountSeeder`** is a static helper called from `ServiceRegistration.AddAiService`: +```csharp +// Called at startup: ensures AI accounts exist, idempotent (upsert by deterministic ID) +internal static async Task SeedAsync(SorIdentityDbContext identityDb, CancellationToken ct) +``` + +It uses a deterministic GUID-from-name strategy for each account ID so re-running is safe. +For each combination of difficulties 1–10 and strategies `["Aggressive", "Control", +"Balanced", "Ramp", "Swarm"]`, it upserts an Account row with: +- `IsAi = true` +- `AiDifficulty` / `AiStrategy` set +- `Username` = e.g. `"Balanced AI (Adept)"` (human-readable display name) +- `RankScore = 0`, `OriginPoints = 0` (AI accounts don't earn currency) +- `IsEmailVerified = true`, `PasswordHash = ""` (never logs in) + +**DI wiring** (in `ServiceRegistration.cs`): +```csharp +// Register as IHostedService so it runs once at startup before traffic is accepted +services.AddHostedService(); +``` + +`AiSeedStartupService` is a one-shot `IHostedService` that calls `AiAccountSeeder.SeedAsync` +then exits — same pattern as the existing `GameStartupCleanupService`. + +**Done when**: after server start, a DB query for `WHERE is_ai = true` returns exactly +`10 difficulties × 5 strategies = 50` rows. + +--- + +### Phase 1.5 — AI Deck Seeds + +**Goal**: Create one pre-built `Deck` (with `DeckCard` rows) for each AI account. Decks are +seeded from code-defined constants; they do not go through normal collection ownership. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Seeding/ + ├── AiDeckDefinitions.cs — static list of deck blueprints (by strategy archetype) + └── AiDeckSeeder.cs — upserts Deck + DeckCard rows for each AI account +``` + +**`AiDeckDefinitions.cs`** defines a `record AiDeckBlueprint(string Strategy, string ArchSpiritName, string[] CardNames)`. +One blueprint per strategy archetype: +- `Balanced` — one ArchSpirit, mixed Spirit/Repentance cards +- `Aggressive` — cheap Spirits, attack-range units, Repentance damage spells +- `Control` — Terramorpha + high-defense Spirits, few attacks +- `Ramp` — Sacrifice-heavy Spirits, high-cost powerful late-game cards +- `Swarm` — max-count low-SP Spirits, wide board presence + +Blueprints reference cards by name. `AiDeckSeeder` resolves names to `CardDefinitionId` at +seed time (query `CardDefinitions WHERE Name = ?`). If a card doesn't exist in the catalog +(environment without full card data), the seeder logs a warning and skips, allowing partial +decks to still work. + +**`AiDeckSeeder`** upserts one `Deck` row per AI account with: +- `AccountId` = AI account ID +- `IsValid = true` (forced — bypasses deck-construction validation) +- Cards from matching blueprint + +**DI wiring**: called inside `AiSeedStartupService` after `AiAccountSeeder.SeedAsync` completes, +so both run atomically at startup. + +**Done when**: after server start, each AI account has at least one `Deck` row with at least +one `DeckCard` child row; querying `decks WHERE account_id IN (ai account IDs)` returns 50 rows. + +--- + +### Phase 1.6 — Lobby Handlers: Add / Remove / Configure AI + +**Goal**: Expose the three message handlers that let a host manage AI seats in a custom lobby. +After this phase, a host can add/remove AI players from a lobby via the client — though the AI +won't actually play yet (turn execution comes later). + +**New message types** — add to `SOR.Game/GameMessages.cs`: +```csharp +public record GameAddAiRequest(Guid LobbyId, int Difficulty, string Strategy); +public record GameAddAiResponse(Guid AiAccountId, string AiDisplayName, int SeatIndex); + +public record GameRemoveAiRequest(Guid LobbyId, Guid AiAccountId); +public record GameRemoveAiResponse(bool Success); + +public record GameConfigureAiRequest(Guid LobbyId, Guid AiAccountId, + int? Difficulty, string? Strategy); +public record GameConfigureAiResponse(bool Success); + +public record CustomLobbyAiSlotsChangedPush(Guid LobbyId, + IReadOnlyList CurrentAiSlots); + +public record AiSlotInfo(Guid AccountId, string DisplayName, + int Difficulty, string Strategy, int SeatIndex); +``` + +**Files to create:** + +``` +Server/src/SOR.Ai/ +├── Lobby/ +│ ├── AiSlotAssigner.cs — resolves (difficulty, strategy) → AI Account + seat index +│ └── AiLobbyService.cs — shared read/write helpers for CustomLobby.AiSlotsJson +└── Handlers/ + ├── GameAddAiHandler.cs + ├── GameRemoveAiHandler.cs + └── GameConfigureAiHandler.cs +``` + +**Handler pattern**: each handler extends `GameHandlerBase` (from `SOR.Game.Handlers`), +taking a `GameDbContext` and `IClientPush` via constructor (injected as transient, same as all +existing game handlers). Each validates: +- `conn.UserId == lobby.HostAccountId` (only host can manage AI slots) +- Lobby status is `Open` or `Full` (not `Started` or `Completed`) +- For Add: seat count after add does not exceed `lobby.MaxPlayers` +- For Remove: the given AI account is actually in `AiSlotsJson` + +`AiSlotAssigner.Assign(difficulty, strategy)` queries `identityDb.Users WHERE IsAi = true +AND AiDifficulty = difficulty AND AiStrategy = strategy LIMIT 1` and returns the account. + +After any mutation, all handlers push `CustomLobbyAiSlotsChangedPush` to all lobby members +(using the same `clientPush.PushAsync` pattern as existing lobby handlers). + +**DI wiring** in `SOR.Ai/ServiceRegistration.cs`: +```csharp +services.AddTransient(); +services.AddTransient(); +services.AddTransient(); +services.AddScoped(); +services.AddScoped(); +``` + +**Done when**: a client can call `game.ai.add` on an open lobby and receive a valid +`GameAddAiResponse`; calling `game.ai.remove` removes it; both changes are persisted to +`CustomLobby.AiSlotsJson` and pushed to all lobby members. + +--- + +### Phase 1.7 — AI Session Manager (Hosted Service Skeleton) + +**Goal**: Create `AiPlayerSessionManager` — the singleton hosted service that will orchestrate +AI turns. In this phase it only handles the game-start event and registers active AI sessions. +Turn execution is wired in Phase 2.1. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Core/ + ├── AiPlayerSession.cs — per-session state for one AI seat + ├── AiPlayerSessionManager.cs — singleton hosted service, manages all active AI sessions + └── AiTurnContext.cs — snapshot of GameState from one AI's perspective +``` + +**`AiPlayerSession`** holds: +- `Guid SessionId` +- `Guid AiAccountId` +- `int Difficulty`, `string Strategy` +- `int SeatIndex` +- `CancellationTokenSource SessionCts` — cancelled when game ends + +**`AiPlayerSessionManager`** is a `BackgroundService` that: +1. Subscribes to NATS subject `NatsSubjects.GameStarted` (the same event `SOR.Matchmaking` + already publishes when any game starts — including custom lobby games) +2. On `GameStartedEvent`, loads the `GameSession` from DB and inspects `AdditionalPlayersJson` + plus `GuestAccountId` / `PlayerOneAccountId` to identify any seats whose account has `IsAi = true` +3. Creates one `AiPlayerSession` per AI seat and stores it in a `ConcurrentDictionary>` +4. Subscribes to NATS subject `NatsSubjects.GameEnded` and disposes sessions for that game + +At this stage, the sessions are created but no turn logic fires yet. + +**Auto-ready**: when the game session is first created and an AI is in a seat, the manager +sends `game.ready` (via a direct handler call using `AiAuthenticatedConnection` + `AiClientMessage`) +with a short random delay (200–800ms). This allows a 1-human-vs-1-AI lobby to start without +the human waiting for a fake "opponent connect" event. + +**DI wiring** in `ServiceRegistration.cs`: +```csharp +services.AddSingleton(); +services.AddHostedService(sp => sp.GetRequiredService()); +``` + +**Done when**: starting a custom lobby game that has one AI seat causes `AiPlayerSessionManager` +to log "AI session registered: {sessionId} seat {seatIndex}" and the game transitions past the +ready phase automatically (the AI submits `game.ready`). + +--- + +### Phase 2.1 — Turn Event + Action Submission Pipeline + +**Goal**: Wire up the `AiTurnStartedEvent` from `GameEndTurnHandler` and implement the action +submission loop in `AiPlayerSession`. After this phase, the AI will take turns — even if it +does nothing useful on them (end turn immediately). This proves the end-to-end pipeline works. + +**Files to modify:** + +- `SOR.Shared/Nats/NatsSubjects.cs` — add `public const string AiTurnStarted = "sor.game.ai_turn_started";` +- `SOR.Game/Handlers/GameEndTurnHandler.cs` — after advancing the turn, if the new + `state.ActivePlayerAccountId` is an AI account (check via `IEventBus` — publish + `AiTurnStartedEvent { SessionId, AiAccountId, TurnNumber }`). The check is done by looking up + whether `activePlayerId` appears in a locally-injected `IAiAccountRegistry` (see below). + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Core/ + └── AiAccountRegistry.cs — singleton: set of all known AI account IDs (loaded at startup) +``` + +`AiAccountRegistry` is a singleton loaded by `AiSeedStartupService` after seeding — it reads +all `IsAi = true` account IDs into a `HashSet` for O(1) lookups. Injected into +`GameEndTurnHandler` via `IAiAccountRegistry` interface (defined in `SOR.Networking.Abstractions` +or `SOR.Shared` to avoid a circular dependency from `SOR.Game` → `SOR.Ai`). + +**`AiPlayerSession.ExecuteTurnAsync`** (Phase 2.1 stub): +```csharp +internal async Task ExecuteTurnAsync(GameState state, CancellationToken ct) +{ + // Phase 2.1: immediately end turn (no decision logic yet) + await SubmitActionAsync("game.end_turn", new GameEndTurnRequest(SessionId), ct); +} +``` + +`SubmitActionAsync` constructs `AiAuthenticatedConnection` + `AiClientMessage`, resolves the +matching `IMessageHandler` from `IServiceProvider` (keyed by `msg.Type`), and calls +`handler.HandleAsync`. Handler resolution follows the same `MessageDispatcher` pattern already +used in `SOR.Gateway`. + +**`AiPlayerSessionManager`** subscribes to `AiTurnStartedEvent` via NATS and calls +`session.ExecuteTurnAsync` after a configurable base delay. + +**Done when**: in a human-vs-AI custom game, after the human ends their turn, the AI's turn +starts and immediately ends (AI passes). The human sees the state update and their turn resumes. +The game can reach game-over naturally when the human attacks the AI ArchSpirit to zero health. + +--- + +### Phase 2.2 — Placement Phase Handling + +**Goal**: Teach the AI to handle the `Placement` phase — specifically `game.place_arch_spirit`. +Without this the AI will never leave Placement and the game cannot begin. + +This is a discrete phase because placement has its own logic: the AI must pick a valid starting +coordinate in its placement zone, which is determined by `SeatIndex` and `GameRules`. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Engine/ + └── PlacementStrategy.cs — picks a valid arch-spirit placement coordinate +``` + +**`PlacementStrategy.SelectCoord(AiTurnContext ctx) → Coord`**: +- Reads `ctx.State.Board.StartingZones[aiSeatIndex]` +- For Phase 2.2 (novice behaviour): picks a random coordinate from the starting zone +- Later phases will have `HeuristicDecisionEngine` call this too, potentially picking + a coordinate that maximises affinity push toward the board center + +**`AiPlayerSession.ExecuteTurnAsync`** gains a phase check: +```csharp +if (state.Phase == GamePhase.Placement) +{ + var coord = PlacementStrategy.SelectCoord(ctx); + await SubmitActionAsync("game.place_arch_spirit", new GamePlaceArchSpiritRequest(SessionId, coord), ct); + return; +} +``` + +**Done when**: an AI seat progresses through Placement automatically and the board reaches +the Draw phase, at which point both human and AI have ArchSpirits on the board. + +--- + +### Phase 2.3 — Random Decision Engine (Difficulty 1) + +**Goal**: Implement `IAiDecisionEngine`, the `AiAction` discriminated union, `AiDifficultyProfile`, +and `RandomDecisionEngine`. After this phase Difficulty 1 AI plays a legal (but random) game. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Engine/ + ├── IAiDecisionEngine.cs — interface + AiAction hierarchy (records) + ├── AiDifficultyProfile.cs — record definition + ├── AiDifficultyProfiles.cs — static table of all 10 profiles + └── RandomDecisionEngine.cs — picks random legal action each step +``` + +**`IAiDecisionEngine`**: +```csharp +public interface IAiDecisionEngine +{ + IReadOnlyList ComputeTurn(AiTurnContext ctx); +} +``` + +`AiAction` discriminated union: `AiDrawAction`, `AiPlayCardAction`, `AiMoveAction`, +`AiAttackAction`, `AiActivateAbilityAction`, `AiSacrificeAction`, `AiAscendAction`, +`AiEndTurnAction`. + +**`RandomDecisionEngine`** loops: +1. Generate one random legal action (from any category) — or `AiEndTurnAction` if none exist +2. Append to plan +3. If action was `AiEndTurnAction` or SP/MP exhausted, stop + +**`AiPlayerSession`** selects engine based on `AiDifficultyProfiles.Get(difficulty).EngineType`. +For this phase only `"Random"` works; other engine types fall back to `RandomDecisionEngine`. + +**DI wiring**: +```csharp +services.AddTransient(); +``` + +Engines are resolved by `AiPlayerSession` directly from `IServiceProvider` (keyed by engine type +string from the profile). This avoids a factory abstraction we don't need yet. + +**Done when**: an AI on Difficulty 1 plays a full game from Placement to game-over (either the +human kills the AI ArchSpirit, the AI accidentally kills the human's, or turn limit is reached). +All actions are valid (no `GameException` thrown). + +--- + +### Phase 2.4 — Action Candidate Generator + +**Goal**: Build `ActionCandidateGenerator` — the component that enumerates every legal move +the AI can make from a given `GameState`. This is a pure function (no side effects, no DB), +reused by both the heuristic and MCTS engines. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Heuristics/ + └── ActionCandidateGenerator.cs +``` + +**Method signatures:** +```csharp +public static class ActionCandidateGenerator +{ + // All legal actions for the active player in the given state. + public static IReadOnlyList All(AiTurnContext ctx); + + // Channeling candidates only (play card to tile) + public static IReadOnlyList Channelings(AiTurnContext ctx); + + // Movement candidates for a specific unit + public static IReadOnlyList Movements(AiTurnContext ctx, string unitInstanceId); + + // Attack candidates for a specific unit + public static IReadOnlyList Attacks(AiTurnContext ctx, string unitInstanceId); + + // Ability candidates for a specific unit + public static IReadOnlyList Abilities(AiTurnContext ctx, string unitInstanceId); +} +``` + +Implementation delegates range/path/affinity logic back to `SOR.Game` modules directly — +`ChannelingRange`, `Pathfinding`, `AffinitySystem` — so no game rules are duplicated in `SOR.Ai`. + +**`AiTurnContext`** (from Phase 1.7) stores: +- `GameState State` +- `string AiAccountId` +- `PlayerState AiPlayer` (convenience: `State.Players[AiAccountId]`) +- `IReadOnlyList OpponentIds` +- `GameRules Rules` + +**Done when**: unit tests (xUnit, same test project pattern as existing `SOR.Game.Tests`) cover: +- Channeling with sufficient SP and matching affinity → produces candidates +- Channeling with insufficient SP → no candidates +- Movement with zero MP remaining → no candidates +- Attack out of range → not in candidates +- Ascend when next-tier ArchSpirit is in hand → ascend candidate present + +--- + +### Phase 2.5 — Heuristic Scoring & Decision Engine (Difficulties 2–5) + +**Goal**: Implement board evaluation and the greedy heuristic engine. After this phase, +Difficulties 2–5 play purposefully — they attack weak targets, defend the ArchSpirit, and +spend SP on cards that improve their board position. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Heuristics/ + ├── ScoringFunctions.cs — board evaluation: material, position, affinity, threat + ├── ThreatDetector.cs — which enemy units can reach own ArchSpirit next turn + └── HeuristicDecisionEngine.cs — greedy loop with mistake injection +``` + +**`ScoringFunctions.Evaluate(GameState state, string aiAccountId, AiDifficultyProfile profile) → float`** +uses the weighted formula defined in §5.2. Weights come from `profile`, allowing different +difficulties and strategies to push the AI toward different behaviours without changing code. + +**`HeuristicDecisionEngine.ComputeTurn(AiTurnContext ctx) → IReadOnlyList`**: +``` +1. Draw (always) +2. Greedy loop: + a. candidates = ActionCandidateGenerator.All(ctx) + b. for each candidate: score = ScoringFunctions.Evaluate(Simulate(state, candidate)) + c. best = argmax(score) + d. if best.score <= current score AND no mandatory actions remain: break + e. apply MistakeRate: with probability MistakeRate, replace best with random candidate + f. append best to plan; update ctx with simulated state +3. AiEndTurnAction +``` + +`Simulate(state, action)` calls `GameEngine.Draw / MoveUnit / Attack / ChannelCard` etc. +directly (same pure static methods — no DB, no side effects) to get the post-action state for +scoring. This is cheap: `GameEngine` is designed to be called this way. + +**`AiDifficultyProfiles`** now defines full profiles for 1–5: +- Difficulty 1: `EngineType = "Random"`, `MistakeRate = 1.0` +- Difficulty 2: `EngineType = "Heuristic"`, `MistakeRate = 0.60` +- Difficulty 3: `EngineType = "Heuristic"`, `MistakeRate = 0.40` +- Difficulty 4: `EngineType = "Heuristic"`, `MistakeRate = 0.25` +- Difficulty 5: `EngineType = "Heuristic"`, `MistakeRate = 0.10` + +Strategy weight overlays (Aggressive, Control, etc.) are applied on top of the difficulty profile +via `AiDifficultyProfile.WithStrategy(strategy)` — a `with`-expression that adjusts weights. + +**DI wiring**: +```csharp +services.AddTransient(); +``` + +**Done when**: manual playtesting confirms: +- Difficulty 2 AI makes obviously suboptimal moves ~half the time +- Difficulty 5 AI consistently attacks low-HP units first, channels Spirits to relevant affinity + tiles, and does not leave its ArchSpirit adjacent to enemy attackers without blocking +- Difficulty 5 AI wins > 60% of games against Difficulty 1 AI in a 100-game self-play run + (run via a temporary test harness calling `GameEngine` directly in a console test) + +--- + +### Phase 3.1 — AI Internal ELO Tracking + +**Goal**: Record win/loss outcomes for AI accounts in a separate `AiEloRecord` table. +This data is used for calibration in later phases and is never surfaced to players. + +**Migration**: create `AiEloRecord` table (see §11.2). + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Tracking/ + └── AiEloService.cs — records outcome, updates AiEloRecord after each AI game ends +``` + +**`AiEloService`** is called from `AiPlayerSessionManager` when it receives `GameEndedEvent`. +It identifies which participants were AI accounts, loads their `AiEloRecord`, applies the same +`GameEngine.ComputeEloDelta` formula used by `FinalizeGameAsync`, and saves. + +Note: AI accounts also go through `FinalizeGameAsync` for their human-facing `Account.RankScore` +(since the session uses their real account ID). The `AiEloRecord` is an **additional** private +tracker, not a replacement. AI `RankScore` on the `Account` table should be frozen at `0` +post-game — add a guard in `FinalizeGameAsync`: if `winner.IsAi || loser.IsAi`, skip the +`identityDb.SaveChangesAsync` ELO adjustment (human's ELO still updates normally). + +**DI wiring**: +```csharp +services.AddScoped(); +``` + +**Done when**: after an AI game completes, the `ai_elo_records` table has updated win/loss +counts and an adjusted internal ELO score for the AI account. + +--- + +### Phase 3.2 — Self-Play Runner + +**Goal**: Build an in-memory AI-vs-AI game runner for data generation and engine benchmarking. +Runs entirely via `GameEngine` static methods — no DB writes, no network, no handlers. Pure +computation. Used by Phase 3.3 (data export) and for validating engine improvements. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Training/ + └── SelfPlayRunner.cs — runs one in-memory AI-vs-AI game, returns outcome +``` + +**`SelfPlayRunner.RunGameAsync(AiDifficultyProfile p1, AiDifficultyProfile p2, GameRules rules) → SelfPlayResult`**: +1. Build two `AiTurnContext` instances with a shared `GameState` (initialized via `GameEngine.Initialize`) +2. Alternate turns: `decisionEngine.ComputeTurn(ctx)` → apply each action via `GameEngine.*` +3. After `GameEngine.EndTurn` returns `(state, gameOver: true)`, return `SelfPlayResult { WinnerSeat, TurnCount, FinalState }` +4. No delays, no DB, no NATS — pure CPU + +**`SelfPlayOrchestrator`** wraps this in a batch loop: +```csharp +public async Task RunBatchAsync(int numGames, int difficulty, CancellationToken ct) +``` +Runs games in parallel via `Task.WhenAll` (configurable concurrency limit). Reports +win counts, average turn counts, and game records for export. + +**Admin API** in `SOR.Admin`: +- `POST /admin/ai/self-play/start { numGames, difficulty }` — kicks off a background batch +- `GET /admin/ai/self-play/status` — returns progress (games completed / total, win rates) + +**Done when**: a 100-game self-play batch completes between two Difficulty 5 heuristic AIs +in under 30 seconds, with a win rate between 45–55% (roughly equal opponents), confirming +the runner produces valid complete games. + +--- + +### Phase 3.3 — Training Data Export + +**Goal**: Export human game replays and self-play results as structured JSONL, ready for +offline feature extraction and model training. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Training/ + ├── GameReplayExporter.cs — reads GameActionLog rows, emits training samples + ├── FeatureExtractor.cs — GameState → float[] feature vector + └── TrainingDataWriter.cs — writes JSONL to disk, one record per action taken +``` + +**`TrainingRecord`** (serialized to JSONL): +```csharp +public record TrainingRecord( + string SessionId, + string ActorId, + int TurnNumber, + string ActionType, + string ActionPayloadJson, + string StateFeaturesBase64, // FeatureExtractor output, base64-encoded float[] + int Outcome); // 1 = this actor won, 0 = lost +``` + +**`GameReplayExporter`** queries: +```sql +SELECT al.*, gs.winner_account_id +FROM game_action_logs al +JOIN game_sessions gs ON gs.id = al.game_session_id +WHERE gs.status = 'Completed' + AND gs.ended_at > @lastExportedAt + AND al.action_type NOT IN ('game.ready', 'game.concede') +ORDER BY al.game_session_id, al.sequence_number +``` + +For each row, it deserializes the state from `StateJson` (at that point in the log), calls +`FeatureExtractor.Extract`, and writes a `TrainingRecord`. + +**Admin API**: +- `POST /admin/ai/export-replays { sinceDate }` — triggers an export job +- Output path: configurable via `appsettings.json`, e.g. `"Ai:TrainingDataPath": "/data/training/"` + +**Done when**: calling the export API on a DB with at least 10 completed games produces a +valid `.jsonl` file where each line deserializes to a `TrainingRecord` and `StateFeaturesBase64` +decodes to a float array of length ~990. + +--- + +### Phase 3.4 — MCTS Engine (Difficulties 6–8) + +**Goal**: Implement Monte Carlo Tree Search and wire it as the engine for Difficulties 6–8. +This engine does lookahead — it should noticeably outperform the heuristic engine. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── MCTS/ + ├── MctsNode.cs — tree node (state, action, visits, wins) + ├── MctsTree.cs — UCB1 selection + expansion + backpropagation + ├── MctsSimulator.cs — random playout from a node using RandomDecisionEngine + ├── MctsEvaluator.cs — leaf-node board score (delegates to ScoringFunctions) + └── MonteCarloEngine.cs — IAiDecisionEngine implementation wrapping MctsTree +``` + +**`MonteCarloEngine.ComputeTurn(AiTurnContext ctx)`**: +``` +Given timeBudgetMs (from profile): + 1. Root = MctsNode(currentState) + 2. While elapsed < timeBudgetMs AND iterations < maxIterations: + a. node = Selection(root) — UCB1 traversal + b. child = Expansion(node) — pick unexplored candidate action + c. result = MctsSimulator.Playout(child.state, maxDepth) + d. BackPropagate(child, result) — increment visits and wins up to root + 3. bestChild = root.children.MaxBy(c => c.Visits) + 4. Return bestChild.Action + recurse into bestChild for multi-step plans +``` + +Simulation uses `SelfPlayRunner` internally (configured for max-speed random play). Because +`SelfPlayRunner` calls `GameEngine` directly, the playout is very fast — expect 100–500 +simulations per second per thread. + +**`AiDifficultyProfiles`** entries for 6–8: +- Difficulty 6: `EngineType = "MCTS"`, `MctsTimeBudgetMs = 500`, `MctsMaxDepth = 3` +- Difficulty 7: `EngineType = "MCTS"`, `MctsTimeBudgetMs = 1500`, `MctsMaxDepth = 5` +- Difficulty 8: `EngineType = "MCTS"`, `MctsTimeBudgetMs = 4000`, `MctsMaxDepth = 7` + +**DI wiring**: +```csharp +services.AddTransient(); +``` + +**Done when**: +- A 100-game self-play batch of MCTS-Difficulty-7 vs Heuristic-Difficulty-5 shows MCTS winning + > 70% of games, confirming meaningful lookahead improvement +- Per-turn latency for Difficulty 6 is < 600ms measured wall-clock (budget + overhead) + +--- + +### Phase 3.5 — AI Calibration Job + +**Goal**: Automated measurement of AI win rates across difficulty tiers to confirm the +calibration targets from §7.5 are being met. Admin-triggered; results stored for review. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Calibration/ + └── AiCalibrationJob.cs — runs cross-difficulty self-play batches, records results +``` + +**`AiCalibrationJob.RunAsync(CancellationToken ct)`**: +- Runs 50-game batches for each adjacent difficulty matchup (1v2, 2v3, ..., 7v8) +- Records win rates in a new `ai_calibration_runs` table (id, run_at, difficulty_a, difficulty_b, win_rate_a, game_count) +- Also runs the full heuristic difficulty ladder (1v5, 2v5, 3v5, 4v5) to confirm relative strength + +**Admin API**: +- `POST /admin/ai/calibrate` — triggers calibration job +- `GET /admin/ai/calibrate/history` — returns last N calibration run results + +**Done when**: calibration completes and the output shows monotonically increasing win rates +across the difficulty ladder (Difficulty 3 beats Difficulty 2 > 60% of games, etc.). + +--- + +### Phase 4.1 — Feature Extractor & Training Pipeline Validation + +**Goal**: Finalize `FeatureExtractor` (already stubbed in Phase 3.3) to produce a stable, +documented feature vector. Validate it against known game states before the Python training +pipeline is built against it. + +**Files to modify:** + +- `SOR.Ai/Training/FeatureExtractor.cs` — finalize all feature groups per §7.2, ensure + output length is constant regardless of board size variation (pad or truncate to fixed dims) + +**Files to create:** + +``` +Server/scripts/ai_training/ +├── requirements.txt — numpy, torch, pyarrow, onnx, onnxruntime +├── extract_features.py — reads JSONL from Phase 3.3, converts to Parquet +├── train.py — PyTorch training loop (policy + value heads) +├── export_onnx.py — exports best checkpoint to ONNX +└── benchmark.py — runs AiVsAi in ONNX mode, reports win rates +``` + +These are Python scripts committed to the repo under `Server/scripts/`. They are not part of +the .NET build. Documentation in `Server/scripts/ai_training/README.md` covers: +- Environment setup +- How to point scripts at exported JSONL data +- Expected training time per epoch +- How to validate the ONNX output shape matches what `NeuralDecisionEngine` expects + +**Done when**: `extract_features.py` reads a `.jsonl` file from Phase 3.3 and writes a +`.parquet` file; `train.py` runs at least 1 epoch without error and outputs a `.pt` checkpoint; +`export_onnx.py` produces an `.onnx` file with the expected input/output shape. + +--- + +### Phase 4.2 — Neural Decision Engine (Difficulties 9–10) + +**Goal**: Wire ONNX model inference into the server as `NeuralDecisionEngine`. This phase +requires a trained model from Phase 4.1 to be useful, but the code can be written and tested +with a randomly-initialized model first. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Engine/ + └── NeuralDecisionEngine.cs — IAiDecisionEngine wrapping OnnxRuntime inference +``` + +**`NeuralDecisionEngine`**: +- Loads `{AiTrainingDataPath}/models/sor-ai-v{N}.onnx` at construction +- `ComputeTurn(ctx)`: + 1. `float[] features = FeatureExtractor.Extract(ctx.State, ctx.AiAccountId)` + 2. Run ONNX session inference → `policyLogits[]`, `valueScore` + 3. Generate `ActionCandidateGenerator.All(ctx)` + 4. Map candidates to policy indices; take softmax + 5. Pick action with highest policy score where value doesn't drop below threshold + 6. Repeat until `AiEndTurnAction` + +**Hot-reload API**: +- `POST /admin/ai/reload-model { version: N }` — `NeuralDecisionEngine.ReloadModel(version)` + swaps the ONNX session without restart. Uses a read-write lock so in-flight turns complete + before the swap. + +**`AiDifficultyProfiles`** for 9–10: +- Difficulty 9: `EngineType = "Neural"`, inference timeout 200ms, fallback to MCTS-7 if model not loaded +- Difficulty 10: `EngineType = "Neural"`, beam search (top-3 policy candidates, pick highest value), 500ms + +**Package**: add `Microsoft.ML.OnnxRuntime` to `SOR.Ai.csproj` via `Directory.Packages.props` +(using the existing central package version management pattern). + +**DI wiring**: +```csharp +services.AddSingleton(); // singleton: ONNX session is expensive to load +``` + +**Done when**: `NeuralDecisionEngine` runs inference without exception (even with a +randomly-initialized model) and produces a legal sequence of `AiAction`s. The hot-reload API +swaps the model file and subsequent turns use the new model. + +--- + +### Phase 5.1 — Game-Over Handling & ELO Guard + +**Goal**: Ensure that when an AI is eliminated or the game ends, AI sessions are properly +cleaned up and AI ELO adjustments are skipped on the human-facing `Account.RankScore`. +Also handle the edge case where an AI is eliminated mid-game (FFA/team games). + +**Files to modify:** + +- `SOR.Game/Handlers/GameHandlerBase.cs` `FinalizeGameAsync` — add guard: + ```csharp + if (!winner.IsAi) { winner.RankScore += winnerDelta; } + if (!loser.IsAi) { loser.RankScore = Math.Max(0, loser.RankScore - loserDelta); } + ``` + Same guard for `FinalizeMultiPlayerGameAsync`. + OP rewards (`OriginPoints`) are also withheld for AI accounts (they never show a balance). + +- `SOR.Ai/Core/AiPlayerSessionManager.cs` — on `GameEndedEvent`, cancel all `AiPlayerSession` + CancellationTokens for that session and remove from the dictionary + +- `SOR.Game/Handlers/GameHandlerBase.cs` `PushStateToPlayersAsync` — AI player IDs should + **not** receive Redis push (they have no WebSocket subscriber). Add filter: + `allIds.Where(pid => !aiRegistry.IsAi(pid))` before pushing. This avoids wasted Redis + publishes to queues nobody reads. + +**Done when**: completing a human-vs-AI game does not change the AI account's `RankScore` +and does not trigger ELO/OP changes for the AI in the identity DB; the human's stats update +correctly; Redis push is not sent to the AI account ID. + +--- + +### Phase 5.2 — Triggered Ability Handling for AI + +**Goal**: Handle `game.ability.triggered_target_request` pushes for AI accounts. When an +ability fires that needs manual target selection, the push currently goes to the triggering +player's Redis channel — if that player is AI, nobody reads it and the game stalls. + +**Files to modify:** + +- `SOR.Game/Handlers/GameHandlerBase.cs` `PushStateToPlayersAsync` — after pushing the + `triggered_target_request`, check if `pending.ActorId` is an AI account. If so, instead + of pushing to Redis, call `AiTriggeredTargetResolver.ResolveAsync(pending, state, ct)` directly. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Engine/ + └── AiTriggeredTargetResolver.cs — picks targets for triggered abilities +``` + +**`AiTriggeredTargetResolver.ResolveAsync`** reads the pending action's target requirements +(from `PendingTriggeredTarget.ActionsJson`) and picks targets using the same heuristic scoring +as the main decision engine — prefer targets that maximize board score. Falls back to a random +valid target if scoring is too expensive. + +Submits the selection via `AiAuthenticatedConnection` + `game.triggered_target` message, +identical to how a human client would respond. + +**Done when**: a game where the AI has a card with a triggered target-selection ability +completes without stalling. Verify with a specific card/ability known to trigger this path. + +--- + +### Phase 5.3 — Adaptive Difficulty + +**Goal**: Allow the system to auto-suggest (or auto-adjust) AI difficulty based on a player's +recent win rate against AI, so new players aren't stuck on a difficulty that's too hard, and +veteran players aren't bored on one that's too easy. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Adaptive/ + └── AiDifficultyAdvisor.cs — computes recommended difficulty from recent game history +``` + +**`AiDifficultyAdvisor.GetRecommendedDifficultyAsync(Guid humanAccountId, CancellationToken ct) → int`**: +- Queries last 20 completed AI games for `humanAccountId` from `game_sessions` where any + participant `IsAi = true` +- Computes human win rate +- If win rate > 70%: recommend current + 1 (up to 10) +- If win rate < 30%: recommend current - 1 (down to 1) +- Otherwise: return current difficulty + +**Client API**: `GET /game/ai/recommended-difficulty` — returns `{ recommendedDifficulty: N }`. +Called by the client when the custom lobby AI configuration panel opens. + +**Done when**: a player who has won their last 15 AI games gets a `recommendedDifficulty` +higher than their last used difficulty; a player on a losing streak gets a lower recommendation. + +--- + +### Phase 5.4 — AI Personality & Lobby Display Polish + +**Goal**: Add display metadata (personality label, flavor text, avatar) to AI slots in the +custom lobby. This is purely presentational — no game logic changes. + +**Files to create:** + +``` +Server/src/SOR.Ai/ +└── Metadata/ + └── AiPersonalityMetadata.cs — static display data per strategy archetype +``` + +**`AiPersonalityMetadata`** is a static dictionary keyed by strategy name, providing: +- `string PersonalityLabel` — e.g. "The Relentless" (Aggressive), "The Architect" (Control) +- `string FlavorText` — 1-sentence description shown in lobby +- `string AvatarSlug` — key into asset server for an AI avatar image + +**New response field**: `GameAddAiResponse` gains `string PersonalityLabel`, `string FlavorText`, +`string AvatarSlug`. The client shows these in the AI slot card. + +**Done when**: adding an AI to a lobby returns personality metadata in the response; the custom +lobby screen (client-side, separate ticket) can display the AI's avatar and personality label. + +--- + +### Phase 5.5 — Counter-Deck Logic + +**Goal**: Allow the AI to pick a deck archetype that counters the human opponent's observed +ArchSpirit, rather than always using its static default deck. + +**Files to modify / create:** + +- `SOR.Ai/Lobby/AiSlotAssigner.cs` — when the human's deck is known (lobby `HostDeckId`), + load the human's ArchSpirit affinity. Apply counter-affinity logic: + - Fire ArchSpirit → prefer Water-control AI deck + - Water ArchSpirit → prefer Nature-ramp AI deck + - etc. (full matrix defined in `CounterAffinityMatrix.cs`) + +- `SOR.Ai/Lobby/CounterAffinityMatrix.cs` — static `Affinity → Affinity[]` mapping (preferred + counter affinities in priority order) + +`AiSlotAssigner.Assign` now takes an optional `Affinity? opponentAffinity` parameter. When +provided, it queries for AI accounts whose deck's ArchSpirit affinity appears in the counter list +for that opponent affinity. + +**Done when**: adding an AI to a lobby where the host has a Fire-affinity ArchSpirit deck +causes the AI account selected to have a Water-affinity deck (or the closest available match). + +--- + +## Phase Summary + +| Phase | Track | Goal | Key Deliverable | +|---|---|---|---| +| 1.1 | A | Scaffold | `SOR.Ai.csproj` builds, wired into Host | +| 1.2 | A | Transport | `AiAuthenticatedConnection`, `AiClientMessage` | +| 1.3 | A | DB Schema | Migrations for `IsAi`, `AiSlotsJson` | +| 1.4 | A | AI Accounts | 50 seeded AI accounts at startup | +| 1.5 | A | AI Decks | Pre-built decks for every AI account | +| 1.6 | A | Lobby Handlers | Host can add/remove/configure AI in lobby | +| 1.7 | A | Session Manager | AI auto-sends `game.ready`, sessions tracked | +| 2.1 | B | Turn Pipeline | AI takes turns (immediately end-turns) | +| 2.2 | B | Placement | AI places ArchSpirit in Placement phase | +| 2.3 | B | Random Engine | Difficulty 1 plays legal random game end-to-end | +| 2.4 | B | Candidate Gen | All legal moves enumerated, unit tested | +| 2.5 | B | Heuristic Engine | Difficulties 2–5 play purposeful games | +| 3.1 | C | AI ELO | Internal ELO tracked for AI accounts | +| 3.2 | C | Self-Play | In-memory AI-vs-AI runner, admin API | +| 3.3 | C | Data Export | Replay JSONL export for training pipeline | +| 3.4 | C | MCTS Engine | Difficulties 6–8 with lookahead | +| 3.5 | C | Calibration | Automated win-rate calibration across difficulty tiers | +| 4.1 | D | Feature Extractor | Python training scripts, validated feature vector | +| 4.2 | D | Neural Engine | ONNX inference for Difficulties 9–10 | +| 5.1 | E | ELO Guard | AI ELO/OP excluded from human-facing records | +| 5.2 | E | Triggered Targets | AI resolves ability target-selection without stalling | +| 5.3 | E | Adaptive Difficulty | Recommended difficulty API | +| 5.4 | E | Personality | Display metadata, avatars, flavor text | +| 5.5 | E | Counter-Deck | AI selects counter-affinity deck vs human | + +--- + +## Key Design Decisions & Rationale + +| Decision | Rationale | +|---|---| +| AI goes through full handler pipeline | Ensures AI actions are fully validated, logged, and pushed to humans exactly as human actions are. No code duplication, no drift. | +| AI accounts are real DB rows | Allows lobby, session, and replay systems to work unmodified. AI is a player, not a special case. | +| Heuristic engine first | Fastest path to a playable feature. Gives training data. MCTS and Neural can replace it later with no API changes. | +| ONNX Runtime for inference | Train in Python (PyTorch ecosystem, mature ML tooling), run in .NET (production server). Standard interop pattern. | +| Self-play for training data | Human game data is sparse and biased toward popular strategies. Self-play explores the full strategy space faster. | +| In-process action submission | No network hop, no extra infra. AI turn latency is controlled purely by think-time delay, not transport. | +| Per-strategy deck seeding | Strategy is only meaningful if the AI's deck supports it. A control AI with an aggro deck would play incoherently. | +| Mistake injection for difficulty | Easier to implement and tune than reducing search depth for Heuristic AI. More realistic too — low-skill AIs play wrong, not just slowly. |