- 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>
79 KiB
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
- Project Structure
- Integration Points
- AI Account Model
- Game Flow — How AI Joins & Plays
- Decision Engine Architecture
- Difficulty System
- Training & Improvement Strategy
- Deck Composition for AI
- Multi-Player & Team AI
- New Message Types
- Database Schema Additions
- 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
AiEloRecordtable (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):
GameSessionis created with AI accounts in their seats (no change to existing code).AiPlayerSessionManager.OnGameSessionCreatedis called.- Manager creates an
AiPlayerSessionfor each AI seat in that session. - AI seats automatically send
game.readyafter 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
GameSessionrows have a fullActionLog(sequence of actions + states) GameReplayExporterconverts 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
SelfPlayOrchestratorrunsAiVsAiGameSessionbatches (no network, no DB needed — pureGameEnginecalls)- 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
- Cold start: run heuristic self-play (D5) to generate initial data; train first model.
- Deploy model and enable D9-D10 in calibration runs.
- D9/D10 self-play generates higher-quality data than heuristic rollouts.
- Append new export to JSONL; retrain with more epochs.
- 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— addSOR.Aiproject entryServer/src/SOR.Host/SOR.Host.csproj— add<ProjectReference>toSOR.AiServer/src/SOR.Host/Program.cs— callbuilder.Services.AddAiService(builder.Configuration)immediately afterAddGameService, guarded by the sameENABLED_SERVICEScheck 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 forIsAiinOnModelCreating -
Server/src/SOR.Database/Entities/Game/CustomLobby.cs— addpublic 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 = trueAiDifficulty/AiStrategysetUsername= 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 cardsAggressive— cheap Spirits, attack-range units, Repentance damage spellsControl— Terramorpha + high-defense Spirits, few attacksRamp— Sacrifice-heavy Spirits, high-cost powerful late-game cardsSwarm— 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 IDIsValid = 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
OpenorFull(notStartedorCompleted) - 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 SessionIdGuid AiAccountIdint Difficulty,string Strategyint SeatIndexCancellationTokenSource SessionCts— cancelled when game ends
AiPlayerSessionManager is a BackgroundService that:
- Subscribes to NATS subject
NatsSubjects.GameStarted(the same eventSOR.Matchmakingalready publishes when any game starts — including custom lobby games) - On
GameStartedEvent, loads theGameSessionfrom DB and inspectsAdditionalPlayersJsonplusGuestAccountId/PlayerOneAccountIdto identify any seats whose account hasIsAi = true - Creates one
AiPlayerSessionper AI seat and stores it in aConcurrentDictionary<Guid, List<AiPlayerSession>> - Subscribes to NATS subject
NatsSubjects.GameEndedand 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— addpublic const string AiTurnStarted = "sor.game.ai_turn_started";SOR.Game/Handlers/GameEndTurnHandler.cs— after advancing the turn, if the newstate.ActivePlayerAccountIdis an AI account (check viaIEventBus— publishAiTurnStartedEvent { SessionId, AiAccountId, TurnNumber }). The check is done by looking up whetheractivePlayerIdappears in a locally-injectedIAiAccountRegistry(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
HeuristicDecisionEnginecall 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:
- Generate one random legal action (from any category) — or
AiEndTurnActionif none exist - Append to plan
- If action was
AiEndTurnActionor 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 Statestring AiAccountIdPlayerState AiPlayer(convenience:State.Players[AiAccountId])IReadOnlyList<string> OpponentIdsGameRules 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
GameEnginedirectly 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:
- Build two
AiTurnContextinstances with a sharedGameState(initialized viaGameEngine.Initialize) - Alternate turns:
decisionEngine.ComputeTurn(ctx)→ apply each action viaGameEngine.* - After
GameEngine.EndTurnreturns(state, gameOver: true), returnSelfPlayResult { WinnerSeat, TurnCount, FinalState } - 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 batchGET /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_runstable (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 jobGET /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
NeuralDecisionEngineexpects
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}.onnxat construction ComputeTurn(ctx):float[] features = FeatureExtractor.Extract(ctx.State, ctx.AiAccountId)- Run ONNX session inference →
policyLogits[],valueScore - Generate
ActionCandidateGenerator.All(ctx) - Map candidates to policy indices; take softmax
- Pick action with highest policy score where value doesn't drop below threshold
- 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.csFinalizeGameAsync— 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— onGameEndedEvent, cancel allAiPlayerSessionCancellationTokens for that session and remove from the dictionary -
SOR.Game/Handlers/GameHandlerBase.csPushStateToPlayersAsync— 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.csPushStateToPlayersAsync— after pushing thetriggered_target_request, check ifpending.ActorIdis an AI account. If so, instead of pushing to Redis, callAiTriggeredTargetResolver.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
humanAccountIdfromgame_sessionswhere any participantIsAi = 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 lobbystring 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 (lobbyHostDeckId), 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— staticAffinity → 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— addActiveAbilities(ctx)method that iteratesaiPlayer.Field, checks each unitsAbilitieslist forCanActivate == trueandCurrentCooldown == 0, and yieldsAiActivateAbilityAction(unitInstanceId, abilityIndex)`SOR.Ai/Heuristics/HeuristicDecisionEngine.cs— addAiActivateAbilityActioncase toApplyActioncallingGameEngine.ActivateAbilitySOR.Ai/Training/SelfPlayRunner.cs— sameApplyActionextension
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 agame.target_requiredpush and respond withAiTargetSelectionActionSOR.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 aSelectTargetmethod 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 typegame.ai.recommended_difficulty; returns difficulty 1-10 based onAccount.RankScoremapped against calibration win-rate data inai_calibration_runsSOR.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 keySOR.Ai/Handlers/GameAddAiHandler.cs— include personality fields inGameAddAiResponseandCustomLobbyAiSlotsChangedPush- 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) — staticAffinity -> Affinity[]mapping (preferred counter affinities in priority order for each affinity)SOR.Ai/Lobby/AiSlotAssigner.cs— addopponentAffinityparameter; prefer AI accounts whose active deck`s ArchSpirit affinity appears in the counter listSOR.Ai/Handlers/GameAddAiHandler.cs— resolve hosts deck affinity fromCollectionDb, pass toAiSlotAssigner`
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):
- Run
AiCalibrationJob.RunAllPairsAsyncwithgameCount = 500per pair. - Export training data from admin portal to
/var/sor/training/data.jsonl. - Train:
python tools/train_neural.py --data data.jsonl --out model-v1.onnx --epochs 100 - Copy
model-v1.onnxto path configured inAi:NeuralModelPath. - Admin -> AI -> Neural Model -> Hot-swap Model.
- 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. |