Files
sor/Server/docs/SOR.Ai-Architecture-Plan.md
T
955a44725c docs: update AI architecture plan with current status and training guide
- Phase Summary table: mark phases 1.1-4.4 as done (added 4.3 training
  pipeline and 4.4 client UI); mark 5.1-5.6 as TODO with status column
- Section 7.3: replace placeholder model spec with actual implemented
  ValueNet MLP (1024->512->256->128->1 tanh, ~920k params, ONNX contract)
- Section 7.4: replace stub pipeline with actual How to Train the AI
  guide (self-play -> export -> train_neural.py -> hot-swap); includes
  CLI flags table and iterative improvement workflow
- New section: Remaining Work (Phases 5.x) with full implementation
  detail for each pending phase: active abilities (5.1), triggered
  target selection (5.2), adaptive difficulty API (5.3), personality
  & display (5.4), counter-deck selection (5.5), initial model
  operational runbook (5.6)

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
2026-04-12 22:11:31 -04:00

79 KiB
Raw Blame History

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
  2. Integration Points
  3. AI Account Model
  4. Game Flow — How AI Joins & Plays
  5. Decision Engine Architecture
  6. Difficulty System
  7. Training & Improvement Strategy
  8. Deck Composition for AI
  9. Multi-Player & Team AI
  10. New Message Types
  11. Database Schema Additions
  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):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\SOR.Database\SOR.Database.csproj" />
    <ProjectReference Include="..\SOR.Game\SOR.Game.csproj" />
    <ProjectReference Include="..\SOR.Networking.Abstractions\SOR.Networking.Abstractions.csproj" />
    <ProjectReference Include="..\SOR.Shared\SOR.Shared.csproj" />
  </ItemGroup>
</Project>

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):

// Conceptual: AI calling GameDrawHandler directly
var fakeConn = new AiAuthenticatedConnection(aiAccountId, sessionId);
var fakeMsg  = new AiClientMessage("game.draw", seq: 0, payload: Array.Empty<byte>());
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

public interface IAiDecisionEngine
{
    /// <summary>
    /// 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.
    /// </summary>
    IReadOnlyList<AiAction> ComputeTurn(AiTurnContext ctx);
}

