# 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.