card_game/docs/AI.md

AI

AI v1 consumes Game.Core. It does not reimplement rules.

Scope

• Own current turn only
• Not: MCTS, minimax, multi-turn planning, predicting the player’s next turn, predicting player responses, LLM play

Pipeline: legal actions → simulate (Clone + Execute) → evaluate → shallow beam search → near-optimal pick.

Implemented in TurnBeamSearch (Game.Core). Playtest client shows each AI step’s top scored candidates.

Core loop

state
  → GetLegalActions
  → simulate each action (CloneState + Execute)
  → evaluate
  → keep best candidates (beam width)
  → expand
  → stop at EndTurn or depth limit

After each real action, search again. Do not search the opponent’s next turn.

Evaluation terms

PlayerDamage, EnemyUnitRemoved, OwnBoardValue, EnemyBoardValue, Heal, Draw, Energy, HandValue, CountdownValue, StatusValue.

Killing the player: WIN_SCORE far above ordinary terms. Weights per enemy and board (e.g. more draw weight on empty hand). Do not show weights in UI.

Near-optimal randomness

Compute BestScore. Sample uniformly (via GameRng) among lines with Score >= BestScore * Threshold. Avoids both obvious blunders and fully deterministic puppeteering.

Performance

Limit beam width and action depth. Dedupe identical/equivalent states. Do not simulate player responses in v1. Deep-copy until clone/Execute is the measured bottleneck.