public abstract record AiAction;
public record AiDrawAction : AiAction;
public record AiPlayCardAction(string CardInstanceId, Coord TargetTile,
                                IReadOnlyList<string> 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<AiAbilityTarget> 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

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.

// 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 (implemented)

A value network MLP in tools/train_neural.py:

Input:   1024 floats  (FeatureExtractor vector)
Dense:   1024 -> 512   + LayerNorm + ReLU + Dropout(0.2)
Dense:    512 -> 256   + LayerNorm + ReLU + Dropout(0.2)
Dense:    256 -> 128   + LayerNorm + ReLU
Output:   128 ->   1   + Tanh  =>  score in [-1, 1]
  • +1.0 = acting player won; -1.0 = acting player lost
  • Loss: MSELoss on outcome. Optimizer: AdamW + cosine LR annealing, gradient clip 1.0
  • Best checkpoint (lowest val loss) restored before ONNX export
  • ~920k parameters

ONNX contract (must match NeuralModelRegistry constants InputName/OutputName):

Property Value
Input tensor name features
Input shape [1, 1024] float32
Output tensor name score
Output shape [1, 1] float32
Output range [-1, 1] via tanh

7.4 How to Train the AI

See tools/README.md for the complete step-by-step workflow. Summary below.

Step 1 - Generate self-play data

In the admin portal, go to AI -> Calibration and click Run All Pairs. This triggers in-process AI vs AI games (no network, no delays) across all difficulty pairs. The resulting GameSession rows are the training data source.

Alternatively run a specific difficulty pair to generate targeted data faster:

POST /admin/ai/calibration/run-pair { difficultyA: 7, difficultyB: 8, gameCount: 200 }

Step 2 - Export training data

In the admin portal, go to AI -> Calibration and click Export Training Data. Enter an output path on the server, e.g. /var/sor/training/data.jsonl.

GameReplayExporter replays each completed session action-by-action and writes one JSON line per action:

{
  GameSessionId: 3fa85f64...,
  TurnNumber: 5,
  ActorAccountId: ...,
  Features: [0.0, 1.0, ...],
  ActionType: AiPlayCardAction,
  ActionJson: {},
  Outcome: 1.0
}

Outcome is +1.0 if the acting player won, -1.0 if they lost.

Step 3 - Train the model

Install dependencies (Python 3.11+):

pip install -r tools/requirements.txt

Run training:

python tools/train_neural.py     --data /var/sor/training/data.jsonl     --out  /var/sor/models/model.onnx     --epochs 50     --batch-size 512     --lr 1e-3

Key options:

Flag Default Description
--epochs 50 Training epochs
--batch-size 512 Mini-batch size
--lr 0.001 AdamW learning rate
--val-split 0.1 Validation fraction
--dropout 0.2 Dropout probability
--cpu off Force CPU (ignores CUDA)

The script prints per-epoch train/val loss, marks best checkpoint with *, restores best weights before export, and runs a quick onnxruntime validation of the exported file.

Step 4 - Deploy

1. Copy model.onnx to the path configured in appsettings: Ai:NeuralModelPath
2. Admin -> AI -> Neural Model -> Hot-swap Model

No restart required. The old ONNX InferenceSession is disposed atomically. Tiers 9-10 use the new model for all subsequent decisions. If no model file exists, tiers 9-10 fall back to heuristic scoring transparently.

Iterative improvement

  1. Cold start: run heuristic self-play (D5) to generate initial data; train first model.
  2. Deploy model and enable D9-D10 in calibration runs.
  3. D9/D10 self-play generates higher-quality data than heuristic rollouts.
  4. Append new export to JSONL; retrain with more epochs.
  5. Monitor admin calibration win-rates after each deployment; adjust difficulty profiles if needed.

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:

// 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<AiSlotInfo> 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

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:

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):

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:

ALTER TABLE custom_lobbies ADD COLUMN ai_slots_json JSONB NULL;

AiSlotsJson is an array of:

