diff --git a/Server/src/SOR.Ai/Core/AiPlayerSession.cs b/Server/src/SOR.Ai/Core/AiPlayerSession.cs
index 52ac71c..2e5e0b3 100644
--- a/Server/src/SOR.Ai/Core/AiPlayerSession.cs
+++ b/Server/src/SOR.Ai/Core/AiPlayerSession.cs
@@ -3,9 +3,11 @@ namespace SOR.Ai.Core;
using System.Text.Json;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
+using SOR.Ai.Engine;
+using SOR.Ai.Heuristics;
using SOR.Ai.Transport;
using SOR.Database.Enums; // GamePhase
-using SOR.Game; // GameState
+using SOR.Game; // GameState, GameEngine, game request records
using SOR.Networking.Abstractions.Messaging;
using SOR.Networking.Abstractions.Transport;
@@ -14,10 +16,11 @@ using SOR.Networking.Abstractions.Transport;
///
/// Responsibilities:
/// - Submits game.ready at startup so the game can begin.
-/// - Executes the AI's turn when AiPlayerSessionManager signals it.
+/// - Executes the AI's full turn when AiPlayerSessionManager signals it.
///
-/// Phase 1 stub: ExecuteTurnAsync immediately ends the turn (pass).
-/// Later phases add decision logic.
+/// Phase 1: placed ArchSpirit randomly; ended turn immediately.
+/// Phase 2: selects a decision engine based on Difficulty, computes a full
+/// action plan, and submits each action with human-like timing delays.
///
internal sealed class AiPlayerSession : IAsyncDisposable
{
@@ -49,61 +52,94 @@ internal sealed class AiPlayerSession : IAsyncDisposable
_logger = logger;
}
+ // ── Public API ────────────────────────────────────────────────────────────
+
///
/// Sends game.ready on behalf of the AI after a short humanizing delay.
/// Called once when the game session is detected by AiPlayerSessionManager.
///
public async Task SendReadyAsync(CancellationToken appCt)
{
- using var ct = CancellationTokenSource.CreateLinkedTokenSource(appCt, _sessionCts.Token);
+ using var cts = CancellationTokenSource.CreateLinkedTokenSource(appCt, _sessionCts.Token);
+ var ct = cts.Token;
- // Short random delay before sending ready — feels more natural.
- await Task.Delay(Random.Shared.Next(300, 900), ct.Token);
+ await Task.Delay(Random.Shared.Next(300, 900), ct);
_logger.LogDebug("AI {Account} sending game.ready for session {Session}.",
AiAccountId, SessionId);
await InvokeHandlerAsync("game.ready",
JsonSerializer.SerializeToUtf8Bytes(new { SessionId }),
- ct.Token);
+ ct);
}
///
/// Executes the AI's full turn.
- /// Phase 1 stub: end turn immediately (AI passes).
+ ///
+ /// Selects the decision engine based on the difficulty profile, computes
+ /// an action plan, then submits each action with human-like delays.
+ /// Placement phase is handled separately (random coord from starting zone).
///
public async Task ExecuteTurnAsync(GameState state, CancellationToken appCt)
{
using var cts = CancellationTokenSource.CreateLinkedTokenSource(appCt, _sessionCts.Token);
- var ct = cts.Token;
+ var ct = cts.Token;
_logger.LogDebug(
"AI {Account} (seat {Seat}) taking turn {Turn} in session {Session}.",
AiAccountId, SeatIndex, state.TurnNumber, SessionId);
- // Handle Placement phase separately — must place ArchSpirit before main turn.
+ // Placement phase: place ArchSpirit before everything else.
if (state.Phase == GamePhase.Placement)
{
await ExecutePlacementAsync(state, ct);
return;
}
- // Phase 1 stub: immediately end turn with a short simulated delay.
- await Task.Delay(Random.Shared.Next(800, 2000), ct);
+ // Resolve difficulty profile + strategy overlay.
+ var profile = AiDifficultyProfiles.Get(Difficulty).WithStrategy(Strategy);
- _logger.LogDebug(
- "AI {Account} ending turn (stub — no decision logic yet).",
- AiAccountId);
+ // Think delay (before first action).
+ await Task.Delay(
+ Random.Shared.Next(profile.MinThinkTimeMs, profile.MaxThinkTimeMs + 1), ct);
- await InvokeHandlerAsync("game.end_turn",
- JsonSerializer.SerializeToUtf8Bytes(new { SessionId }),
- ct);
+ // Compute action plan.
+ var ctx = new AiTurnContext(state, AiAccountId);
+ var engine = ResolveEngine(profile);
+ IReadOnlyList plan;
+ try
+ {
+ plan = engine.ComputeTurn(ctx);
+ }
+ catch (Exception ex)
+ {
+ _logger.LogWarning(ex, "AI {Account}: decision engine threw — falling back to pass.", AiAccountId);
+ plan = [new AiEndTurnAction()];
+ }
+
+ _logger.LogDebug("AI {Account} turn plan: {Count} action(s).", AiAccountId, plan.Count);
+
+ // Submit each action with delays.
+ foreach (var action in plan)
+ {
+ ct.ThrowIfCancellationRequested();
+
+ var (msgType, payload) = ActionToMessage(action);
+ if (msgType is null) continue;
+
+ await InvokeHandlerAsync(msgType, payload, ct);
+
+ // Small delay between sequential actions (except after EndTurn).
+ if (action is not AiEndTurnAction)
+ {
+ await Task.Delay(
+ Random.Shared.Next(profile.MinActionDelayMs, profile.MaxActionDelayMs + 1), ct);
+ }
+ }
}
- ///
- /// Places the AI's ArchSpirit on a random valid tile in its starting zone.
- /// Called during the Placement phase.
- ///
+ // ── Placement ─────────────────────────────────────────────────────────────
+
private async Task ExecutePlacementAsync(GameState state, CancellationToken ct)
{
if (!state.Players.ContainsKey(AiAccountId))
@@ -112,7 +148,6 @@ internal sealed class AiPlayerSession : IAsyncDisposable
return;
}
- // Pick a random coord from the starting zone for this seat.
if (state.Board is null ||
!state.Board.StartingZones.TryGetValue(SeatIndex, out var zone) ||
zone.Count == 0)
@@ -137,18 +172,82 @@ internal sealed class AiPlayerSession : IAsyncDisposable
ct);
}
+ // ── Engine selection ──────────────────────────────────────────────────────
+
+ private static IAiDecisionEngine ResolveEngine(AiDifficultyProfile profile) =>
+ profile.EngineType switch
+ {
+ "Heuristic" => new HeuristicDecisionEngine(profile),
+ _ => new RandomDecisionEngine(), // "Random" + any future unknown
+ };
+
+ // ── Action → message mapping ──────────────────────────────────────────────
+
+ ///
+ /// Maps an AiAction to the game message type and JSON payload.
+ /// Returns (null, null) for actions that don't produce a message (e.g., internal guards).
+ ///
+ private (string? msgType, ReadOnlyMemory payload) ActionToMessage(AiAction action)
+ {
+ return action switch
+ {
+ AiDrawAction =>
+ Msg("game.draw", new GameDrawRequest(SessionId)),
+
+ AiPlayCardAction play => play.TargetTiles.Count switch
+ {
+ 0 => Msg("game.play_card",
+ new GamePlayCardRequest(SessionId, play.CardInstanceId)),
+ 1 => Msg("game.play_card",
+ new GamePlayCardRequest(SessionId, play.CardInstanceId,
+ TargetTile: new CoordDto(play.TargetTiles[0].X, play.TargetTiles[0].Y))),
+ _ => Msg("game.play_card",
+ new GamePlayCardRequest(SessionId, play.CardInstanceId,
+ TargetTiles: play.TargetTiles
+ .Select(c => new CoordDto(c.X, c.Y)).ToList())),
+ },
+
+ AiMoveAction move =>
+ Msg("game.move_unit",
+ new GameMoveUnitRequest(SessionId, move.UnitInstanceId,
+ new CoordDto(move.Target.X, move.Target.Y))),
+
+ AiAttackAction atk =>
+ Msg("game.attack",
+ new GameAttackRequest(SessionId, atk.AttackerInstanceId, atk.TargetInstanceId)),
+
+ AiSacrificeAction sac =>
+ Msg("game.sacrifice",
+ new GameSacrificeRequest(SessionId, sac.UnitInstanceId)),
+
+ AiAscendAction asc =>
+ Msg("game.ascend",
+ new GameAscendRequest(SessionId, asc.IncomingCardInstanceId)),
+
+ AiEndTurnAction =>
+ Msg("game.end_turn", new GameEndTurnRequest(SessionId)),
+
+ _ => (null, ReadOnlyMemory.Empty),
+ };
+ }
+
+ private static (string msgType, ReadOnlyMemory payload) Msg(string type, T body)
+ => (type, JsonSerializer.SerializeToUtf8Bytes(body));
+
+ // ── Handler invocation ────────────────────────────────────────────────────
+
///
/// Resolves and invokes a game message handler directly in-process,
/// as if the AI were a connected client sending that message.
///
private async Task InvokeHandlerAsync(
- string messageType,
+ string messageType,
ReadOnlyMemory payload,
- CancellationToken ct)
+ CancellationToken ct)
{
- using var scope = _scopeFactory.CreateScope();
- var handlers = scope.ServiceProvider.GetServices();
- var handler = handlers.FirstOrDefault(h => h.MessageType == messageType);
+ using var scope = _scopeFactory.CreateScope();
+ var handlers = scope.ServiceProvider.GetServices();
+ var handler = handlers.FirstOrDefault(h => h.MessageType == messageType);
if (handler is null)
{
@@ -174,14 +273,22 @@ internal sealed class AiPlayerSession : IAsyncDisposable
{
// Session or app shutdown — ignore.
}
+ catch (GameException gex)
+ {
+ _logger.LogDebug(
+ "AI {Account}: handler '{Type}' rejected action: {Code}.",
+ AiAccountId, messageType, gex.Message);
+ }
catch (Exception ex)
{
_logger.LogWarning(ex,
- "AI {Account}: handler '{Type}' threw an exception.",
+ "AI {Account}: handler '{Type}' threw an unexpected exception.",
AiAccountId, messageType);
}
}
+ // ── Lifecycle ─────────────────────────────────────────────────────────────
+
public void Cancel() => _sessionCts.Cancel();
public ValueTask DisposeAsync()
diff --git a/Server/src/SOR.Ai/Engine/AiDifficultyProfile.cs b/Server/src/SOR.Ai/Engine/AiDifficultyProfile.cs
new file mode 100644
index 0000000..5a59a44
--- /dev/null
+++ b/Server/src/SOR.Ai/Engine/AiDifficultyProfile.cs
@@ -0,0 +1,71 @@
+namespace SOR.Ai.Engine;
+
+///
+/// Immutable configuration profile for one AI difficulty tier.
+/// Profiles are defined in AiDifficultyProfiles (in-code constants, no migrations needed).
+/// Strategy archetypes apply weight overlays on top via WithStrategy().
+///
+internal sealed 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 ─────────────────────────────────────────────────────
+ /// Probability (0–1) of replacing the optimal action with a random one.
+ public float MistakeRate { get; init; }
+ /// Probability (0–1) of picking the 2nd-best action instead of the best.
+ public float SuboptimalRate { get; init; }
+
+ // ── MCTS params (Phase 3) ────────────────────────────────────────────────
+ public int MctsTimeBudgetMs { get; init; }
+ public int MctsMaxDepth { get; init; }
+
+ // ── Humanization delays ───────────────────────────────────────────────────
+ /// Think time before the first action of the turn (ms).
+ public int MinThinkTimeMs { get; init; }
+ public int MaxThinkTimeMs { get; init; }
+ /// Delay between subsequent actions within one turn (ms).
+ public int MinActionDelayMs { get; init; }
+ public int MaxActionDelayMs { get; init; }
+
+ // ── Heuristic scoring weights ─────────────────────────────────────────────
+ public float MaterialWeight { get; init; } = 1.0f;
+ public float AffinityControlWeight { get; init; } = 1.0f;
+ public float ThreatWeight { get; init; } = 1.0f;
+ public float PositionalWeight { get; init; } = 1.0f;
+ public float ResourceWeight { get; init; } = 1.0f;
+
+ // ── Strategy overlay ──────────────────────────────────────────────────────
+
+ ///
+ /// Returns a new profile with scoring weights adjusted for the given strategy archetype.
+ /// Strategies shift priorities without changing difficulty level.
+ ///
+ public AiDifficultyProfile WithStrategy(string strategy) => strategy switch
+ {
+ "Aggressive" => this with
+ {
+ MaterialWeight = MaterialWeight * 1.3f,
+ ThreatWeight = ThreatWeight * 0.5f, // less defensive
+ PositionalWeight = PositionalWeight * 1.5f, // push toward opponent
+ },
+ "Control" => this with
+ {
+ ThreatWeight = ThreatWeight * 1.6f, // protect ArchSpirit
+ AffinityControlWeight = AffinityControlWeight * 1.8f, // Terramorpha priority
+ MaterialWeight = MaterialWeight * 0.8f,
+ },
+ "Ramp" => this with
+ {
+ ResourceWeight = ResourceWeight * 2.0f, // value ST/SP accumulation
+ MaterialWeight = MaterialWeight * 0.7f,
+ },
+ "Swarm" => this with
+ {
+ MaterialWeight = MaterialWeight * 1.2f, // value unit count
+ PositionalWeight = PositionalWeight * 1.1f,
+ },
+ _ => this, // "Balanced" — no adjustment
+ };
+}
diff --git a/Server/src/SOR.Ai/Engine/AiDifficultyProfiles.cs b/Server/src/SOR.Ai/Engine/AiDifficultyProfiles.cs
new file mode 100644
index 0000000..b1eb4cf
--- /dev/null
+++ b/Server/src/SOR.Ai/Engine/AiDifficultyProfiles.cs
@@ -0,0 +1,189 @@
+namespace SOR.Ai.Engine;
+
+///
+/// Static lookup table for all 10 difficulty profiles.
+/// In-code constants — no DB storage needed, tuning is done via code changes.
+///
+internal static class AiDifficultyProfiles
+{
+ private static readonly AiDifficultyProfile[] _profiles =
+ [
+ // ── Tier 1: Novice (Random) ───────────────────────────────────────────
+ new()
+ {
+ Difficulty = 1,
+ DisplayName = "Novice",
+ EngineType = "Random",
+ MistakeRate = 1.0f,
+ MinThinkTimeMs = 600,
+ MaxThinkTimeMs = 1400,
+ MinActionDelayMs = 300,
+ MaxActionDelayMs = 700,
+ },
+
+ // ── Tier 2: Apprentice (Heuristic, 60% mistakes) ─────────────────────
+ new()
+ {
+ Difficulty = 2,
+ DisplayName = "Apprentice",
+ EngineType = "Heuristic",
+ MistakeRate = 0.60f,
+ MinThinkTimeMs = 700,
+ MaxThinkTimeMs = 1600,
+ MinActionDelayMs = 400,
+ MaxActionDelayMs = 900,
+ MaterialWeight = 1.0f,
+ AffinityControlWeight = 0.5f,
+ ThreatWeight = 0.5f,
+ PositionalWeight = 0.5f,
+ ResourceWeight = 0.5f,
+ },
+
+ // ── Tier 3: Journeyman (Heuristic, 40% mistakes) ─────────────────────
+ new()
+ {
+ Difficulty = 3,
+ DisplayName = "Journeyman",
+ EngineType = "Heuristic",
+ MistakeRate = 0.40f,
+ MinThinkTimeMs = 800,
+ MaxThinkTimeMs = 1800,
+ MinActionDelayMs = 400,
+ MaxActionDelayMs = 900,
+ MaterialWeight = 1.0f,
+ AffinityControlWeight = 0.8f,
+ ThreatWeight = 0.8f,
+ PositionalWeight = 0.8f,
+ ResourceWeight = 0.7f,
+ },
+
+ // ── Tier 4: Adept (Heuristic, 25% mistakes) ──────────────────────────
+ new()
+ {
+ Difficulty = 4,
+ DisplayName = "Adept",
+ EngineType = "Heuristic",
+ MistakeRate = 0.25f,
+ MinThinkTimeMs = 900,
+ MaxThinkTimeMs = 2000,
+ MinActionDelayMs = 500,
+ MaxActionDelayMs = 1100,
+ MaterialWeight = 1.0f,
+ AffinityControlWeight = 1.0f,
+ ThreatWeight = 1.0f,
+ PositionalWeight = 1.0f,
+ ResourceWeight = 0.8f,
+ },
+
+ // ── Tier 5: Expert (Heuristic, 10% mistakes) ─────────────────────────
+ new()
+ {
+ Difficulty = 5,
+ DisplayName = "Expert",
+ EngineType = "Heuristic",
+ MistakeRate = 0.10f,
+ MinThinkTimeMs = 1000,
+ MaxThinkTimeMs = 2200,
+ MinActionDelayMs = 600,
+ MaxActionDelayMs = 1200,
+ MaterialWeight = 1.0f,
+ AffinityControlWeight = 1.2f,
+ ThreatWeight = 1.2f,
+ PositionalWeight = 1.1f,
+ ResourceWeight = 1.0f,
+ },
+
+ // ── Tiers 6–10: placeholder Heuristic until MCTS/Neural are built ─────
+ // Phase 3 will replace EngineType with "MCTS" / "Neural".
+ new()
+ {
+ Difficulty = 6,
+ DisplayName = "Master",
+ EngineType = "Heuristic", // TODO Phase 3: "MCTS"
+ MistakeRate = 0.05f,
+ MctsTimeBudgetMs = 500,
+ MctsMaxDepth = 3,
+ MinThinkTimeMs = 1200,
+ MaxThinkTimeMs = 2500,
+ MinActionDelayMs = 700,
+ MaxActionDelayMs = 1400,
+ MaterialWeight = 1.2f,
+ AffinityControlWeight = 1.4f,
+ ThreatWeight = 1.4f,
+ PositionalWeight = 1.2f,
+ ResourceWeight = 1.2f,
+ },
+ new()
+ {
+ Difficulty = 7,
+ DisplayName = "Grandmaster",
+ EngineType = "Heuristic", // TODO Phase 3: "MCTS"
+ MistakeRate = 0.02f,
+ MctsTimeBudgetMs = 1500,
+ MctsMaxDepth = 5,
+ MinThinkTimeMs = 1400,
+ MaxThinkTimeMs = 3000,
+ MinActionDelayMs = 800,
+ MaxActionDelayMs = 1500,
+ MaterialWeight = 1.3f,
+ AffinityControlWeight = 1.5f,
+ ThreatWeight = 1.5f,
+ PositionalWeight = 1.3f,
+ ResourceWeight = 1.3f,
+ },
+ new()
+ {
+ Difficulty = 8,
+ DisplayName = "Champion",
+ EngineType = "Heuristic", // TODO Phase 3: "MCTS"
+ MistakeRate = 0.0f,
+ MctsTimeBudgetMs = 4000,
+ MctsMaxDepth = 7,
+ MinThinkTimeMs = 1500,
+ MaxThinkTimeMs = 3200,
+ MinActionDelayMs = 900,
+ MaxActionDelayMs = 1600,
+ MaterialWeight = 1.4f,
+ AffinityControlWeight = 1.6f,
+ ThreatWeight = 1.6f,
+ PositionalWeight = 1.4f,
+ ResourceWeight = 1.4f,
+ },
+ new()
+ {
+ Difficulty = 9,
+ DisplayName = "Legend",
+ EngineType = "Heuristic", // TODO Phase 4: "Neural"
+ MistakeRate = 0.0f,
+ MinThinkTimeMs = 1500,
+ MaxThinkTimeMs = 3000,
+ MinActionDelayMs = 900,
+ MaxActionDelayMs = 1600,
+ MaterialWeight = 1.5f,
+ AffinityControlWeight = 1.8f,
+ ThreatWeight = 1.8f,
+ PositionalWeight = 1.5f,
+ ResourceWeight = 1.5f,
+ },
+ new()
+ {
+ Difficulty = 10,
+ DisplayName = "Mythic",
+ EngineType = "Heuristic", // TODO Phase 4: "Neural"
+ MistakeRate = 0.0f,
+ MinThinkTimeMs = 1500,
+ MaxThinkTimeMs = 3000,
+ MinActionDelayMs = 1000,
+ MaxActionDelayMs = 1800,
+ MaterialWeight = 1.6f,
+ AffinityControlWeight = 2.0f,
+ ThreatWeight = 2.0f,
+ PositionalWeight = 1.6f,
+ ResourceWeight = 1.6f,
+ },
+ ];
+
+ /// Returns the difficulty profile for the given tier (1–10).
+ public static AiDifficultyProfile Get(int difficulty)
+ => _profiles[Math.Clamp(difficulty, 1, 10) - 1];
+}
diff --git a/Server/src/SOR.Ai/Engine/IAiDecisionEngine.cs b/Server/src/SOR.Ai/Engine/IAiDecisionEngine.cs
new file mode 100644
index 0000000..322f9dc
--- /dev/null
+++ b/Server/src/SOR.Ai/Engine/IAiDecisionEngine.cs
@@ -0,0 +1,65 @@
+namespace SOR.Ai.Engine;
+
+using SOR.Ai.Core;
+using SOR.Game.Grid;
+
+///
+/// Contract for all AI turn-planning engines.
+/// Takes a snapshot of the game state and returns an ordered action plan
+/// that the session manager will execute sequentially.
+///
+/// Implementations must be pure (no DB, no network). They may read GameState
+/// but must not mutate it — the caller owns the original state.
+///
+internal interface IAiDecisionEngine
+{
+ ///
+ /// Compute the full action plan for the AI's turn.
+ /// The plan MUST end with as the final element.
+ ///
+ IReadOnlyList ComputeTurn(AiTurnContext ctx);
+}
+
+// ── AiAction discriminated union ──────────────────────────────────────────────
+
+/// Base type for all AI actions.
+internal abstract record AiAction;
+
+/// Draw card(s) from deck (Draw phase).
+internal sealed record AiDrawAction : AiAction;
+
+///
+/// Channel (play) a card from hand.
+/// TargetTiles contains:
+/// - 0 entries → Ruin / Repentance / Instinct (no tile required)
+/// - 1 entry → Spirit or Terramorpha Mono
+/// - 2 entries → Terramorpha Di (tiles must be adjacent)
+/// - 3 entries → Terramorpha Tri (each adjacent to the previous)
+///
+internal sealed record AiPlayCardAction(
+ string CardInstanceId,
+ IReadOnlyList TargetTiles) : AiAction;
+
+/// Move a unit to a new tile.
+internal sealed record AiMoveAction(
+ string UnitInstanceId,
+ Coord Target) : AiAction;
+
+/// Attack an opponent's unit (or ArchSpirit) with one of the AI's field cards.
+internal sealed record AiAttackAction(
+ string AttackerInstanceId,
+ string TargetInstanceId) : AiAction;
+
+/// Activate an active ability (no target required for Phase 2).
+internal sealed record AiActivateAbilityAction(
+ string UnitInstanceId,
+ int AbilityIndex) : AiAction;
+
+/// Sacrifice a Spirit adjacent to the AI's ArchSpirit.
+internal sealed record AiSacrificeAction(string UnitInstanceId) : AiAction;
+
+/// Ascend the AI's ArchSpirit to the next tier.
+internal sealed record AiAscendAction(string IncomingCardInstanceId) : AiAction;
+
+/// End the AI's turn (always the final action in the plan).
+internal sealed record AiEndTurnAction : AiAction;
diff --git a/Server/src/SOR.Ai/Engine/RandomDecisionEngine.cs b/Server/src/SOR.Ai/Engine/RandomDecisionEngine.cs
new file mode 100644
index 0000000..0c580df
--- /dev/null
+++ b/Server/src/SOR.Ai/Engine/RandomDecisionEngine.cs
@@ -0,0 +1,49 @@
+namespace SOR.Ai.Engine;
+
+using SOR.Ai.Core;
+using SOR.Ai.Heuristics;
+using SOR.Database.Enums;
+
+///
+/// Random decision engine (Difficulty 1 — Novice).
+/// Picks a random legal action each step until SP/MP is exhausted or no candidates remain.
+/// All chosen actions are valid (won't throw GameException when submitted).
+///
+internal sealed class RandomDecisionEngine : IAiDecisionEngine
+{
+ public IReadOnlyList ComputeTurn(AiTurnContext ctx)
+ {
+ var plan = new List();
+
+ // Draw phase → always draw.
+ if (ctx.State.Phase == GamePhase.Draw)
+ plan.Add(new AiDrawAction());
+
+ // Main phase: pick random legal actions until exhausted.
+ // Limit iterations to prevent runaway loops in edge cases.
+ const int maxActions = 50;
+ int iterations = 0;
+
+ while (iterations++ < maxActions)
+ {
+ var candidates = ActionCandidateGenerator.All(ctx);
+
+ // Filter out draw action — handled above, or not applicable.
+ var mainCandidates = candidates
+ .Where(a => a is not AiDrawAction)
+ .ToList();
+
+ if (mainCandidates.Count == 0)
+ break;
+
+ var chosen = mainCandidates[Random.Shared.Next(mainCandidates.Count)];
+ plan.Add(chosen);
+
+ // If it was an AttackAction the attacker is now exhausted — stop if no
+ // other actions are available (will be detected on next iteration).
+ }
+
+ plan.Add(new AiEndTurnAction());
+ return plan;
+ }
+}
diff --git a/Server/src/SOR.Ai/Heuristics/ActionCandidateGenerator.cs b/Server/src/SOR.Ai/Heuristics/ActionCandidateGenerator.cs
new file mode 100644
index 0000000..b978218
--- /dev/null
+++ b/Server/src/SOR.Ai/Heuristics/ActionCandidateGenerator.cs
@@ -0,0 +1,374 @@
+namespace SOR.Ai.Heuristics;
+
+using SOR.Ai.Core;
+using SOR.Ai.Engine;
+using SOR.Database.Enums;
+using SOR.Game;
+using SOR.Game.Combat;
+using SOR.Game.Grid;
+
+///
+/// Enumerates every legal action available to the AI on its current turn.
+/// Pure static methods — no side effects, no DB access.
+/// Delegates range/path/affinity logic to SOR.Game modules so no rules are duplicated.
+///
+internal static class ActionCandidateGenerator
+{
+ /// Returns all legal actions for the active player in the given turn context.
+ public static IReadOnlyList All(AiTurnContext ctx)
+ {
+ var state = ctx.State;
+ var result = new List();
+
+ if (state.Phase == GamePhase.Draw)
+ {
+ result.Add(new AiDrawAction());
+ return result;
+ }
+
+ if (state.Phase != GamePhase.Main)
+ return result;
+
+ result.AddRange(Channelings(ctx));
+ result.AddRange(AllMovements(ctx));
+ result.AddRange(AllAttacks(ctx));
+ result.AddRange(Sacrifices(ctx));
+ result.AddRange(AscendCandidates(ctx));
+
+ return result;
+ }
+
+ // ── Channeling ────────────────────────────────────────────────────────────
+
+ /// All valid card-play actions (Spirits, Terramorpha, Ruin, Repentance/Instinct).
+ public static IReadOnlyList Channelings(AiTurnContext ctx)
+ {
+ var player = ctx.AiPlayer;
+ var state = ctx.State;
+ var board = state.Board;
+ var result = new List();
+
+ foreach (var card in player.Hand)
+ {
+ if (player.CurrentSp < card.SpCost) continue;
+ if (player.CurrentSt < card.StCost) continue;
+
+ switch (card.CardType)
+ {
+ case "Spirit":
+ if (!player.CanChannelSpirit) continue;
+ result.AddRange(SpiritChannelings(ctx, card, board));
+ break;
+
+ case "Terramorpha":
+ result.AddRange(TerramorphaChannelings(ctx, card, board));
+ break;
+
+ case "Ruin":
+ if (!player.CanChannelRuin) continue;
+ // Placement is random — just add one candidate per Ruin card.
+ result.Add(new AiPlayCardAction(card.InstanceId, []));
+ break;
+
+ case "Repentance":
+ if (!player.CanChannelRepentance) continue;
+ result.Add(new AiPlayCardAction(card.InstanceId, []));
+ break;
+
+ case "Instinct":
+ if (!player.CanChannelInstinct) continue;
+ result.Add(new AiPlayCardAction(card.InstanceId, []));
+ break;
+ }
+ }
+
+ return result;
+ }
+
+ private static IEnumerable SpiritChannelings(
+ AiTurnContext ctx, CardInstance card, Board? board)
+ {
+ if (board is null) yield break;
+
+ var archSpirit = ctx.AiPlayer.ArchSpirit;
+ if (archSpirit?.Position is null) yield break;
+
+ var origin = archSpirit.Position.Value;
+ var minRange = card.MinChannelRange ?? 1;
+ var maxRange = card.MaxChannelRange ?? 1;
+
+ if (!Enum.TryParse(card.Affinity, out var affinity))
+ yield break;
+
+ foreach (var tile in board.Tiles.Values)
+ {
+ if (!tile.IsEmpty) continue;
+
+ var dist = board.HexSides > 0
+ ? HexGrid.Distance(origin, tile.Coord, board.HexSides)
+ : origin.ManhattanDistance(tile.Coord);
+
+ if (dist < minRange || dist > maxRange) continue;
+ if (!AffinitySystem.IsAffinityValid(tile, affinity)) continue;
+
+ yield return new AiPlayCardAction(card.InstanceId, [tile.Coord]);
+ }
+ }
+
+ private static IEnumerable TerramorphaChannelings(
+ AiTurnContext ctx, CardInstance card, Board? board)
+ {
+ if (board is null) yield break;
+
+ bool allowed = card.TerramorphaMode switch
+ {
+ TerramorphaMode.Mono => ctx.AiPlayer.CanChannelTerramorphaMono,
+ TerramorphaMode.Di => ctx.AiPlayer.CanChannelTerramorphaDi,
+ TerramorphaMode.Tri => ctx.AiPlayer.CanChannelTerramorphaTri,
+ _ => false,
+ };
+ if (!allowed) yield break;
+
+ var allCoords = board.Tiles.Keys
+ .Select(k => board.Tiles[k].Coord)
+ .ToList();
+
+ if (card.TerramorphaMode == TerramorphaMode.Mono)
+ {
+ foreach (var c in allCoords)
+ yield return new AiPlayCardAction(card.InstanceId, [c]);
+ }
+ else if (card.TerramorphaMode == TerramorphaMode.Di)
+ {
+ foreach (var c1 in allCoords)
+ foreach (var c2 in board.GetNeighbors(c1))
+ yield return new AiPlayCardAction(card.InstanceId, [c1, c2]);
+ }
+ else // Tri
+ {
+ foreach (var c1 in allCoords)
+ foreach (var c2 in board.GetNeighbors(c1))
+ foreach (var c3 in board.GetNeighbors(c2))
+ {
+ if (c3 == c1) continue;
+ yield return new AiPlayCardAction(card.InstanceId, [c1, c2, c3]);
+ }
+ }
+ }
+
+ // ── Movement ──────────────────────────────────────────────────────────────
+
+ /// All movement candidates for all of the AI's movable units.
+ public static IReadOnlyList AllMovements(AiTurnContext ctx)
+ {
+ var result = new List();
+ foreach (var unit in AllFieldUnits(ctx.AiPlayer))
+ result.AddRange(Movements(ctx, unit.InstanceId));
+ return result;
+ }
+
+ /// Movement candidates for a specific unit.
+ public static IReadOnlyList Movements(AiTurnContext ctx, string unitInstanceId)
+ {
+ var state = ctx.State;
+ var board = state.Board;
+ if (board is null) return [];
+
+ var unit = FindUnit(ctx.AiPlayer, unitInstanceId);
+ if (unit is null || !unit.CanMove || unit.CurrentMp <= 0 || unit.Position is null)
+ return [];
+
+ var movType = unit.MovementType;
+ var result = new List();
+
+ if (movType is MovementType.Walk or MovementType.Flight)
+ {
+ var blocked = BuildBlockedSet(state, unitInstanceId, movType);
+ var reachable = Pathfinding.GetReachableWithCost(board, unit.Position.Value, unit.CurrentMp, blocked);
+ foreach (var (coord, _) in reachable)
+ {
+ var tile = board.GetTile(coord);
+ if (tile is not null && tile.IsEmpty)
+ result.Add(new AiMoveAction(unitInstanceId, coord));
+ }
+ }
+ else if (movType is MovementType.Jump)
+ {
+ foreach (var coord in Pathfinding.GetJumpRange(board, unit.Position.Value, 1, unit.CurrentMp))
+ {
+ var tile = board.GetTile(coord);
+ if (tile is not null && tile.IsEmpty)
+ result.Add(new AiMoveAction(unitInstanceId, coord));
+ }
+ }
+ else if (movType is MovementType.Teleport)
+ {
+ var occupancy = board.BuildOccupancyMap();
+ occupancy.Remove(unit.Position.Value);
+ foreach (var coord in Pathfinding.GetJumpRange(board, unit.Position.Value, 1, unit.CurrentMp))
+ {
+ var tile = board.GetTile(coord);
+ if (tile is null || !tile.IsEmpty) continue;
+ if (LineOfSight.HasLos(board, unit.Position.Value, coord, occupancy, board.HexSides))
+ result.Add(new AiMoveAction(unitInstanceId, coord));
+ }
+ }
+
+ return result;
+ }
+
+ // ── Attacks ───────────────────────────────────────────────────────────────
+
+ /// All attack candidates for all of the AI's units that can still attack.
+ public static IReadOnlyList AllAttacks(AiTurnContext ctx)
+ {
+ var result = new List();
+ foreach (var unit in AllFieldUnits(ctx.AiPlayer))
+ result.AddRange(Attacks(ctx, unit.InstanceId));
+ return result;
+ }
+
+ /// Attack candidates for a specific unit.
+ public static IReadOnlyList Attacks(AiTurnContext ctx, string unitInstanceId)
+ {
+ var state = ctx.State;
+ var board = state.Board;
+
+ var unit = FindUnit(ctx.AiPlayer, unitInstanceId);
+ if (unit is null || unit.IsExhausted || !unit.CanAttack || unit.Position is null)
+ return [];
+
+ if (unit.ExtraAttacksRemaining == 0 && unit.IsExhausted)
+ return [];
+
+ var result = new List();
+ var minRange = unit.MinAttackRange ?? 1;
+ var maxRange = unit.MaxAttackRange ?? 1;
+
+ if (board is not null)
+ {
+ var occupancy = board.BuildOccupancyMap();
+ var attackableCoords = AttackSystem.GetAttackableCoords(
+ board, unit.Position.Value, minRange, maxRange, unit.RequiresLos, occupancy)
+ .ToHashSet();
+
+ foreach (var enemyId in ctx.OpponentIds)
+ {
+ var enemy = state.Players[enemyId];
+ foreach (var target in AllFieldUnits(enemy))
+ {
+ if (!target.CanBeAttacked) continue;
+ if (target.Position.HasValue && attackableCoords.Contains(target.Position.Value))
+ result.Add(new AiAttackAction(unitInstanceId, target.InstanceId));
+ }
+ }
+ }
+ else
+ {
+ // No board — any enemy unit is valid (fallback for legacy games).
+ foreach (var enemyId in ctx.OpponentIds)
+ foreach (var target in AllFieldUnits(state.Players[enemyId]))
+ if (target.CanBeAttacked)
+ result.Add(new AiAttackAction(unitInstanceId, target.InstanceId));
+ }
+
+ return result;
+ }
+
+ // ── Sacrifice ─────────────────────────────────────────────────────────────
+
+ /// Sacrifice candidates — non-ArchSpirit Spirits adjacent to the AI's ArchSpirit.
+ public static IReadOnlyList Sacrifices(AiTurnContext ctx)
+ {
+ if (!ctx.AiPlayer.CanSacrificeSpirit) return [];
+
+ var archSpirit = ctx.AiPlayer.ArchSpirit;
+ if (archSpirit?.Position is null) return [];
+
+ var archPos = archSpirit.Position.Value;
+ var result = new List();
+
+ foreach (var unit in ctx.AiPlayer.Field.OfType())
+ {
+ if (unit.IsLeader || !unit.CanBeSacrificed) continue;
+ if (unit.Position is null) continue;
+ if (unit.Position.Value.IsOrthogonallyAdjacentTo(archPos))
+ result.Add(new AiSacrificeAction(unit.InstanceId));
+ }
+
+ return result;
+ }
+
+ // ── Ascend ────────────────────────────────────────────────────────────────
+
+ /// Ascend candidates — next-tier ArchSpirit available in any zone, affordable.
+ public static IReadOnlyList AscendCandidates(AiTurnContext ctx)
+ {
+ var player = ctx.AiPlayer;
+ var archSpirit = player.ArchSpirit;
+ if (archSpirit?.Position is null) return [];
+ if (!player.CanAscendArchSpirit) return [];
+
+ int nextTier = (archSpirit.Tier ?? 1) + 1;
+ var currentDefId = archSpirit.CardDefinitionId;
+
+ var candidates = player.Hand
+ .Concat(player.Deck)
+ .Concat(player.Discard)
+ .Where(c => c.CardType == "ArchSpirit"
+ && (c.Tier ?? 1) == nextTier
+ && c.PreviousTierId == currentDefId
+ && player.CurrentSp >= c.SpCost
+ && player.CurrentSt >= c.StCost)
+ .Select(c => new AiAscendAction(c.InstanceId))
+ .ToList();
+
+ return candidates;
+ }
+
+ // ── Helpers ───────────────────────────────────────────────────────────────
+
+ private static IEnumerable AllFieldUnits(PlayerState player)
+ {
+ foreach (var fc in player.Field.OfType())
+ yield return fc;
+
+ if (player.ArchSpirit is not null)
+ yield return player.ArchSpirit;
+ }
+
+ private static FieldCard? FindUnit(PlayerState player, string instanceId)
+ {
+ foreach (var fc in player.Field.OfType())
+ if (fc.InstanceId == instanceId) return fc;
+ if (player.ArchSpirit?.InstanceId == instanceId)
+ return player.ArchSpirit;
+ return null;
+ }
+
+ ///
+ /// Replicates GameEngine's internal blocked-tile set for movement pathfinding.
+ /// Walk is blocked by all units; Flight is blocked only by other Flight units.
+ ///
+ private static HashSet BuildBlockedSet(
+ GameState state, string movingUnitId, MovementType? movType)
+ {
+ var blocked = new HashSet();
+ foreach (var player in state.Players.Values)
+ {
+ foreach (var card in player.Field.OfType())
+ {
+ if (card.InstanceId == movingUnitId || !card.Position.HasValue) continue;
+ if (movType == MovementType.Flight && card.MovementType != MovementType.Flight) continue;
+ blocked.Add(card.Position.Value);
+ }
+ var arch = player.ArchSpirit;
+ if (arch is not null && arch.InstanceId != movingUnitId && arch.Position.HasValue)
+ {
+ if (movType != MovementType.Flight || arch.MovementType == MovementType.Flight)
+ blocked.Add(arch.Position.Value);
+ }
+ }
+ return blocked;
+ }
+}
diff --git a/Server/src/SOR.Ai/Heuristics/HeuristicDecisionEngine.cs b/Server/src/SOR.Ai/Heuristics/HeuristicDecisionEngine.cs
new file mode 100644
index 0000000..03b7d95
--- /dev/null
+++ b/Server/src/SOR.Ai/Heuristics/HeuristicDecisionEngine.cs
@@ -0,0 +1,151 @@
+namespace SOR.Ai.Heuristics;
+
+using SOR.Ai.Core;
+using SOR.Ai.Engine;
+using SOR.Database.Enums;
+using SOR.Game;
+
+///
+/// Greedy heuristic decision engine (Difficulties 2–5 and 6–10 until MCTS/Neural phases).
+///
+/// Turn algorithm:
+/// 1. Draw (always, no decision needed).
+/// 2. Greedy loop: at each step pick the candidate action that maximises
+/// ScoringFunctions.Evaluate on the simulated post-action state.
+/// MistakeRate: randomly replace optimal with a random candidate.
+/// 3. Append AiEndTurnAction.
+///
+/// State simulation clones via JSON (GameEngine.Serialize/Deserialize) so the
+/// original state is never mutated, and ability side-effects are included in scores.
+///
+internal sealed class HeuristicDecisionEngine : IAiDecisionEngine
+{
+ private readonly AiDifficultyProfile _profile;
+
+ public HeuristicDecisionEngine(AiDifficultyProfile profile)
+ {
+ _profile = profile;
+ }
+
+ public IReadOnlyList ComputeTurn(AiTurnContext ctx)
+ {
+ var plan = new List();
+
+ // ── 1. Draw phase ─────────────────────────────────────────────────────
+ GameState workingState;
+ if (ctx.State.Phase == GamePhase.Draw)
+ {
+ plan.Add(new AiDrawAction());
+
+ // Simulate the draw to get the Main-phase state for greedy evaluation.
+ workingState = CloneState(ctx.State);
+ try { GameEngine.Draw(workingState, ctx.AiAccountId); }
+ catch { workingState = CloneState(ctx.State); /* if draw fails, proceed anyway */ }
+ }
+ else
+ {
+ workingState = CloneState(ctx.State);
+ }
+
+ // ── 2. Greedy main phase loop ─────────────────────────────────────────
+ float baseScore = ScoringFunctions.Evaluate(workingState, ctx.AiAccountId, _profile);
+ const int maxActions = 50;
+ int iterations = 0;
+
+ while (iterations++ < maxActions)
+ {
+ var workingCtx = new AiTurnContext(workingState, ctx.AiAccountId);
+ var candidates = ActionCandidateGenerator.All(workingCtx)
+ .Where(a => a is not AiDrawAction)
+ .ToList();
+
+ if (candidates.Count == 0) break;
+
+ AiAction? bestAction = null;
+ float bestScore = baseScore;
+
+ foreach (var candidate in candidates)
+ {
+ var simState = CloneState(workingState);
+ float score;
+ try
+ {
+ ApplyAction(simState, ctx.AiAccountId, candidate);
+ score = ScoringFunctions.Evaluate(simState, ctx.AiAccountId, _profile);
+ }
+ catch
+ {
+ // Invalid in the current state — skip.
+ continue;
+ }
+
+ if (score > bestScore)
+ {
+ bestScore = score;
+ bestAction = candidate;
+ }
+ }
+
+ if (bestAction is null)
+ break; // no improvement available
+
+ // ── Mistake injection ──────────────────────────────────────────────
+ if (_profile.MistakeRate > 0 && Random.Shared.NextSingle() < _profile.MistakeRate)
+ bestAction = candidates[Random.Shared.Next(candidates.Count)];
+
+ plan.Add(bestAction);
+
+ // Apply the chosen action to the working state.
+ try { ApplyAction(workingState, ctx.AiAccountId, bestAction); }
+ catch { break; /* action became invalid — stop the loop */ }
+
+ baseScore = ScoringFunctions.Evaluate(workingState, ctx.AiAccountId, _profile);
+ }
+
+ plan.Add(new AiEndTurnAction());
+ return plan;
+ }
+
+ // ── Helpers ───────────────────────────────────────────────────────────────
+
+ private static GameState CloneState(GameState state)
+ => GameEngine.Deserialize(GameEngine.Serialize(state));
+
+ ///
+ /// Apply one AiAction directly to a GameState (for simulation purposes).
+ /// Throws GameException if the action is invalid — callers must handle this.
+ ///
+ private static void ApplyAction(GameState state, string actorId, AiAction action)
+ {
+ switch (action)
+ {
+ case AiDrawAction:
+ GameEngine.Draw(state, actorId);
+ break;
+
+ case AiPlayCardAction play:
+ GameEngine.ChannelCard(state, actorId, play.CardInstanceId, play.TargetTiles);
+ break;
+
+ case AiMoveAction move:
+ GameEngine.MoveUnit(state, actorId, move.UnitInstanceId, move.Target);
+ break;
+
+ case AiAttackAction atk:
+ GameEngine.Attack(state, actorId, atk.AttackerInstanceId, atk.TargetInstanceId);
+ break;
+
+ case AiSacrificeAction sac:
+ GameEngine.Sacrifice(state, actorId, sac.UnitInstanceId);
+ break;
+
+ case AiAscendAction asc:
+ GameEngine.Ascend(state, actorId, asc.IncomingCardInstanceId);
+ break;
+
+ case AiEndTurnAction:
+ // Don't simulate end-turn — the greedy loop handles the termination.
+ break;
+ }
+ }
+}
diff --git a/Server/src/SOR.Ai/Heuristics/ScoringFunctions.cs b/Server/src/SOR.Ai/Heuristics/ScoringFunctions.cs
new file mode 100644
index 0000000..4445053
--- /dev/null
+++ b/Server/src/SOR.Ai/Heuristics/ScoringFunctions.cs
@@ -0,0 +1,205 @@
+namespace SOR.Ai.Heuristics;
+
+using SOR.Ai.Core;
+using SOR.Ai.Engine;
+using SOR.Database.Enums;
+using SOR.Game;
+using SOR.Game.Grid;
+
+///
+/// Board evaluation function for the heuristic decision engine.
+///
+/// Score = Σ (weight × feature) using the formula from the architecture plan §5.2.
+/// Higher = better for the AI. Weights come from AiDifficultyProfile so that
+/// different difficulty/strategy combinations produce different behaviour without
+/// any code changes.
+///
+internal static class ScoringFunctions
+{
+ ///
+ /// Evaluate the board state from the AI's perspective.
+ /// Returns a dimensionless float — only the relative ordering of scores matters.
+ ///
+ public static float Evaluate(
+ GameState state,
+ string aiAccountId,
+ AiDifficultyProfile profile)
+ {
+ if (!state.Players.TryGetValue(aiAccountId, out var aiPlayer))
+ return 0f;
+
+ float material = MaterialScore(state, aiAccountId);
+ float affinityControl = AffinityControlScore(state, aiAccountId, aiPlayer);
+ float threat = ThreatScore(state, aiAccountId, aiPlayer);
+ float positional = PositionalScore(state, aiAccountId, aiPlayer);
+ float resource = ResourceScore(state, aiPlayer);
+
+ return material * profile.MaterialWeight
+ + affinityControl * profile.AffinityControlWeight
+ + threat * profile.ThreatWeight
+ + positional * profile.PositionalWeight
+ + resource * profile.ResourceWeight;
+ }
+
+ // ── Feature functions ──────────────────────────────────────────────────────
+
+ ///
+ /// Material = own unit value − opponent unit value + ArchSpirit HP ratio bonus.
+ ///
+ /// Unit value = Damage × 2 + MaxHealth (roughly captures combat power).
+ /// ArchSpirit HP ratio × 500 heavily rewards keeping your ArchSpirit healthy.
+ ///
+ private static float MaterialScore(GameState state, string aiAccountId)
+ {
+ float score = 0f;
+
+ foreach (var (playerId, player) in state.Players)
+ {
+ if (player.IsEliminated) continue;
+
+ bool isOwn = playerId == aiAccountId;
+ float sign = isOwn ? 1f : -1f;
+
+ // Field units.
+ foreach (var fc in player.Field.OfType())
+ {
+ if (fc.IsLeader) continue; // ArchSpirit counted separately.
+ float value = (fc.Damage ?? 0) * 2f + (fc.MaxHealth ?? 0);
+ score += sign * value;
+ }
+
+ // ArchSpirit HP ratio.
+ var arch = player.ArchSpirit;
+ if (arch is not null)
+ {
+ float maxHp = arch.MaxHealth ?? 1;
+ float curHp = arch.CurrentHealth ?? 0;
+ float ratio = maxHp > 0 ? curHp / maxHp : 0f;
+
+ if (isOwn)
+ score += ratio * 500f;
+ else
+ score -= ratio * 500f; // destroying opponent ArchSpirit is very good
+ }
+ }
+
+ return score;
+ }
+
+ ///
+ /// Affinity control = tiles with own ArchSpirit's affinity within channeling range × 3.
+ /// Rewards building a "pool" of valid channeling tiles.
+ ///
+ private static float AffinityControlScore(
+ GameState state, string aiAccountId, PlayerState aiPlayer)
+ {
+ var board = state.Board;
+ var archSpirit = aiPlayer.ArchSpirit;
+
+ if (board is null || archSpirit?.Position is null) return 0f;
+
+ if (!Enum.TryParse(archSpirit.Affinity, out var aiAffinity))
+ return 0f;
+
+ var origin = archSpirit.Position.Value;
+ var maxRange = archSpirit.MaxChannelRange ?? 1;
+
+ float count = 0f;
+ foreach (var tile in board.Tiles.Values)
+ {
+ var dist = board.HexSides > 0
+ ? HexGrid.Distance(origin, tile.Coord, board.HexSides)
+ : origin.ManhattanDistance(tile.Coord);
+ if (dist > maxRange) continue;
+
+ if (AffinitySystem.IsAffinityValid(tile, aiAffinity))
+ count++;
+ }
+
+ return count * 3f;
+ }
+
+ ///
+ /// Threat = −30 per opponent unit that can reach the AI's ArchSpirit.
+ /// A strong deterrent against leaving the ArchSpirit undefended.
+ ///
+ private static float ThreatScore(
+ GameState state, string aiAccountId, PlayerState aiPlayer)
+ {
+ var ctx = new AiTurnContext(state, aiAccountId);
+ int threats = ThreatDetector.CountThreatsToArchSpirit(ctx);
+ return -threats * 30f;
+ }
+
+ ///
+ /// Positional = +15 per own unit adjacent to any enemy ArchSpirit
+ /// + +2 per own unit in the center 3×3 zone of the board.
+ /// Rewards pressure and board control.
+ ///
+ private static float PositionalScore(
+ GameState state, string aiAccountId, PlayerState aiPlayer)
+ {
+ var board = state.Board;
+ if (board is null) return 0f;
+
+ float score = 0f;
+
+ // Center zone: tiles within ⌊board/3⌋ of center.
+ int cx = board.Width / 2;
+ int cy = board.Height / 2;
+ int centerRadius = Math.Max(1, Math.Min(board.Width, board.Height) / 3);
+
+ // Collect enemy ArchSpirit positions.
+ var enemyArchPositions = new List();
+ foreach (var (id, p) in state.Players)
+ {
+ if (id == aiAccountId || p.IsEliminated) continue;
+ if (p.ArchSpirit?.Position.HasValue == true)
+ enemyArchPositions.Add(p.ArchSpirit.Position.Value);
+ }
+
+ foreach (var unit in aiPlayer.Field.OfType())
+ {
+ if (unit.Position is null) continue;
+
+ // Adjacent to enemy ArchSpirit.
+ foreach (var eap in enemyArchPositions)
+ {
+ bool adjacent = board.HexSides > 0
+ ? HexGrid.Distance(unit.Position.Value, eap, board.HexSides) == 1
+ : unit.Position.Value.IsOrthogonallyAdjacentTo(eap);
+ if (adjacent) { score += 15f; break; }
+ }
+
+ // Center control (square grid only for simplicity).
+ if (board.HexSides == 0)
+ {
+ int dx = Math.Abs(unit.Position.Value.X - cx);
+ int dy = Math.Abs(unit.Position.Value.Y - cy);
+ if (dx <= centerRadius && dy <= centerRadius)
+ score += 2f;
+ }
+ }
+
+ return score;
+ }
+
+ ///
+ /// Resource = −10 if SP well above typical per-turn gain (penalise hoarding)
+ /// + +5 per Sacrifice Token.
+ ///
+ private static float ResourceScore(GameState state, PlayerState aiPlayer)
+ {
+ float score = 0f;
+
+ // Penalise excessive unspent SP.
+ int spPerTurn = state.Rules.SpAccumulationPerTurn;
+ if (spPerTurn > 0 && aiPlayer.CurrentSp > spPerTurn * 3)
+ score -= 10f;
+
+ // Sacrifice tokens are immediately valuable.
+ score += aiPlayer.CurrentSt * 5f;
+
+ return score;
+ }
+}
diff --git a/Server/src/SOR.Ai/Heuristics/ThreatDetector.cs b/Server/src/SOR.Ai/Heuristics/ThreatDetector.cs
new file mode 100644
index 0000000..9e8b234
--- /dev/null
+++ b/Server/src/SOR.Ai/Heuristics/ThreatDetector.cs
@@ -0,0 +1,116 @@
+namespace SOR.Ai.Heuristics;
+
+using SOR.Ai.Core;
+using SOR.Database.Enums;
+using SOR.Game;
+using SOR.Game.Combat;
+using SOR.Game.Grid;
+
+///
+/// Detects enemy units that can reach (attack) the AI's ArchSpirit on the next turn.
+/// Used by ScoringFunctions to penalise board states that leave the ArchSpirit exposed.
+///
+internal static class ThreatDetector
+{
+ ///
+ /// Returns the number of opponent units that could attack the AI's ArchSpirit
+ /// if the opponent were to act right now (ignoring exhaustion resets between turns).
+ ///
+ /// Conservative over-estimate: assumes all opponent units are fresh (max MP restored).
+ ///
+ public static int CountThreatsToArchSpirit(AiTurnContext ctx)
+ {
+ var state = ctx.State;
+ var board = state.Board;
+ var archSpirit = ctx.AiPlayer.ArchSpirit;
+
+ if (archSpirit?.Position is null || board is null)
+ return 0;
+
+ var archPos = archSpirit.Position.Value;
+ var occupancy = board.BuildOccupancyMap();
+ int threats = 0;
+
+ foreach (var enemyId in ctx.OpponentIds)
+ {
+ var enemy = state.Players[enemyId];
+
+ foreach (var unit in AllEnemyUnits(enemy))
+ {
+ if (unit.Position is null || !unit.CanAttack) continue;
+
+ var minRange = unit.MinAttackRange ?? 1;
+ var maxRange = unit.MaxAttackRange ?? 1;
+
+ // Check direct attack range first (fast path).
+ if (AttackSystem.CanAttack(
+ unit.Position.Value, archPos,
+ minRange, maxRange, unit.RequiresLos,
+ board, occupancy))
+ {
+ threats++;
+ continue;
+ }
+
+ // Check if the unit can move into attack range.
+ int mp = unit.MaxMp ?? 0; // restored at start of enemy turn
+ if (mp <= 0) continue;
+
+ if (CanReachAttackRange(unit, archPos, mp, minRange, maxRange, state, board))
+ threats++;
+ }
+ }
+
+ return threats;
+ }
+
+ // ── Helpers ───────────────────────────────────────────────────────────────
+
+ private static bool CanReachAttackRange(
+ FieldCard unit, Coord target, int mp,
+ int minRange, int maxRange,
+ GameState state, Board board)
+ {
+ // Build a hypothetical blocked set treating all current occupants as blockers.
+ var blocked = new HashSet();
+ foreach (var p in state.Players.Values)
+ {
+ foreach (var fc in p.Field.OfType())
+ {
+ if (fc.InstanceId == unit.InstanceId || !fc.Position.HasValue) continue;
+ if (unit.MovementType == MovementType.Flight && fc.MovementType != MovementType.Flight) continue;
+ blocked.Add(fc.Position.Value);
+ }
+ var arch = p.ArchSpirit;
+ if (arch is not null && arch.InstanceId != unit.InstanceId && arch.Position.HasValue)
+ {
+ if (unit.MovementType != MovementType.Flight || arch.MovementType == MovementType.Flight)
+ blocked.Add(arch.Position.Value);
+ }
+ }
+
+ var reachable = Pathfinding.GetReachableWithCost(
+ board, unit.Position!.Value, mp, blocked);
+
+ var occupancy = board.BuildOccupancyMap();
+
+ foreach (var (reachableCoord, _) in reachable)
+ {
+ if (AttackSystem.CanAttack(
+ reachableCoord, target,
+ minRange, maxRange, unit.RequiresLos,
+ board, occupancy))
+ return true;
+ }
+
+ return false;
+ }
+
+ private static IEnumerable AllEnemyUnits(PlayerState enemy)
+ {
+ foreach (var fc in enemy.Field.OfType())
+ yield return fc;
+ if (enemy.ArchSpirit is not null)
+ yield return enemy.ArchSpirit;
+ }
+}
diff --git a/Server/src/SOR.Ai/ServiceRegistration.cs b/Server/src/SOR.Ai/ServiceRegistration.cs
index 6dd1514..d0e7cae 100644
--- a/Server/src/SOR.Ai/ServiceRegistration.cs
+++ b/Server/src/SOR.Ai/ServiceRegistration.cs
@@ -3,7 +3,9 @@ namespace SOR.Ai;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using SOR.Ai.Core;
+using SOR.Ai.Engine;
using SOR.Ai.Handlers;
+using SOR.Ai.Heuristics;
using SOR.Ai.Lobby;
using SOR.Ai.Seeding;
using SOR.Networking.Abstractions.Messaging;
@@ -41,6 +43,13 @@ public static class ServiceRegistration
services.AddScoped();
services.AddScoped();
+ // ── Decision engines (transient — each turn gets a fresh instance) ──────
+ // Engines are resolved directly by AiPlayerSession via ResolveEngine(),
+ // not injected via DI — they are pure stateless objects built from profiles.
+ // Registering here for clarity and future testability.
+ services.AddTransient();
+ services.AddTransient();
+
// ── Lobby message handlers ────────────────────────────────────────────
services.AddTransient();
services.AddTransient();