[
  { "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", <TargetFramework>net8.0</TargetFramework>
  • <FrameworkReference Include="Microsoft.AspNetCore.App" />
  • Project references: SOR.Database, SOR.Game, SOR.Networking.Abstractions, SOR.Shared

ServiceRegistration.cs:

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 <ProjectReference> 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<byte> 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:

    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:

// 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):

// Register as IHostedService so it runs once at startup before traffic is accepted
services.AddHostedService<AiSeedStartupService>();

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:

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<AiSlotInfo> 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:

services.AddTransient<IMessageHandler, GameAddAiHandler>();
services.AddTransient<IMessageHandler, GameRemoveAiHandler>();
services.AddTransient<IMessageHandler, GameConfigureAiHandler>();
services.AddScoped<AiSlotAssigner>();
services.AddScoped<AiLobbyService>();

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<Guid, List<AiPlayerSession>>
  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:

services.AddSingleton<AiPlayerSessionManager>();
services.AddHostedService(sp => sp.GetRequiredService<AiPlayerSessionManager>());

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<string> 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):

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:

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:

public interface IAiDecisionEngine
{
    IReadOnlyList<AiAction> 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:

services.AddTransient<RandomDecisionEngine>();

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:

public static class ActionCandidateGenerator
{
    // All legal actions for the active player in the given state.
    public static IReadOnlyList<AiAction> All(AiTurnContext ctx);

    // Channeling candidates only (play card to tile)
    public static IReadOnlyList<AiPlayCardAction> Channelings(AiTurnContext ctx);

    // Movement candidates for a specific unit
    public static IReadOnlyList<AiMoveAction> Movements(AiTurnContext ctx, string unitInstanceId);

    // Attack candidates for a specific unit
    public static IReadOnlyList<AiAttackAction> Attacks(AiTurnContext ctx, string unitInstanceId);

    // Ability candidates for a specific unit
    public static IReadOnlyList<AiActivateAbilityAction> 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<string> 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<AiAction>:

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:

services.AddTransient<HeuristicDecisionEngine>();

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:

services.AddScoped<AiEloService>();

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:

public async Task<SelfPlayBatchResult> 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):

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:

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:

services.AddTransient<MonteCarloEngine>();

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:

services.AddSingleton<NeuralDecisionEngine>(); // 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 AiActions. 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:

    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 Status Goal Key Deliverable
1.1 A done Scaffold SOR.Ai.csproj builds, wired into Host
1.2 A done Transport AiAuthenticatedConnection, AiClientMessage
1.3 A done DB Schema Migrations for IsAi, AiSlotsJson, ai_elo_records, ai_calibration_runs, ai_deck_assignments
1.4 A done AI Accounts 50 seeded AI accounts at startup (10 tiers x 5 strategies)
1.5 A done AI Decks Resolved dynamically from prebuilt starter decks; admin deck-per-difficulty config
1.6 A done Lobby Handlers Host can add/remove/configure AI in lobby (server handlers + client UI)
1.7 A done Session Manager AI auto-sends game.ready, sessions tracked
2.1 B done Turn Pipeline AI takes turns end-to-end
2.2 B done Placement AI places ArchSpirit in Placement phase
2.3 B done Random Engine Difficulty 1 plays legal random game end-to-end
2.4 B done Candidate Gen All legal moves enumerated (draw/channel/move/attack/sacrifice/ascend)
2.5 B done Heuristic Engine Difficulties 2-5 with weighted scoring and mistake injection
3.1 C done AI ELO Separate ai_elo_records table; FinalizeGameAsync guards with IsAi
3.2 C done Self-Play In-process SelfPlayOrchestrator, admin calibration page
3.3 C done Data Export GameReplayExporter writes JSONL; admin export UI
3.4 C done MCTS Engine UCT tree search for Difficulties 6-8 (2-4s budget)
3.5 C done Calibration AiCalibrationJob pairwise runs; ai_calibration_runs table
4.1 D done Feature Extractor FeatureExtractor 1024-float vector; matches Python training contract
4.2 D done Neural Engine NeuralDecisionEngine MCTS + ONNX leaf eval; hot-swap via admin
4.3 D done Training Pipeline tools/train_neural.py PyTorch MLP -> ONNX; tools/README.md workflow docs
4.4 A done Client AI UI Lobby Add AI Opponent button with difficulty (D1-D10) and strategy picker
5.1 E TODO Active Abilities AI generates AiActivateAbilityAction candidates and executes active abilities
5.2 E TODO Triggered Targets AI resolves ability target-selection without stalling
5.3 E TODO Adaptive Difficulty Recommended difficulty API based on human ELO rank
5.4 E TODO Personality Display metadata, avatars, flavor text per strategy archetype
5.5 E TODO Counter-Deck AI selects counter-affinity deck vs human opponent
5.6 E TODO Trained Model Run self-play -> export -> train cycle to produce initial model.onnx for D9-D10


Remaining Work (Phases 5.x)

The following phases are not yet implemented. They are ordered by recommended priority.


Phase 5.1 — Active Ability Support

Gap: ActionCandidateGenerator does not generate AiActivateAbilityAction candidates. The action type is defined in IAiDecisionEngine.cs but never produced, so the AI never uses unit active abilities regardless of difficulty.

Files to create/modify:

  • SOR.Ai/Heuristics/ActionCandidateGenerator.cs — add ActiveAbilities(ctx) method that iterates aiPlayer.Field, checks each units Abilitieslist forCanActivate == trueandCurrentCooldown == 0, and yields AiActivateAbilityAction(unitInstanceId, abilityIndex)`
  • SOR.Ai/Heuristics/HeuristicDecisionEngine.cs — add AiActivateAbilityAction case to ApplyAction calling GameEngine.ActivateAbility
  • SOR.Ai/Training/SelfPlayRunner.cs — same ApplyAction extension

Done when: a unit with a 0-cooldown active ability uses it during AI turns.


Phase 5.2 — Triggered Target Selection

Gap: Some game effects require target selection mid-turn (triggered abilities, on-play effects with target prompts). The current AI pipeline submits the initial action but has no mechanism to respond to a follow-up target-selection request from the server.

Files to create/modify:

  • SOR.Ai/Core/AiPlayerSession.cs — after submitting each action, check for a game.target_required push and respond with AiTargetSelectionAction
  • SOR.Ai/Heuristics/TargetSelector.cs (new) — given a list of valid target candidates, pick the best target using heuristic scoring (prefer highest-threat enemy, prefer own lowest-HP unit for healing, etc.)
  • SOR.Ai/Engine/IAiDecisionEngine.cs — optionally extend with a SelectTarget method so MCTS/Neural engines can participate in target selection

Done when: an AI playing a card that requires target selection completes the full play-then-target flow without stalling the game.


Phase 5.3 — Adaptive Difficulty API

Goal: expose an endpoint that recommends a difficulty tier for a new human player based on their ELO rank, so the client can suggest an appropriate starting difficulty.

Files to create/modify:

  • SOR.Ai/Handlers/GetRecommendedDifficultyHandler.cs (new) — message type game.ai.recommended_difficulty; returns difficulty 1-10 based on Account.RankScore mapped against calibration win-rate data in ai_calibration_runs
  • SOR.Admin/Components/Pages/Ai/AiCalibrationPage.razor — display recommended-difficulty mapping table derived from calibration results

Done when: a player with ELO 1400 gets recommended D5-D6; a player with ELO 800 gets D2-D3.


Phase 5.4 — AI Personality & Display

Goal: give each AI strategy archetype a display name, avatar, and flavor text so they feel like distinct opponents rather than Balanced AI (Adept).

Files to create/modify:

  • SOR.Ai/Seeding/AiPersonality.cs (new) — static record per (difficulty, strategy): display name, short bio, avatar asset key
  • SOR.Ai/Handlers/GameAddAiHandler.cs — include personality fields in GameAddAiResponse and CustomLobbyAiSlotsChangedPush
  • Client lobby_room_screen.gd — render avatar + bio in guest slot when AI is present
  • SOR.Admin/Components/Pages/Ai/AiEloPage.razor — show avatar next to AI ELO rows

Done when: each of the 50 AI accounts has a distinct portrait visible in the lobby room.


Phase 5.5 — Counter-Deck Selection

Goal: when a host adds an AI opponent, automatically select an AI account whose deck affinity counters the host`s ArchSpirit affinity, making the AI a more interesting opponent.

Files to create/modify:

  • SOR.Ai/Lobby/CounterAffinityMatrix.cs (new) — static Affinity -> Affinity[] mapping (preferred counter affinities in priority order for each affinity)
  • SOR.Ai/Lobby/AiSlotAssigner.cs — add opponentAffinity parameter; prefer AI accounts whose active deck`s ArchSpirit affinity appears in the counter list
  • SOR.Ai/Handlers/GameAddAiHandler.cs — resolve hosts deck affinity from CollectionDb, pass to AiSlotAssigner`

Done when: adding an AI to a lobby where the host has a Fire-affinity deck causes the AI to select a Water-affinity account.


Phase 5.6 — Initial Trained Model

Goal: produce and deploy the first real model.onnx so D9-D10 use neural evaluation instead of the heuristic fallback.

Steps (not a code change — operational work):

  1. Run AiCalibrationJob.RunAllPairsAsync with gameCount = 500 per pair.
  2. Export training data from admin portal to /var/sor/training/data.jsonl.
  3. Train: python tools/train_neural.py --data data.jsonl --out model-v1.onnx --epochs 100
  4. Copy model-v1.onnx to path configured in Ai:NeuralModelPath.
  5. Admin -> AI -> Neural Model -> Hot-swap Model.
  6. Run calibration again; confirm D9 win rate vs D8 > 60%.

Done when: admin neural model page shows Loaded and D9/D10 calibration win rates are measurably higher than D8.


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.