# Tabletwin: full documentation

All documentation pages in one file (quick reference and reference first), followed by two example models. Links are absolute.


<!-- https://tabletwin.com/docs/cheatsheet.md -->

# Quick reference

Everything needed to write a model, on one page. Details: [reference](https://tabletwin.com/docs/reference/),
[expressions](https://tabletwin.com/docs/expressions/), [engine](https://tabletwin.com/docs/engine/); workflow and more patterns: [guide](https://tabletwin.com/docs/guide/).
Every snippet below validates and plays: paste it into the
[validator](https://tabletwin.com/validate/) to try it.

**Basics.** One YAML file (YAML 1.1: quote `yes`/`no`/`on`/`off`, `010`, `1:30`). A field `f` is text
for people; `f_x` is an expression the engine runs (`_x` wins). Text without `_x` does nothing or
stops the engine: the [validator](https://tabletwin.com/validate/) lists these gaps under "What the
engine still misses". Players are `0 … n−1`: rulebook "player 1" is `0`.
Index 0 of a zone is the top. Quote expressions containing `: # [ {` or starting with a quote.

## Top-level keys

| Key | Meaning |
|---|---|
| `game`, `label` | Id (lower-case, hyphens) and display name. Required by the schema |
| `num_players` | Default 2 |
| `mode` | `competitive` (default) or `cooperative` |
| `players`, `summary`, `demonstrates`, `scope`, `description`, `utility` | For people only |
| `constants` | `{NAME: value}`; read-only |
| `boards`, `functions` | Board geometry; own pure functions `{name: {params: [a, b?], let: {...}, x: expr}}` |
| `state` | `zones`, `vars`, `derived` (below); `entity_types` is descriptive |
| `flow`, `flows` | Main flow (one node, required); named subflows `{name: node}` |
| `actions` | `{name: {pre_x, cost, effect, speed}}` |
| `triggers`, `modifiers`, `priority`, `outcomes`, `agents`, `content`, `code` | Reactions, value changes, windows, skill, policies, cards as data, escape hatch |
| `open_questions` | `[{id, question, about, status, answer, source}]` ([§22](https://tabletwin.com/docs/reference/#22-open_questions)) |
| `end` | List of end conditions (below) |

## State

| Zone field (`state.zones.<name>`) | Meaning |
|---|---|
| `owner` | `global` (default, one list) or `player` (list per player; path `hand[p]`, unindexed is an error) |
| `visibility` | `public` (default), `owner`, `hidden`: who sees what is drawn into it |
| `shuffled` | `true`: drawing is a chance node (order unknown except known top/bottom) |
| `init_x` | Initial list (`owner: player`: list of lists). Dicts become instances with a `uid` |
| `persist` | `campaign`: kept by `reset` |
| `drawn_from` | Hidden zone dealt from that shuffled zone (so look-ahead players do not peek) |
| `kind`, `holds`, `size`, `label`, `note` | Descriptive |

| Var field (`state.vars.<name>`) | Meaning |
|---|---|
| `scope` | `global` (default, one value) or `player` (list, path `score[p]`; a non-list `init` is copied per player) |
| `init` / `init_x` | Literal (`null` = `None`) / expression (sees constants, `players`, `n_players`, `content`, vars declared above; no zones) |
| `persist` | `campaign`: kept by `reset` |
| `type`, `range`, `label`, `note` | Descriptive |

`state.derived`: `{name: "expr"}` or `{name: {text, x}}`, computed on use; may use derived values
declared above.

## Flow nodes

| Kind | Fields | Does |
|---|---|---|
| all | `id` (unique), `kind`, `label`, `note`, `window`, `end_event` | After the node's own work: its `window` opens, then each `end_event` is emitted with an end check after each. On a loop: once, after the whole loop |
| `sequence` | `children` | Children in order. `children: []` + `window` = a node that only opens a window |
| `loop` | `children`, `over_x`, `as`, `until_x`, `once`, `order` (V) | Before each round: stop if `until_x`. Per value of `over_x` (evaluated each round) set var `as`, run children. With `over_x` and no `until_x` it repeats round after round until an end condition fires. `once: true`: one round. No `over_x`: children once per round. 10,000 rounds: error |
| `branch` | `cases: [{when_x, children}]`, `switch` (V) | First case whose `when_x` is true; `when_x: "True"` as default |
| `step` | `do` (action or list), `actor_x`, `secret`, `visible_to_x` | Legal = actions whose `pre_x` holds; none: skipped (no end check); one: runs without asking; several: decision for `actor_x`. Then cost, effect, end check |
| `subflow` | `ref` (name in `flows`) | Runs that flow; clears `results[ref]`; scoped end conditions apply |

Declare the `as` variable in `state.vars` (a validator error otherwise: it would only exist once the
loop has started, and `reset` would skip it).
Flow expressions see no local names: use the `as` variable. A step without `actor_x` is a system
step: fine if it never needs a decision.

## Actions and ops

Action: `pre_x` (legal when; default always), `cost` (ops run when played), `effect` (ops),
`speed` (playable in windows that `allow` it). In `pre_x`, `cost` and `effect`, `actor` is the
acting player. Names bound in `cost` stay for `effect`. Fields accepting literals:
`value amount what at n die options min max items until target of`; any other text needs `_x`.
`value` text in `set`/`let` is a string literal.

| Op | Fields (`f`/`f_x` = literal or expression) |
|---|---|
| `set` | `var` path, or `of_x` + `attr`; `value`/`value_x` |
| `add` | `var` path, or `of_x` + `attr`; `amount`/`amount_x` (`+`: lists concatenate) |
| `let` | `bind`, `value`/`value_x` |
| `place` | `what`/`what_x`, `to`, `at`/`at_x` (replace index), `position` (`top`/`bottom`/`random`) |
| `create` | `what`/`what_x` (dict → instance), `to`, `n`/`n_x`, `with_x` (extra state), `position`, `bind` (last) |
| `move` | `what`/`what_x` (item or list; first equal element), `from`, `to`, `position` |
| `destroy` | `what`/`what_x`, `from` (else first zone holding it) |
| `draw` | `from`, `to`, `n`/`n_x`, `visible_to_x` (default by destination visibility), `position` |
| `shuffle` | `zone`: forget known top/bottom of a shuffled zone |
| `look` | `from`, `n`/`n_x`, `bind` (list), `actor_x`, `visible_to_x` |
| `search` | `from`, `bind`, `filter_x` (item `it` or `as`), `as`, `actor_x`, `min`/`max`, `visible_to_x` |
| `reveal` | `what`/`what_x`, `visible_to_x` (default everyone) |
| `roll` | `die`/`die_x` (faces), `bind`, `visible_to_x` |
| `choose` | `options`/`options_x`, `bind`, `actor_x` (default `actor`), `secret`, `visible_to_x`, `min`/`max` (subset), `agent` |
| `if` | `cond_x`, `then`, `else` |
| `for_each` | `items`/`items_x`, `as` (default `it`), `body` (copy of names) |
| `repeat` | `until`/`until_x` (tested before each pass), `body` |
| `emit` | `event` (literal name), `impact` (ops; triggers may replace it) |
| `sample` | `model` (name in `outcomes`) |
| `exec` | `of_x` (content item with `effect`; `self` = item), `content` (catalogue path, V) |
| `run` | `flow`: run a named flow inside the effect |
| `window` | `name` (none: every speed) |
| `cancel` | `target`/`target_x`: index in `stack` (0 bottom, −1 top); sets `cancelled` now |
| `modify` | `stat`, `change_x` (`value` = so far), `layer`, `if_x`, `until` (event) |
| `reset` | `scope` (label): every var/zone without `persist` back to its initial value |
| `call` | `code`: escape hatch to code outside the model; always `NotExecutable` (a gap) |
| `say` | `actor`, `channel`, `constraint`, `bind`, `agent`: always `NotExecutable` |

## Windows, triggers, content, outcomes, agents

| Key | Fields |
|---|---|
| `priority.protocol` | `first_x` (default local `actor`, else 0; evaluated once), `closes` (`all_pass_in_succession`/`single_pass_each`), `resolution` (`immediate`/`nested`/`lifo_stack`), `after_action` (`next`/`same`) |
| `priority.windows.<name>` | `allows: [speed, ...]`, `label`, `note` |
| `triggers[]` | `id`, `event`, `timing` (`before`/`when`/`instead`/`after`), `optional` + `controller_x`, `if_x`, `do` |
| `modifiers[]` | `stat`, `change_x`, `layer`, `if_x`; read with `modified('stat', base, k=v)` |
| content item | `id`, `label`, `status` (`verified`/`uncertain`/`missing`), `text`, `effect`, `triggers`, `modifiers`, `abilities` (actions with `speed`), `keywords`, `active_x` |
| `outcomes.<m>` | `derived_x`, `outcomes: [{id, p, p_x, effect}]` (sum 1), `skill` |
| `agents.<a>` | `policy_x` returns an option label (`options`, `decider` in scope) |

Window run: priority from `first_x`, then index + 1 (eliminated skipped). A player with legal
candidates picks one or `pass`; otherwise passes silently. `immediate`: cost + effect + end check
at once. `lifo_stack`: cost at once, item `{action, actor, cancelled}` on `stack`; when all pass,
the top resolves (cancelled: dropped, no check; else effect with its `actor` and cost names, then
end check), and priority goes back to the player `first_x` gave when the window opened (not
re-evaluated). All pass with an empty stack: the window closes, no end check. `cancel` in an
`effect` marks its target only when that effect resolves; cancelling twice is harmless. Give each
fast action a `pre_x` or `cost` that runs out: an always-legal one can keep the window open
forever (validator warning `always playable in window`).

## End conditions

| Field | Meaning |
|---|---|
| `id` | Reason reported |
| `if_x` | Condition (without it: never fires) |
| `result` | `win`, `loss`, `draw`, `score`, `eliminate`, `continue` |
| `who_x` | Competitive `win`/`loss`: one index (a list is an error; several winners: `score`). `eliminate`: index or list |
| `returns_x` | `score`: one number per player |
| `scope` | Name in `flows`: only while that subflow runs |

| Result | Competitive | Cooperative |
|---|---|---|
| `win` | +1 for `who_x`, −1 all others | +1 all |
| `loss` | −1 for `who_x`, +1 all others | −1 all |
| `draw` | 0 all | 0 all |
| `score` | `returns_x` | `returns_x` |
| `eliminate` | add `who_x` to `eliminated`; play and checking go on | same |
| scoped `win`/`loss`/`draw` | `results[scope] = 'win'`/`'loss'`/`'draw'`, the subflow ends, its caller continues | same |

Checked in list order; the first that fires ends the game (`eliminate` and `continue` never stop
the scan). Other results with a `scope` act unscoped while the subflow runs (a scoped `score` ends
the game). **When**: after each step that ran an action; in a window after each played action
(`immediate`) or each resolved, uncancelled item (`lifo_stack`); after each `end_event`. Never
mid-effect, after a cost, when a window closes, or at loop boundaries. Flow ran out: 0 for all.

## Names in scope

| Name | Where |
|---|---|
| constants, vars (incl. `as` loop vars), zones, derived, `players`, `n_players`, `eliminated`, `results` (`{flow: 'win'/'loss'/'draw'}`), `content`, `modified`, functions | Every expression (var `init_x`: no zones, derived or `modified`) |
| `actor` | Action `pre_x`/`cost`/`effect` (step actor; in a window who has priority; on resolution who played it); triggers fired from there. Not in flow or `end` |
| bound names (`bind`, `let`, `for_each` `as`) | Later ops of the same action run; `cost` → `effect`. `for_each`, `emit`, `exec`, `sample` get a copy |
| `it` / `as` | `search` `filter_x`; `for_each` body |
| `self` | Abilities, `exec` effects, content triggers, modifiers, `active_x` |
| `stack`, `window` | Window actions' `pre_x`, `cost` (stack as played on) and `effect` (stack without the item) |
| `event` | Trigger `if_x`, `controller_x`, `do` (plus the emitter's names) |
| `value` | Modifier `change_x` (plus `modified()` keyword args) |
| `options`, `decider` | Agent `policy_x` |

Built-ins: `len any all min max sum range abs round sorted list tuple set dict enumerate zip int
float str bool sigmoid exp sqrt log`; methods `.get .items .keys .values` (dict), `.count .index`
(list, tuple, text). No assignment, lambda, `_names`, `|`, f-strings, comments.

## Places and option labels

| Place (`where`; tactics `at:`) | From |
|---|---|
| `step <id>` | Choice between a step's actions (options: action names) |
| `action <name>` / `action <name> (cost)` | Ops in an action's effect / cost |
| `window <name>` (`window None` for `window: true`) | Priority: legal fast actions + `pass` |
| `trigger <id>` | Optional trigger (`use`/`skip`) and its ops |
| `content <id>` | Ops of an `exec`'d item |
| `<place> · k`, `<place> · <model>`, `<place> · <event>` | k-th pick of a subset (`done` ends it), a `sample`, an `emit` impact |

Other options are labelled by value: text as is, a dict by its `label`, else `id`, else `uid`.

## Checking your model

Everything runs in the browser; nothing is uploaded.

| Tool | What you get |
|---|---|
| [Validator](https://tabletwin.com/validate/) | Paste the model (and optionally a [view](https://tabletwin.com/docs/views/)), press Check (Ctrl+Enter): errors; warnings, including `unknown key`; `% executable` with rules, content, steps, ops, code, open questions; "What the engine still misses" (the gaps, below 100%); "Test games: X of 20 finished" with the end reasons, "Where games stopped" and games that did not end within 5000 requests; "The flow as a tree" |
| [Player](https://tabletwin.com/play/) | "Open in the player" (after a test game finished) adds "Your model". One game question by question: place, options, choice, automatic choices, what changed, the table. Players: a seat by hand, everyone by hand, random, a `policy_x` heuristic, always the first option. "Game (seed)" replays the same game; "view as" shows one player's view |
| [Diagram](https://tabletwin.com/diagram/) | "Draw your own model": the flow as a tree and as a track diagram, with the markers per step |

Done means: no errors, every warning understood, rules 100% executable, 20 of 20 test games
finish with plausible reasons, and one game in the player reads like the rulebook. Simulating
many games, comparing variants and loading your own tactics are not yet available on the site.

## Patterns

**Turn loop.** The loop repeats the round until an end condition fires; the end check runs right
after the step, so `current` is still the player who just moved.

```yaml
game: race
label: Race
num_players: 2
state:
  vars:
    pos: {scope: player, init: 0}
    current: {init: 0}                 # the `as` variable
flow:
  id: game
  kind: loop
  over_x: players
  as: current
  children: [{id: turn, kind: step, actor_x: current, do: [walk, run]}]
actions:
  walk: {effect: [{op: add, var: "pos[actor]", amount: 1}]}       # actor = the player who acts
  run: {effect: [{op: roll, die: [0, 3], bind: d}, {op: add, var: "pos[actor]", amount_x: d}]}
end:
  - {id: finish, if_x: "pos[current] >= 6", result: win, who_x: current}
```

**Cards: setup step without actor, deck, hidden hands, check/fold–bet/call, rank function.**

```yaml
game: mini-poker
label: Mini poker
num_players: 2
constants: {CARDS: [J, Q, K]}
functions:
  rank: {params: [c], x: "'JQK'.index(c)"}          # constant order: J < Q < K
state:
  zones:
    deck: {kind: stack, visibility: hidden, shuffled: true, init_x: "list(CARDS)"}
    hand: {kind: set, owner: player, visibility: owner}
  vars:
    current: {init: 0}
    stake: {scope: player, init: 1}                  # ante
    bet_out: {init: false}
    folded: {init: null}
    called: {init: false}
    checks: {init: 0}
flow:
  id: game
  kind: sequence
  children:
    - {id: deal, kind: step, do: deal}               # no actor_x: a system step
    - id: betting
      kind: loop
      over_x: players
      as: current
      children: [{id: act, kind: step, actor_x: current, do: [check_fold, bet_call]}]
actions:
  deal:
    effect: [{op: for_each, items_x: players, as: p, body: [{op: draw, from: deck, to: "hand[p]"}]}]
  check_fold:
    effect:
      - {op: if, cond_x: bet_out, then: [{op: set, var: folded, value_x: actor}], else: [{op: add, var: checks, amount: 1}]}
  bet_call:
    effect:
      - {op: add, var: "stake[actor]", amount: 1}
      - {op: if, cond_x: bet_out, then: [{op: set, var: called, value: true}], else: [{op: set, var: bet_out, value: true}]}
end:
  - {id: fold, if_x: "folded is not None", result: score, returns_x: "[-stake[p] if p == folded else stake[1 - p] for p in players]"}
  - {id: showdown, if_x: "called or checks == n_players", result: score,
     returns_x: "[stake[1 - p] if rank(hand[p][0]) > rank(hand[1 - p][0]) else -stake[p] for p in players]"}
```

**Campaign: scoped subflow, reset, reward after a won scenario.** The `turns` loop has no `until_x`:
the scoped end conditions stop the scenario; `reward` then reads `results.get('scenario')`.

```yaml
game: trek
label: Trek
num_players: 1
constants: {SCENARIOS: 3}
state:
  vars:
    played: {init: 0, persist: campaign}
    gold: {init: 0, persist: campaign}
    hp: {init: 2}                                    # back to 2 at each reset
    dist: {init: 0}
flows:
  scenario:
    id: scenario
    kind: sequence
    children:
      - {id: setup, kind: step, do: start_scenario}
      - {id: turns, kind: loop, children: [{id: turn, kind: step, actor_x: "0", do: [advance, rest]}]}
flow:
  id: campaign
  kind: loop
  until_x: "played >= SCENARIOS"
  children: [{id: play, kind: subflow, ref: scenario}, {id: reward, kind: step, do: reward}]
actions:
  start_scenario: {effect: [{op: reset}]}
  advance:
    effect:
      - {op: roll, die: [0, 1, 2], bind: d}
      - {op: add, var: dist, amount_x: d}
      - {op: add, var: hp, amount: -1}
  rest: {pre_x: "hp < 2", effect: [{op: add, var: hp, amount: 1}]}
  reward:
    effect:
      - {op: if, cond_x: "results.get('scenario') == 'win'", then: [{op: add, var: gold, amount: 1}]}
      - {op: add, var: played, amount: 1}
end:
  - {id: won, scope: scenario, if_x: "dist >= 3", result: win}
  - {id: lost, scope: scenario, if_x: "hp <= 0", result: loss}
  - {id: campaign_over, if_x: "played >= SCENARIOS", result: score, returns_x: "[gold]"}
```

**Window: node that only opens it, counterspell, end after it closes.** The counter binds its
target in `cost` (cost ops see `stack`): the topmost opponent item not yet cancelled. A target is
marked `cancelled` only when the counter resolves. `end_event` + trigger sets a flag that the end
check right after it reads (a forced step after the window works too).

```yaml
game: duel
label: Duel
num_players: 2
state:
  vars:
    hp: {scope: player, init: 2}
    bolts: {scope: player, init: 1}
    counters: {scope: player, init: 1}
    closed: {init: false}
priority:
  protocol: {first_x: "0", resolution: lifo_stack}
  windows: {fight: {allows: [fast]}}
flow:
  id: game
  kind: sequence
  children:
    - {id: fight, kind: sequence, children: [], window: fight, end_event: fight_over}
actions:
  bolt:
    speed: fast
    pre_x: "bolts[actor] > 0"
    cost: [{op: add, var: "bolts[actor]", amount: -1}]
    effect: [{op: add, var: "hp[1 - actor]", amount: -1}]
  counter:
    speed: fast
    pre_x: "counters[actor] > 0 and any(s['actor'] != actor and not s['cancelled'] for s in stack)"
    cost:
      - {op: add, var: "counters[actor]", amount: -1}
      - {op: let, bind: target, value_x: "max(i for i, s in enumerate(stack) if s['actor'] != actor and not s['cancelled'])"}
    effect: [{op: cancel, target_x: target}]
triggers:
  - {id: close, event: fight_over, do: [{op: set, var: closed, value: true}]}
end:
  - {id: closed, if_x: closed, result: score, returns_x: "[hp[p] - hp[1 - p] for p in players]"}
```


<!-- https://tabletwin.com/docs/reference.md -->

# Model reference

Every key of a Tabletwin game model, layer by layer. A model is one YAML file. The engine plays it
(in the [player](https://tabletwin.com/play/) and in the validator's test games); the
[validator](https://tabletwin.com/validate/) checks it. This page describes what both actually do.

Related pages:
- [expressions.md](https://tabletwin.com/docs/expressions/): the expression language used in every `_x` field, and which
  names are in scope where.
- [board-geometry.md](https://tabletwin.com/docs/board-geometry/): `boards` and `functions` in depth.
- [engine.md](https://tabletwin.com/docs/engine/): how a model is run, step by step.
- [guide.md](https://tabletwin.com/docs/guide/): how to turn a rulebook into a model.
- [cheatsheet.md](https://tabletwin.com/docs/cheatsheet/): the essentials of this page on one page, with complete patterns.
- [tactics.md](https://tabletwin.com/docs/tactics/): tactic files (players as a separate layer).
- [schema.json](https://tabletwin.com/models/docs/schema.json): JSON Schema for editors; the
  validator also uses it to report unknown keys. Where it disagrees with this page, this page wins.

In the tables, **E** means the engine uses the field, **V** means it is for people and the
viewer only. A V field never changes how the game plays.

## 1. Conventions

### Text and expression (`_x`)

Most fields that carry rules come in two forms:

| Form | Example | Meaning |
|---|---|---|
| `field` with text | `pre: "has enough gold"` | For people and the viewer. The engine cannot run it. |
| `field_x` with an expression | `pre_x: "gold[actor] >= 3"` | What the engine runs. |
| `field` with a number, list, bool or dict | `amount: -1`, `die: [1, 2, 3]` | A literal value, used as is (only for the fields listed below). |

If both are present, `_x` wins. An `_x` field may also hold a YAML number or boolean
(`if_x: true`); it is turned into text and evaluated.

**Fields that accept a literal** (a non-text value without `_x`): `value`, `amount`, `what`,
`at`, `n`, `die`, `options`, `min`, `max`, `items`, `until` (of `repeat`), `target`, `of`.
For these, a **text** value without `_x` is an error at run time:
`field 'what' is text without what_x`. The exception is `value` in `set` and `let`: there a
text is a literal string (`value: open` stores `'open'`; `value: "x + 1"` stores the text
`'x + 1'`).

So to place the string `'gold'` in a zone, write `what_x: "'gold'"`, not `what: gold`.

**Fields that only work as `_x`.** What the engine does when only the text form is present:

| Text field without `_x` | Engine |
|---|---|
| `pre` (action), `if` (trigger), `cond` (if op), `when` (branch case), `first` (priority protocol), `of` (exec), `change` (modifier, modify), `p` (outcome) | Error `NotExecutable` when reached |
| `over`, `until` (loop) | Ignored: the loop runs its children once per round, and never stops by itself |
| `actor` (step), `controller` (trigger) | Ignored: no actor / the event's actor decides |
| `if` (end condition) | The condition is skipped |
| `if` (modifier) | Ignored: the modifier always applies |
| `filter` (search) | Ignored: every item is a candidate |
| `who` (end condition) | Ignored, so `who_x` is missing: error when a competitive `win`/`loss` fires, and at the first end check for `eliminate` |

The validator counts most of these places as gaps (its list "What the engine still misses", see
[§20](#20-validator)).

### Paths

| Kind | Syntax | Example |
|---|---|---|
| Variable path (`var` in `set`, `add`) | `name` or `name[expr]` | `score[current]`, `pieces['e4']` |
| Zone path (`from`, `to`, `zone`) | `name` or `name[expr]` | `deck`, `hand[actor]` |

The part in `[ ]` is an expression, evaluated with the local names of the op. A zone with
`owner: player` must be indexed (`hand[1]`); without an index the engine raises
`zone 'hand' belongs to a player; write hand[player]`.

### Players

Players are the integers `0 … num_players − 1`. In expressions, `players` is that list and
`n_players` its length.

### YAML 1.1 pitfalls

Models are read as YAML 1.1:
- `yes`, `no`, `on`, `off` (lower, title or upper case) are booleans, like `true` and `false`. A key `on:` becomes `true` and is rejected
  (`key true is not text; put it in quotes`). That is why triggers use `event:`, not `on:`, and
  branches use `switch:`. `options: [yes, no]` gives `[True, False]`.
- `010` is octal (8), `1:30` is sexagesimal (90). Quote such values.
- Dates (`2024-01-01`) stay text.
- Keys must be text; `<<` merge keys work.

## 2. Top-level keys

| Key | Type | | Meaning |
|---|---|---|---|
| `game` | text | V | Short id (lower case, hyphens) |
| `label` | text | V | Display name |
| `num_players` | integer | E | Number of players (default 2) |
| `mode` | `competitive` / `cooperative` | E V | How end conditions pay out (default `competitive`; anything else is an error) |
| `players` | text | V | E.g. `"2–4 players"` |
| `summary` | text | V | Two or three sentences about the game |
| `demonstrates`, `scope`, `description` | text | V | What the model shows and what it does (not) cover. This `scope` is unrelated to `scope` in `end` |
| `utility` | `{min, max}` | V | Range of a player's return. The engine does not use it |
| `constants` | dict | E | [§3](#3-constants) |
| `boards` | dict | E | [§4](#4-boards) |
| `functions` | dict | E | [§5](#5-functions) |
| `state` | dict | E | [§6](#6-state) |
| `flow` | node | E | The main flow. **Required** by the engine ([§9](#9-flow-and-flows)) |
| `flows` | dict | E | Named subflows |
| `actions` | dict | E | [§10](#10-actions) |
| `triggers` | list | E | [§14](#14-triggers) |
| `modifiers` | list | E | [§15](#15-modifiers) |
| `priority` | dict | E | [§13](#13-priority-windows) |
| `outcomes` | dict | E | [§17](#17-outcomes) |
| `agents` | dict | E | [§18](#18-agents) |
| `content` | dict | E | [§16](#16-content) |
| `code` | dict | E | [§21](#21-code) |
| `open_questions` | list | V | [§22](#22-open_questions) |
| `end` | list | E | [§19](#19-end) |

The JSON Schema also requires `game`, `label`, `actions` and `end`, and allows no other top-level
keys.

## 3. `constants`

`{name: value}`. Fixed numbers, lists and tables. Every expression sees them under their name.
Use upper case. Numbers you may want to change later (a target score, a hand size) belong here:
the site always runs a model with the values written in it, so you change them in one place.

```yaml
constants:
  GOAL: 20
  CARDS: [{id: ace, value: 1}, {id: king, value: 13}]
```

Constants are model data: they are never changed during play. A dict from `constants` placed in
a zone with `place` stays read-only; use `create` to make an instance ([§7](#7-instances)).

## 4. `boards`

`{name: board}`. Fixed boards with geometry: square or hex cells, neighbours, holes, walls.
Expressions call board functions with the board name as first argument
(`neighbours('map', cell)`). Full description in [board-geometry.md](https://tabletwin.com/docs/board-geometry/).

```yaml
boards:
  board: {kind: square, width: 8, height: 8, names: letters, neighbours: 8}
```

## 5. `functions`

`{name: function}`. Your own pure functions in the expression language.

| Field | | Meaning |
|---|---|---|
| `params` | E | List of parameter names (`^[A-Za-z][A-Za-z0-9_]*$`). `name?` is optional (default `None`). Call by position or by name |
| `let` | E | `{name: expression}`, evaluated in order; each sees the parameters and earlier `let`s |
| `x` | E | The result (required) |
| `text`, `note` | V | Explanation |

```yaml
functions:
  other:
    params: [p]
    x: "1 - p"
```

A function sees its parameters, its `let`s and the global part of the scope (constants, state,
derived values, board functions, other functions; recursion up to 100 calls deep). It does not
see the caller's local names (`actor`, `self`, bound names): pass them as arguments. Its name
must not clash with a constant, variable, zone, derived value, builtin, board function or
reserved name (`modified content players n_players eliminated results None`). See
[board-geometry.md](https://tabletwin.com/docs/board-geometry/#3-own-functions).

## 6. `state`

### `state.entity_types`

`{name: {attrs: {name: type}, extends?: name, note?}}`. **V** only: describes the kinds of things,
and `holds` of a zone may name one. Things in zones are plain values (text, number or dict).

### `state.zones`

`{name: zone}`. Places where things lie. In expressions a zone is a list; a zone with
`owner: player` is a list of lists (`hand[1]`). **Index 0 is the top.**

| Field | | Default | Meaning |
|---|---|---|---|
| `owner` | E V | `global` | `global`: one list. `player`: one list per player, path `name[i]`. `team`, `entity`: descriptive (treated as global) |
| `visibility` | E V | `public` | Who sees what is drawn into it: `public` everyone, `owner` only the owning player, `hidden` nobody |
| `shuffled` | E V | `false` | `true`: drawing from it is random (a chance node); order is unknown except a known top and bottom ([§8](#8-stack-order)) |
| `persist` | E V | – | `campaign`: kept by `reset`. Any other value is a validator error |
| `drawn_from` | E | – | For a hidden zone: the shuffled zone its cards come from. A player that looks ahead redistributes its cards together with the unknown part of that zone, so it does not peek. See [tactics.md](https://tabletwin.com/docs/tactics/#look-ahead-search) |
| `init_x` | E | empty | Initial content (a list; for `owner: player` a list of lists). Dicts become instances ([§7](#7-instances)) |
| `kind` | V | – | `grid`, `hexgrid`, `graph`, `plane`, `stack`, `set`, `bag`, `slot`, `track` |
| `holds`, `size`, `label`, `note` | V | – | Descriptive |

```yaml
state:
  zones:
    deck: {kind: stack, visibility: hidden, shuffled: true, init_x: "list(CARDS)"}
    hand: {kind: set, owner: player, visibility: owner}
    discard: {kind: stack}
```

`init_x` of a zone sees the constants, `content`, `players`, `n_players`, board and own functions,
and all variables. It does not see other zones.

### `state.vars`

`{name: var}`.

| Field | | Default | Meaning |
|---|---|---|---|
| `scope` | E V | `global` | `player`: one value per player (a list; path `name[i]`). `team`, `entity`: descriptive |
| `init` | E | `None` | Literal initial value (`null` is `None`). With `scope: player` and a non-list value, every player gets a copy |
| `init_x` | E | – | Initial value as an expression; sees constants, `content`, `players`, `n_players`, board and own functions, and the variables declared **above** it |
| `persist` | E V | – | `campaign`: kept by `reset` |
| `type` | V | – | `int`, `real`, `bool`, `enum`, `ref`, `set`, `list`, `dict`, `str` (descriptive) |
| `range`, `label`, `note` | V | – | Descriptive |

```yaml
state:
  vars:
    score: {scope: player, type: int, init: 0}
    current: {type: ref, init: 0}
    pool_size: {init_x: "2 * n_players"}
```

### `state.derived`

`{name: "expression"}` or `{name: {text, x}}`. Named values, computed each time an expression
uses them (directly or through another derived value). A derived value may use derived values
declared **above** it. It is computed in the scope of the expression that uses it; write it so
that it needs only the global state.

```yaml
state:
  derived:
    total: "sum(score)"
    best: {text: "highest score so far", x: "max(score)"}
    leaders: "[p for p in players if score[p] == best]"
```

## 7. Instances

A dict in a zone is an **instance**: a thing with its own state that can change during play
(damage, exhausted, tokens). Instances come from `create` with a dict, and from a zone's
`init_x` that yields dicts.

- Each instance gets a unique `uid` (1, 2, 3, … in order of creation).
- If the source dict is model data (from `constants` or `content`), the instance copies its
  simple fields (numbers, text, booleans, `None`) and refers to the source under the key
  **`origin`** (`inst['origin']['effect']`). Nested fields such as `effect` or `triggers` are not
  copied. A dict built by an expression is copied whole.
- `with_x` on `create` adds initial state: `with_x: "{'damage': 0}"`.
- Read: `c['damage']`, `c.get('exhausted')`, `c['origin']['effect']`.
- Write: `{op: add, of_x: c, attr: damage, amount: 2}`,
  `{op: set, of_x: c, attr: exhausted, value: true}`. Changing model data itself is an error:
  `'X' is model data; make an instance with create first`.
- In options, chance outcomes and observations an instance is named by its `label`, else `id`,
  else `uid`. Two instances with the same label are indistinguishable to a player.
- `exec` needs a dict with `effect`; for an instance use `of_x: "c['origin']"`.

```yaml
- {op: create, what_x: "content['units']['archer']", to: "army[actor]", with_x: "{'damage': 0}", bind: u}
- {op: add, of_x: u, attr: damage, amount: 1}
```

## 8. Stack order

Index 0 of a zone is the **top**: `draw` and `look` take from there. Inserting without `position`
appends at the end (the bottom).

For a zone with `shuffled: true` the order is unknown, except for a known top and a known
bottom:
- known on top: after `look`, or after `place`/`create`/`move`/`draw` with `position: top`;
- known at the bottom: after `place`/`create`/`move`/`draw` with `position: bottom`;
- the rest is unordered; a chance node decides which card it is when it is drawn or looked at;
- something inserted without `position` (or `position: random`) goes among the unknown cards;
- `shuffle` makes all of it unknown again.

Drawing takes the known top first, then (chance node, uniform) one of the unknown cards, and
only when those are gone the known bottom. For a zone without `shuffled`, `shuffle` does nothing
and `draw` always takes index 0.

## 9. `flow` and `flows`

`flow` is the main flow: one node, usually a `sequence` or `loop`. `flows` is `{name: node}`
with named subflows (used by `subflow` nodes and the `run` op).

| Field | On | | Meaning |
|---|---|---|---|
| `id` | all | E V | Unique in the whole model (validator error on duplicates) |
| `kind` | all | E V | `sequence`, `loop`, `branch`, `step`, `subflow` |
| `label` | all | V | Display name (else `id`) |
| `children` | sequence, loop | E V | List of nodes, run in order |
| `over_x` | loop | E | List (or other iterable) of values to run the children for, evaluated at the start of each round. Usually `players` |
| `as` | loop | E | Variable set to each value of `over_x` before the children run. Declare it in `state.vars` (a validator error otherwise): the engine creates an undeclared one only when the loop first sets it, so it does not exist before that, and `reset` leaves it alone |
| `until_x` | loop | E | Stop condition, tested before each round. Without it the loop repeats round after round (with `over_x`: all values again, from the first) and never stops by itself; the game ends through `end` |
| `once` | loop | E V | `true`: exactly one round (each value of `over_x` once) |
| `over`, `until` | loop | V | Text for people |
| `order` | loop | V | `fixed`, `clockwise_from_first`, `initiative`, `simultaneous`, `deck_order`, `players_choose` (descriptive; other values are a validator error) |
| `cases` | branch | E V | `[{when, when_x, label, note, children}]`. The first case whose `when_x` is true runs; none true: nothing. A case without `when_x` reached before a match is an error |
| `switch` | branch | V | What the branch looks at (text) |
| `ref` | subflow | E V | Name in `flows` |
| `do` | step | E V | Action name, or a list of action names among which the actor chooses |
| `actor_x` | step | E | Who acts (player index). Needed if more than one action is legal, and for any `choose` in the action without its own `actor_x` |
| `actor` | step | V | Text for people |
| `secret` | step | E | Only the actor sees which action was chosen |
| `visible_to_x` | step | E | Who sees the choice (list of player indexes) |
| `window` | all | E V | A priority window opened after the node: a name from `priority.windows`, or `true` (all speeds) |
| `end_event` | all | E V | Event name (or list) emitted when the node is done, after its window |
| `note` | all | V | Explanation |

What each kind does:
- **sequence**: children in order.
- **loop**: before each round, if `until_x` is true the loop ends. With `over_x`, the children
  run once per value (with `as` set); without it, once per round. More than 10,000 rounds is an
  error (`loop does not end`). Eliminated players are **not** skipped: filter them yourself
  (`over_x: "[p for p in players if p not in eliminated]"`).
- **branch**: the first case with a true `when_x`. Use `when_x: "True"` for a default case.
- **subflow**: runs `flows[ref]`. `results[ref]` is cleared when it starts; end conditions with
  `scope: ref` apply while it runs ([§19](#19-end)).
- **step**: (1) evaluate `actor_x` (else the actor is `None`); (2) legal actions are those in
  `do` whose `pre_x` is true, with `actor` in scope; (3) none legal: the step is skipped;
  (4) one legal: it runs without a decision; (5) several: a decision for the actor (an error
  without `actor_x`); (6) the action's `cost`, then its `effect`, with the same local names;
  (7) end conditions are checked.

After a node's own work comes its `window`, then its `end_event`s (each followed by an end
check). On a loop both happen once, after the whole loop.

```yaml
flow:
  id: game
  kind: loop
  over_x: players
  as: current
  children:
    - {id: turn, kind: step, actor_x: current, do: [roll, stop]}
```

Flow expressions (`over_x`, `until_x`, `when_x`, `actor_x`, `visible_to_x`) see only the global
part of the scope: no `actor` and no local names. Use the loop variable from `as`.

## 10. `actions`

`{name: action}`.

| Field | | Meaning |
|---|---|---|
| `pre_x` | E | When the action is legal (default: always). Sees `actor` (and `self` for abilities; `window` and `stack` in a window) |
| `cost` | E | Ops run first when the action is played. With `lifo_stack` they run immediately, while `effect` waits on the stack. Same local names as `pre_x`; in a window that includes `stack` as it is before this action is put on it |
| `effect` | E | List of ops |
| `speed` | E V | Makes the action playable in priority windows whose `allows` contains this speed ([§13](#13-priority-windows)). Actions with a speed are usually not in any step |
| `pre`, `actor`, `label`, `note` | V | Descriptive |

```yaml
actions:
  stop:
    pre: the pot is not empty
    pre_x: "pot > 0"
    effect:
      - {op: add, var: "score[current]", amount_x: pot}
      - {op: set, var: pot, value: 0}
```

In `pre_x`, `cost` and `effect`, `actor` is the player who acts: the step's `actor_x`, in a
window the player who has priority, and when an effect resolves from the stack the player who
played it. Names bound in `cost` (by `choose`, `let`, …) are still there in `effect`, also when the
effect resolves later from the stack.

## 11. Ops

An effect is a list of ops, run top to bottom. Each op is a dict with `op` and its fields.
Local names: `bind` in `choose`, `roll`, `let`, `look`, `search`, `create` adds a local name for
the rest of the effect. `if` and `repeat` share the local names with the surrounding effect;
`for_each`, `emit` (impact and triggers), `exec` and `sample` work on a copy, so names bound
inside do not leak out.

| Op | Fields | Summary |
|---|---|---|
| [`set`](#set) | `var` or `of_x`+`attr`; `value`/`value_x` | Set a variable or an instance attribute |
| [`add`](#add) | `var` or `of_x`+`attr`; `amount`/`amount_x` | Add to a variable or attribute |
| [`let`](#let) | `bind`, `value`/`value_x` | Bind a local name |
| [`place`](#place) | `what`/`what_x`, `to`, `at`/`at_x`, `position` | Put a value in a zone |
| [`create`](#create) | `what`/`what_x`, `to`, `n`/`n_x`, `with_x`, `position`, `bind` | Add new instances |
| [`move`](#move) | `what`/`what_x`, `from`, `to`, `position` | Move items between zones |
| [`destroy`](#destroy) | `what`/`what_x`, `from` | Remove an item from play |
| [`draw`](#draw) | `from`, `to`, `n`/`n_x`, `visible_to_x`, `position` | Take the top card(s) |
| [`shuffle`](#shuffle) | `zone` | Make a shuffled zone's order unknown again |
| [`look`](#look) | `from`, `n`/`n_x`, `bind`, `actor_x`, `visible_to_x` | Look at the top card(s) |
| [`search`](#search) | `from`, `bind`, `filter_x`, `as`, `actor_x`, `min`/`max`, `visible_to_x` | Look through a zone and pick |
| [`reveal`](#reveal) | `what`/`what_x`, `visible_to_x` | Show a value |
| [`roll`](#roll) | `die`/`die_x`, `bind`, `visible_to_x` | Uniform chance node |
| [`choose`](#choose) | `options`/`options_x`, `bind`, `actor_x`, `secret`, `visible_to_x`, `min`/`max` | A decision |
| [`if`](#if) | `cond_x`, `then`, `else` | Conditional |
| [`for_each`](#for_each) | `items`/`items_x`, `as`, `body` | Loop over values |
| [`repeat`](#repeat) | `until`/`until_x`, `body` | Loop until a condition |
| [`emit`](#emit) | `event`, `impact` | Fire an event (triggers) |
| [`sample`](#sample) | `model` | Draw from an outcome model |
| [`exec`](#exec) | `of_x`, `content` | Run a content item's effect |
| [`run`](#run) | `flow` | Run a named flow inside the effect |
| [`window`](#window) | `name` | Open a priority window |
| [`cancel`](#cancel) | `target`/`target_x` | Cancel a stack item |
| [`modify`](#modify) | `stat`, `change_x`, `layer`, `if_x`, `until` | Add a temporary modifier |
| [`reset`](#reset) | `scope` | Campaign: start a new scenario |
| [`call`](#call) | `code` | Escape hatch: code outside the model (not executable) |
| [`say`](#say) | `actor`, `channel`, `constraint`, `bind`, `agent` | Free speech (not executable yet) |

Any other `op` is a validator error and `NotExecutable` at run time. Every op may carry a `note`
(V).

### set

| Field | Default | Meaning |
|---|---|---|
| `var` | – | Variable path. Required unless `attr` is given |
| `of` / `of_x` | – | With `attr`: the instance to change |
| `attr` | – | Attribute name (literal) |
| `value` / `value_x` | – | New value. A text `value` is a literal string |

```yaml
- {op: set, var: phase, value: combat}          # the string 'combat'
- {op: set, var: "score[actor]", value_x: "score[actor] * 2"}
- {op: set, of_x: target, attr: exhausted, value: true}
```

### add

| Field | Default | Meaning |
|---|---|---|
| `var` | – | Variable path. Required unless `attr` is given |
| `of` / `of_x`, `attr` | – | Add to an instance attribute; a missing (or falsy) attribute counts as 0 |
| `amount` / `amount_x` | – | Added with `+` (negative subtracts; on a list variable `+` concatenates) |

```yaml
- {op: add, var: "gold[actor]", amount: -3}
- {op: add, of_x: unit, attr: damage, amount_x: "hit['power']"}
```

### let

| Field | Meaning |
|---|---|
| `bind` | Local name (required) |
| `value` / `value_x` | Value. A text `value` is a literal string |

```yaml
- {op: let, bind: target, value_x: "hand[actor][0]"}
```

### place

| Field | Default | Meaning |
|---|---|---|
| `what` / `what_x` | – | The value |
| `to` | – | Zone path |
| `at` / `at_x` | – | Index: replaces the element at that index (negative counts from the end) |
| `position` | – | Without `at`: `top`, `bottom`, `random` or none ([§8](#8-stack-order)). Any other value is an error |

`place` does not make an instance; use `create` for things with their own state.

```yaml
- {op: place, what_x: "'X'", to: grid, at_x: square}
```

### create

| Field | Default | Meaning |
|---|---|---|
| `what` / `what_x` | – | The thing; a dict becomes a new instance ([§7](#7-instances)) |
| `to` | – | Zone path |
| `n` / `n_x` | 1 | Number of copies |
| `with_x` | – | Dict of extra initial state, merged into each instance |
| `position` | – | `top`, `bottom`, `random` or none |
| `bind` | – | Local name for the (last) instance created |

```yaml
- {op: create, what_x: "content['tokens']['wound']", to: "wounds[actor]", n: 2}
```

### move

| Field | Default | Meaning |
|---|---|---|
| `what` / `what_x` | – | An item or a list of items |
| `from`, `to` | – | Zone paths |
| `position` | – | `top`, `bottom`, `random` or none |

For each item the first equal element (deep equality) in `from` is removed and inserted into
`to`. An item that is not in `from` is an error: `move: 'X' is not in hand[actor]` (the path as
written).

```yaml
- {op: move, what_x: card, from: "hand[actor]", to: discard}
```

### destroy

| Field | Default | Meaning |
|---|---|---|
| `what` / `what_x` | – | The item |
| `from` | – | Zone path. Without it: the first zone (in declaration order) that holds the item |

Not found is an error. Adds the event `destroy:<label>`.

### draw

| Field | Default | Meaning |
|---|---|---|
| `from`, `to` | – | Zone paths |
| `n` / `n_x` | 1 | Number of cards; stops early when `from` is empty |
| `visible_to_x` | destination | Who sees the drawn card. Default: from the destination's `visibility` (`public` everyone, `owner` its owner, `hidden` nobody) |
| `position` | – | Where it goes in `to` |

From a `shuffled` zone without a known top and with more than one unknown card, each draw is a
chance node (uniform over the unknown cards; [§8](#8-stack-order)). Otherwise the top card is
taken.

```yaml
- {op: draw, from: deck, to: "hand[actor]", n: 2}
```

### shuffle

| Field | Meaning |
|---|---|
| `zone` | Zone path. Without it the op does nothing |

Forgets the known top and bottom of a `shuffled` zone. On a zone without `shuffled` it does
nothing.

### look

| Field | Default | Meaning |
|---|---|---|
| `from` | – | Zone path |
| `n` / `n_x` | 1 | How many cards from the top |
| `bind` | – | Local name for the list of cards seen |
| `actor_x` | the local `actor` | Who looks |
| `visible_to_x` | `[actor]` | Who sees them (everyone if there is no actor) |

On a `shuffled` zone, chance nodes fix the unknown cards among the top `n`; afterwards they are
the known top.

### search

| Field | Default | Meaning |
|---|---|---|
| `from` | – | Zone path |
| `bind` | – | Local name for the chosen item (required) |
| `filter_x` | all | Which items may be chosen; the item is named `it` (or `as`) |
| `as` | `it` | Name of the item in `filter_x` |
| `actor_x` | the local `actor` | Who searches |
| `min`, `max` (and `_x`) | – | Choose a subset, as in `choose`; `bind` gets a list |
| `visible_to_x` | `[actor]` | Who sees the choice |

The searcher sees the whole zone (an observation for the actor only). Then a `choose` among the
matching items follows (one match: no decision). No match: `bind` is `None`, or `[]` with
`min`/`max`. `search` does not move or shuffle anything; add `move` and `shuffle` yourself.

```yaml
- {op: search, from: deck, filter_x: "it['type'] == 'ally'", bind: found}
- {op: if, cond_x: "found is not None", then: [{op: move, what_x: found, from: deck, to: "hand[actor]"}]}
- {op: shuffle, zone: deck}
```

### reveal

| Field | Default | Meaning |
|---|---|---|
| `what` / `what_x` | – | The value shown |
| `visible_to_x` | everyone | Who sees it |

Adds an observation. The zone's visibility does not change.

### roll

| Field | Default | Meaning |
|---|---|---|
| `die` / `die_x` | – | List of faces (numbers, text or dicts) |
| `bind` | – | Local name for the face rolled |
| `visible_to_x` | everyone | Who sees the result |

A chance node; each face is equally likely. A random card from a hand: `die_x: "hand[p]"`.

```yaml
- {op: roll, die: [1, 2, 3, 4, 5, 6], bind: pips}
```

### choose

| Field | Default | Meaning |
|---|---|---|
| `options` / `options_x` | – | The options (a list or other iterable) |
| `bind` | – | Local name for the chosen option (required) |
| `actor_x` | the local `actor` | Who chooses |
| `secret` | `false` | Only the chooser sees the choice |
| `visible_to_x` | everyone | Who sees the choice |
| `min` / `min_x`, `max` / `max_x` | – | Subset choice (see below) |
| `agent` | – | Name in `agents` (validator checks it exists; the engine ignores it) |

One option: no decision (the player lists it under "automatic"). No options: an error. More than
one option and no actor: `NotExecutable`.

**Subset.** With any of `min`, `max`, `min_x`, `max_x`, the chooser picks elements one at a time,
in the order of `options`: each time from the elements after the last one picked (only those
that still leave enough elements to reach `min`), plus the option `done` once at least `min` are
chosen. Defaults: `min` 0, `max` the number of options. It stops at `max`, at `done`, or when no
candidates are left. `bind` gets the list. No options and `min` 0 gives `[]`; fewer than `min`
available is an error. Each element is its own decision, at place `<place> · 1`, `· 2`, …

```yaml
- {op: choose, options_x: "hand[actor]", bind: discards, min: 0, max: 2}
```

### if

| Field | Meaning |
|---|---|
| `cond_x` | Condition (required; `cond` alone is an error) |
| `then`, `else` | Lists of ops; `else` optional |

### for_each

| Field | Default | Meaning |
|---|---|---|
| `items` / `items_x` | – | Values to loop over, evaluated once at the start |
| `as` | `it` | Local name of the current value |
| `body` | – | Ops, run once per value with a copy of the local names |

```yaml
- op: for_each
  items_x: "[p for p in players if p != actor]"
  as: p
  body: [{op: add, var: "gold[p]", amount: 1}]
```

If `items_x` is a zone itself (`hand[actor]`) and the body moves things out of that zone, the
loop skips items. Loop over a copy: `items_x: "list(hand[actor])"`.

### repeat

| Field | Meaning |
|---|---|
| `until` / `until_x` | Tested before each pass; the body runs while it is false |
| `body` | Ops (same local names as the surrounding effect) |

More than 10,000 passes is an error (`repeat does not end`).

### emit

| Field | Meaning |
|---|---|
| `event` | Event name (literal text; there is no `event_x`) |
| `impact` | Optional ops: what the event itself does |

Order: triggers with `timing` `when`/`before`; then `instead` triggers (the first one that fires
replaces the impact); then the `impact` (if not replaced); then `after` triggers. Afterwards,
temporary modifiers with `until` equal to this event expire. Triggers see the local names at the
`emit` plus `event`. A chain of more than 50 nested emits is an error. See
[§14](#14-triggers).

```yaml
- op: emit
  event: attack
  impact: [{op: add, of_x: target, attr: damage, amount_x: power}]
```

### sample

| Field | Meaning |
|---|---|
| `model` | Name in `outcomes` |
| `inputs` | Text for people (the engine passes the local names instead) |

Evaluates the model's `derived_x` and `p_x`, makes a chance node over its outcomes, adds the
event `<model>:<outcome id>` and runs that outcome's `effect`. See [§17](#17-outcomes).

### exec

| Field | Meaning |
|---|---|
| `of_x` | The content item (a dict with `effect`). Required |
| `content` | Catalogue path for the validator (e.g. `cards.*`); the engine ignores it |

Runs the item's `effect` with `self` set to the item, in place `content <id>`. Adds the event
`exec:<id>`. An item with `status: missing` or without `effect` is `NotExecutable`.

### run

| Field | Meaning |
|---|---|
| `flow` | Name in `flows` |

Runs the named flow inside this effect, with its own cursor. `results[flow]` is cleared first;
end conditions with `scope: flow` apply while it runs.

### window

| Field | Meaning |
|---|---|
| `name` | Name in `priority.windows`; without it all speeds are allowed |

Opens a priority window from inside an effect. The window sees the op's local names (and
`first_x` is evaluated with them). See [§13](#13-priority-windows).

### cancel

| Field | Meaning |
|---|---|
| `target` / `target_x` | Index in `stack` of the innermost open window (0 is the bottom; −1 the top). `None` does nothing; an index out of range is an `IndexError` |

Sets `cancelled: true` on that stack item **when the op runs**: in a `cost` at once, in an `effect`
(the usual place) only when that effect resolves. Until then the target still shows
`cancelled: false`, so two players can both target the same item. Cancelling an item that is
already cancelled is allowed and changes nothing. A cancelled item is removed without effect
when it would resolve (event `cancelled:<action>`; its cost was already paid). Outside an open
window: an error. Only useful with `resolution: lifo_stack`.

Fix the target when the counter is **played**: bind it in `cost` with `let` (cost ops see
`stack`), and cancel it in `effect`. Items below the counter do not move before it resolves, so
the index stays valid. Here the target is the topmost item of another player that is not yet
cancelled:

```yaml
counter:
  speed: fast
  pre_x: "any(s['actor'] != actor and not s['cancelled'] for s in stack)"
  cost:
    - {op: let, bind: target, value_x: "max(i for i, s in enumerate(stack) if s['actor'] != actor and not s['cancelled'])"}
  effect: [{op: cancel, target_x: target}]
```

A bare `target: -1` in `effect` means "the item directly below this counter when it resolves"
(the counter itself is already off the stack), which may be your own item or one that is already
cancelled.

### modify

| Field | Default | Meaning |
|---|---|---|
| `stat` | – | Which quantity (required) |
| `change_x` | – | New value; `value` is the value so far (required) |
| `layer` | 0 | Order among modifiers |
| `if_x` | – | Only active while true |
| `until` | – | Event at which the modifier expires; without it, it lasts until `reset` |

Adds a temporary modifier. The local names at the time of `modify` (except `stack`) are kept and
visible in `if_x` and `change_x`; `self` (if any) is kept as its content item. See
[§15](#15-modifiers).

```yaml
- {op: modify, stat: attack, change_x: "value + 2 if who == actor else value", until: round_end}
```

### reset

| Field | Default | Meaning |
|---|---|---|
| `scope` | `scenario` | Label only (event `reset:<scope>`) |

Campaign: every variable and zone without `persist: campaign` gets its initial value again
(`init_x` is recomputed); `eliminated` and temporary modifiers are cleared. `results` is kept.

### call

| Field | Meaning |
|---|---|
| `code` | Name in `code` |

Escape hatch: marks a place where the work would be done by code outside the model
(`code.<name>`). A model cannot bring its own code, so a `call` always stops the engine with
`NotExecutable` (`code 'x' → m:f is not implemented`) and counts as a gap. Use it only to record
honestly what the ops cannot express yet; avoid it where the model can express the rule.

### say

Fields `actor`, `channel`, `constraint`, `bind`, `agent`. Free speech for language games. Always
`NotExecutable` for now (`say needs a language agent`); the validator warns without `agent`.

## 12. Places, options and events

The engine names every decision and chance node by its **place** (`where`). Tactics match on it
(`at:`), and the player shows it for every question.

| Place | Where it comes from |
|---|---|
| `step <id>` | Choice between the actions of a step |
| `action <name>` | A `choose`, `roll`, `draw`, `look` or `search` in the action's `effect` (also for abilities) |
| `action <name> (cost)` | The same in its `cost` |
| `<place> · <k>` | The k-th element of a subset choice (`action play · 1`) |
| `window <name>` | A priority decision; `window None` when opened with `window: true` or a `window` op without a name |
| `trigger <id>` | The use/skip decision of an optional trigger, and ops in its `do` (`id` of the trigger, else of its content item) |
| `content <id>` | Ops in an effect run by `exec` |
| `<place> · <model>` | The chance node of a `sample` |
| `<place> · <event>` | Ops in the `impact` of an `emit` |
| `end <node id>` | The `emit` of an `end_event` (only seen in error messages) |

Option labels made by the engine: `pass` (priority window), `done` (end of a subset choice),
`use` / `skip` (optional trigger). Other options are labelled by their value: text as is, an
instance by `label`/`id`/`uid`, anything else in Python notation.

Events recorded by the engine (the player shows them after each question; the ones you do not
emit yourself appear under "messages"):

| Event | When |
|---|---|
| `<event>` | Every `emit` (including `end_event`s) |
| `instead:<trigger id>` | An `instead` trigger fired |
| `stack:<action>`, `resolves:<action>`, `cancelled:<action>` | `lifo_stack`: put on the stack, resolved, removed as cancelled |
| `<model>:<outcome id>` | A `sample` |
| `exec:<id>` | An `exec` |
| `destroy:<label>` | A `destroy` |
| `reset:<scope>` | A `reset` |
| `eliminated:<player>` | An `eliminate` end condition |
| `<scope>:<result>` | A scoped end condition ended a subflow |

## 13. Priority windows

```yaml
priority:
  protocol:
    first: the active player            # V
    first_x: "current"                  # E: who gets priority first
    closes: all_pass_in_succession      # E: or single_pass_each
    resolution: immediate               # E: immediate, nested or lifo_stack
    after_action: next                  # E: next or same
    order: clockwise_from_first         # V
  windows:
    combat: {label: Combat, allows: [fast], note: ...}
```

| Field | | Default | Meaning |
|---|---|---|---|
| `protocol.first_x` | E | the local `actor`, else player 0 | Who gets priority first, and again after each stack item resolves; evaluated once when the window opens. `first` without `first_x` is an error |
| `protocol.closes` | E | `all_pass_in_succession` | `all_pass_in_succession`: closes when all non-eliminated players pass one after the other. `single_pass_each`: a player who passes is out; closes when all are out |
| `protocol.resolution` | E | `immediate` | `immediate`: cost and effect at once. `nested`: the engine treats it like `immediate` (use trigger timing for reactions). `lifo_stack`: cost at once, effect on a stack |
| `protocol.after_action` | E | `next` | Who has priority after a played action: the next player, or the `same` |
| `protocol.order`, `protocol.note` | V | | `clockwise_from_first`, `any_order`, `active_then_clockwise` |
| `windows.<name>.allows` | E | – | List of speeds playable in this window |
| `windows.<name>.label`, `note` | V | | |

How a window runs:
- Candidates are all actions (including content abilities) with a `speed` that the window allows
  (`window: true` or a `window` op without a name: any speed). No candidates: the window closes
  at once.
- Priority passes from player to player (index + 1, wrapping; eliminated players are skipped).
  A player with legal candidates (`pre_x` true) chooses one of them or `pass`; without legal
  candidates the player passes automatically.
- In scope (in `pre_x`, `cost` and `effect` of the candidates): `actor` (who has priority),
  `window` (the window name, `None` for `true`), `stack` (list of `{action, actor, cancelled}`,
  bottom first; empty unless `lifo_stack`), plus the local names of a `window` op. `cost` sees the
  stack before the action is put on it.
- `immediate`/`nested`: cost, effect, then an end check.
- `lifo_stack`: cost runs, the action goes on the stack (event `stack:X`). When all players pass
  with a non-empty stack, the top item resolves: if cancelled it is removed (event `cancelled:X`,
  no effect, no end check); otherwise its effect runs (event `resolves:X`) with `actor` = who
  played it, the names bound in its cost, and `stack` without the item; then an end check. Then
  priority returns to the player `first_x` gave when the window opened (`first_x` is **not**
  evaluated again, even if the effect changed what it reads), and passing starts over
  (`single_pass_each`: everyone is back in). That player passes automatically if they have no
  legal candidate.
- All pass with an empty stack: the window closes (no end check).
- `pass` is reserved: an action named `pass` with a `speed` is a validator error. `speed` and
  `allows` are free names; they only have to match.

## 14. `triggers`

A list of rules that react to `emit` events.

| Field | | Default | Meaning |
|---|---|---|---|
| `id` | E V | – | Unique name; used in the place `trigger <id>` |
| `event` | E V | – | Event name it reacts to (exact match) |
| `timing` | E V | `after` | `when` or `before` (before the impact), `instead` (replaces the impact; only the first that fires), `after` |
| `optional` | E V | `false` | The controller decides `use` or `skip` |
| `controller_x` | E | the event's `actor` | Who decides on an optional trigger. Without it and without an `actor`: an error |
| `if_x` | E | – | Condition, tested right before the trigger would fire (an earlier trigger can disable a later one) |
| `do` | E V | – | Ops |
| `if`, `controller`, `source`, `label`, `note` | V | | `source`: where the rule comes from (card, rule, keyword) |

Within one timing phase: mandatory triggers first, then optional ones; each group in model
order, model triggers before content triggers. In scope: the local names at the `emit`, `event`,
and `self` for a content trigger. A trigger on an `end_event` has only `event`.

```yaml
triggers:
  - id: thorns
    event: attack
    timing: after
    if_x: "target['id'] == 'bramble'"
    do: [{op: add, of_x: attacker, attr: damage, amount: 1}]
```

## 15. Modifiers

A modifier changes a quantity (`stat`) wherever the rules ask for it with
`modified('stat', base, name=value, ...)`.

Static modifiers live in the top-level `modifiers` list and on content items. Temporary ones are
added by the `modify` op.

| Field | | Default | Meaning |
|---|---|---|---|
| `stat` | E V | – | Which quantity. Modifiers without `stat` are ignored |
| `change_x` | E | – | New value; `value` is the value so far. Missing: an error when applied |
| `layer` | E V | 0 | Lower layers first; within a layer the static ones (top-level list first, then content items), then temporary ones in order of creation |
| `if_x` | E | – | Only active while true |
| `until` | E | – | (temporary) expires at this event |
| `id`, `source`, `target`, `change`, `if`, `duration`, `note` | V | | `duration`: `permanent`, `round`, `turn`, `while` |

`modified('stat', base, k=v, ...)`: the extra keyword arguments are local names in `if_x` and
`change_x` (e.g. who attacks). A content modifier also sees `self`, and applies only while its
item's `active_x` is true. Modifiers that refer to each other more than 20 deep are an error.

```yaml
modifiers:
  - {id: veteran, stat: attack, layer: 1, if_x: "who == 0", change_x: "value + 1"}
actions:
  hit:
    effect:
      - {op: add, var: "hp[1]", amount_x: "-modified('attack', 2, who=actor)"}
```

The validator warns when a `stat` is never read with `modified('stat', ...)` (a literal string).

## 16. `content`

Content is the game's material as data: cards, dice, faces, skills. The structure is free:
`{catalogue: {key: item}}`, nested as deep as you like, lists allowed. Expressions see it as
`content`.

```yaml
content:
  cards:
    bolt:
      id: bolt
      label: Lightning Bolt
      status: verified
      text: "Deal 3 damage."
      effect: [{op: add, var: "hp[1 - actor]", amount: -3}]
```

An **item** is a dict with an `id`:

| Field | | Meaning |
|---|---|---|
| `id`, `label` | E V | Identity and name |
| `status` | V | `verified`, `uncertain` or `missing`. The validator warns for every item without one of these |
| `text` | V | The card text in your own words. An item with `text` but no behaviour counts as a gap |
| `effect` | E | Ops, run with `exec` (`self` is the item) |
| `active_x` | E | When the item's `triggers` and `modifiers` apply; `self` is the item. Without it they **always** apply |
| `triggers`, `modifiers` | E V | As in [§14](#14-triggers) and [§15](#15-modifiers), bound to the item |
| `abilities` | E V | Actions on the card itself (`id` unique across all actions and abilities, `speed`, `pre_x`, `cost`, `effect`). Playable in priority windows like any action with `speed`; `self` is the item. Without `speed` never playable (validator warning). The validator rejects them in a step's `do` |
| `keywords` | E V | `"Sentinel, Ranged"` or a list. Their behaviour lives in the rules, which test them, e.g. `'Ranged' in c.get('keywords', '')`. The validator warns for a keyword that no rule expression mentions in quotes |
| `faces` | V | Die faces as `"type number"`; the validator checks that `type` is a key of some `face_types` dict in `content` |
| `source`, `cost`, `requires`, `note` | V | |

Triggers, modifiers and abilities belong to the **item** (the card kind), not to one instance.
With two copies of a card in play, its trigger still fires once per event; `if_x` picks the
right instance through the event's local names (e.g. `card['origin']['id'] == self['id']`, where
`card` is a name bound before the `emit`), and
`active_x` limits when the item counts at all (e.g. only while a copy is in play).

## 17. `outcomes`

`{name: model}`. An outcome model replaces physics or skill by a probability distribution.

| Field | | Meaning |
|---|---|---|
| `outcomes` | E V | `[{id, p, p_x, effect, note}]`. The `p_x` must be ≥ 0 and add up to 1 (± 1e-6), else an error. The validator requires `p` (text) on each outcome as well |
| `derived_x` | E | `{name: expression}`, evaluated in order before `p_x`; visible in `p_x` and `effect` |
| `skill` | V | Depends on skill (`skill` marker instead of `chance`) |
| `inputs`, `params`, `derived`, `doc` | V | Descriptive |

```yaml
outcomes:
  shot:
    skill: true
    derived_x: {q: "sigmoid(skill[actor] - DIFFICULTY)"}
    outcomes:
      - {id: hit, p: q, p_x: q, effect: [{op: add, var: "score[actor]", amount: 1}]}
      - {id: miss, p: 1 - q, p_x: "1 - q"}
```

Used by `{op: sample, model: shot}`; the chance node's labels are the outcome ids.

## 18. `agents`

`{name: agent}`.

| Field | | Meaning |
|---|---|---|
| `policy_x` | E | Returns the label of the option to choose. In scope: `options` (list of labels), `decider` (the player), and the global state. A result that is not one of the labels: a random choice |
| `kind` | V | `search`, `heuristic`, `llm`, `human` |
| `roles`, `sees`, `prompt`, `note` | V | Descriptive |

In the player, an agent with `policy_x` appears under Players as "heuristic <name>", next to
random players, "always the first option" and playing seats yourself. Tactic files (see
[tactics.md](https://tabletwin.com/docs/tactics/)) are the other way to describe how someone plays.

```yaml
agents:
  greedy: {kind: heuristic, policy_x: "'stop' if 'stop' in options and pot >= 10 else options[0]"}
```

## 19. `end`

A list of end conditions. At every check they are tested in **list order**, and the first one
that fires ends the game (or, with a `scope`, the subflow); later ones are not tested.
`eliminate` and `continue` never stop the scan.

| Field | | Meaning |
|---|---|---|
| `id` | E V | Name; the reason reported when the game ends |
| `if_x` | E | When the condition holds. Without `if_x` the condition is skipped |
| `result` | E V | `win`, `loss`, `draw`, `score`, `eliminate`, `continue` |
| `who_x` | E | `win`/`loss` in a competitive game: the winner resp. loser (one index; a list, tuple or set is an `ExprError` when the condition fires, and a validator error when `who_x` is obviously one, such as a list literal or comprehension). `eliminate`: an index or a list |
| `returns_x` | E | `score`: list with one number per player |
| `scope` | E V | A name in `flows`: applies only while that subflow runs ([§9](#9-flow-and-flows)) |
| `if`, `who`, `note` | V | Text |
| `check` | V | `immediate`, `end_of_turn`, `end_of_round`, `end_of_scenario` (descriptive) |

**When**: after each step's action (a skipped step has no check), after each action played (or
resolved) in a window, and after each `end_event`. Not halfway through an effect, not after a cost, not after a cancelled
item, not when a window closes, not at the start or end of a loop round.

**What**:
- A condition with `scope` is skipped unless that subflow is running. If it holds and the result
  is `win`, `loss` or `draw`, `results[scope]` is set to the result (event
  `<scope>:<result>`), the subflow ends and the calling flow continues. A `scope` equal to the
  main flow's `id` means the whole game.
- `eliminate`: the players from `who_x` are added to `eliminated` (event `eliminated:<p>`); play
  goes on.
- `continue`: nothing.
- The first other condition that holds ends the game. A `score` (or `eliminate`, `continue`)
  condition with a `scope` is only tested while that subflow runs and then acts as without scope:
  a scoped `score` ends the whole game.

Returns per player:

| Result | Competitive | Cooperative |
|---|---|---|
| `win` | +1 for `who_x`, −1 for everyone else | +1 for everyone |
| `loss` | −1 for `who_x`, +1 for everyone else | −1 for everyone |
| `draw` | 0 for every player | 0 for every player |
| `score` | `returns_x` | `returns_x` |

Several winners (or losers) in a competitive game cannot be expressed with `win`/`loss`: `who_x`
must be one player index. Use `score`, e.g.
`returns_x: "[1 if p in winners else -1 for p in players]"`.

If the main flow finishes without an end condition, the game ends with 0 for everyone and the
reason `flow finished without an end condition`.

```yaml
end:
  - {id: won, if_x: "score[current] >= GOAL", result: win, who_x: current}
  - {id: out, if_x: "any(hp[p] <= 0 for p in players)", result: eliminate, who_x: "[p for p in players if hp[p] <= 0]"}
  - {id: tally, if_x: "rounds_played >= ROUNDS", result: score, returns_x: "[float(s) for s in score]"}
```

## 20. Validator

The [validator page](https://tabletwin.com/validate/) shows the errors and warnings below, the
executability with a few figures, the gaps ("What the engine still misses", per layer), the flow as
a text tree, and the result of 20 random test games. See [engine.md](https://tabletwin.com/docs/engine/#the-validator) for
what each part means.

**Errors** (must fix): unknown `mode`; `persist` other than `campaign`; duplicate flow `id`;
unknown `kind` or `order`; branch without `cases`; `subflow` to a missing flow; loop `as`
variable not declared in `state.vars`; `window` not in
`priority.windows`; a step's action missing from `actions`; unknown op; undeclared zone in
`from`/`to`/`zone`; undeclared `code`, `flow` (run), outcome `model` (sample) or `agent`
(choose/say); `exec` content path that does not exist; `end_event` that is not a name or list of
names; expression syntax errors; invalid board; function name clash, missing `x`, bad `params`
or `let`; unknown trigger `timing`; unknown `resolution` or `closes`; a `speed` action named
`pass`; end `scope` that is not a named flow; competitive `win`/`loss` whose `who_x` obviously
gives several players (a list, tuple or set literal, a comprehension, or `list()`, `sorted()`,
`set()`, `tuple()`); outcome model without outcomes or an outcome
without `p`; ability without `id` or with a name that already exists; undeclared face type;
open question without `question`.

**Warnings**: `drawn_from` to a zone that is not shuffled, or on a public zone; content item
without a valid `status`; ability without `speed`; keyword not used by any rule; board or
function never used; `say` without `agent`; `exec` without `content` or `of_x`; optional
trigger without `controller_x`; speed not allowed by any window; a fast action that is always
playable in a window that is opened (below); modifier `stat` (static or via
`modify`) never read with `modified()`; trigger on an event that is never emitted; action not
used by any step (unless it has `note` or `speed`); flow never called; open question with a
status other than `open`, `assumed`, `answered`; a key the
[JSON Schema](https://tabletwin.com/models/docs/schema.json) does not allow
(`unknown key 'x' at actions.y`: a typo, or a field the engine ignores).

**Always playable** (`action X: always playable in window Y; random players may keep the window
open forever`): the action has a `speed` that window `Y` allows, `Y` is opened somewhere (a
node's `window` or a `window` op; `window: true` allows every speed), and the action has no
`pre`/`pre_x`, no `cost`, and nothing in its `effect` that could end the game: no `set`/`add` of
a variable, and no zone op on a zone, that an end condition's `if_x` reads (also through derived
values and functions), no `emit` that a trigger listens to, no attribute write, and no `run`,
`exec`, `sample`, `call`, `reset` or `say`. Such an action can be played again and again: random
players rarely all pass in succession, and an agent that never passes hits `window does not
close`. Give it a `pre_x` (a resource, once per window) or a `cost`.

**Unknown keys**: the validator walks the model alongside the JSON schema and reports every
key where the schema allows no other keys, with its path. `content` has a free structure and is
not checked; `constants` and other free dicts neither.

The validator does **not** check that a `var` path names a declared variable, nor that
expressions only use known names; those fail at run time, which the test games usually show.

**Figures**:

| Figure | Meaning |
|---|---|
| `executable` | Share of engine-needed fields that have an `_x` or a literal (rules and content together) |
| rules | The same, for flow, actions, triggers, modifiers, priority, outcomes and end |
| content | Share of content items with behaviour (or `text`, or `status: missing`) that are fully executable, with counts; `-` without content |
| steps | Number of step nodes |
| ops | Number of ops in actions, triggers, outcomes and content |
| code | Share of `call` ops |
| open questions | Number of `open_questions` |

**Markers** of a step (shown in the [diagram](https://tabletwin.com/docs/diagram/#markers); from the ops of its actions,
including flows they `run`):
- `choice`: several actions in `do`, or a `choose`, `say` or `search`;
- `chance`: `shuffle`, `roll`, `draw` from a shuffled zone, `look` at a shuffled zone, `sample`
  from a model without `skill`;
- `skill`: `sample` from a model with `skill: true`;
- `hidden`: `choose` with `secret`, `move`/`draw` to an unshuffled zone with visibility `hidden`
  or `owner`, `search`, `look`;
- `window`: a `window` on the step, or a `window` op in its actions (a `window` on any other
  kind of node is not counted);
- `trigger`: an `emit` of an event some trigger listens to;
- `language`: `say`, or `choose` with an `llm` agent;
- `persistent`: `set`/`add` on a persistent variable, `move`/`draw`/`place`/`create` into a
  persistent zone, or `reset`;
- `code`: `call`.

## 21. `code`

`{name: {lang, ref, doc, kind}}`. Describes code the rules would need but the ops cannot express:
`doc` says what it does, `ref` names it (`"module:function"`), `lang` its language. `kind`:
`content` (should really be in `content`) or `algorithm`. A [`call`](#call) to it is never
executable; the share of `call` ops measures what the metamodel does not (yet) express.

## 22. `open_questions`

A list of gaps or ambiguities in the source: what the rulebook does not say, and what the model
assumes. The engine ignores them; the diagram shows them as a gap report, and the profile counts
them.

| Field | | Meaning |
|---|---|---|
| `id` | V | Short unique name (required by the JSON Schema) |
| `question` | V | The question, in one or two sentences. **Required**: missing is a validator error |
| `about` | V | What it concerns: a path in the model (`actions.attack`, `flow.round`, `end.won`) or a short topic (`setup`) |
| `status` | V | `open` (undecided; the default when missing), `assumed` (the model follows an assumption, given in `answer`), `answered` (the source or the designer settled it). Anything else is a validator warning |
| `answer` | V | The assumption or the answer |
| `source` | V | Where the question comes from (rulebook page, FAQ, forum thread) |

The JSON Schema allows no other fields. Write one entry per question; every `assumed` entry should
say in `answer` what the model does.

```yaml
open_questions:
  - {id: q1, about: actions.attack, question: "Can a unit attack twice?", status: assumed, answer: "No", source: "rulebook p. 6"}
  - {id: q2, about: setup, question: "Who starts?", status: open}
```

## 23. Limits

| Limit | Value | Error |
|---|---|---|
| Rounds of one loop | 10,000 | `loop does not end` |
| Passes of `repeat` | 10,000 | `repeat does not end` |
| Iterations of one window | 10,000 | `window does not close` |
| Nested `emit`s | 50 | `trigger chain too deep` |
| Own function call depth | 100 | `more than 100 calls deep` |
| Modifier nesting | 20 | `modifiers for 'x' refer to each other in a cycle` |
| `range()` length | 10,000,000 | `range too large` |

## 24. Tools on the site

| Tool | Use it to |
|---|---|
| [Validator](https://tabletwin.com/validate/) | Check a pasted model (and optionally its [view](https://tabletwin.com/docs/views/)): errors, warnings, executability, gaps, the flow as a tree, 20 random test games. Then "Open in the player" |
| [Player](https://tabletwin.com/play/) | Follow one game question by question, with random players, a heuristic from `agents`, or seats played by hand. "Game (seed)" replays the same game |
| [Diagram](https://tabletwin.com/diagram/) | See the rules as a text tree and a track diagram ("Draw your own model") |

Everything runs in the browser; nothing is uploaded. Playing many games to measure win rates and
comparing variants or tactics are not yet available on the site. See
[engine.md](https://tabletwin.com/docs/engine/#checking-and-running-a-model-on-the-site).


<!-- https://tabletwin.com/docs/expressions.md -->

# Expression language

The language of every `_x` field, of `state.derived`, of `functions` (`let`, `x`), of outcome
`derived_x`, and of `let` in tactics. It is a safe subset of Python expressions: if you can read
Python, you can read it.

An expression has no side effects: it reads the state and returns one value. Changing the state
is done by ops (see [reference.md](https://tabletwin.com/docs/reference/#11-ops)).

## 1. Values

| Kind | Example | Note |
|---|---|---|
| none | `None` | `null` in YAML |
| truth value | `True`, `False` | |
| number | `3`, `-2`, `2.5`, `1e3`, `0x1f`, `0o17`, `0b101`, `1_000` | One number type for integers and decimals |
| text | `'abc'`, `"it's"`, `r'a\n'`, `'''long'''` | |
| list | `[1, 2]` | |
| tuple | `(1, 'x')`, `1,`, `()` | Never equal to a list |
| dict | `{'power': 3}` | **Keys are text** |
| set | `{1, 2}`, `set()` | |
| generator | `(x for x in L)`, `zip(...)`, `enumerate(...)` | Lazy, usable once |
| function | `len`, `modified`, board and own functions | |

`True` and `False` count as 1 and 0 (`True + True == 2`). `1 == 1.0 == True`, and these three
are the same key in a set.

## 2. Syntax

**Allowed:**
- literals as above; adjacent text literals are joined (`'a' 'b'` is `'ab'`);
- lists, tuples, dicts (also `{**d, 'x': 1}`) and sets;
- arithmetic `+ - * / // % **`, unary `-` and `+`;
- comparisons `== != < <= > >=`, also chained (`0 < x <= 3`);
- `in`, `not in`, `is`, `is not`;
- `and`, `or`, `not`, and `x if c else y`;
- indexing `a[i]` and slicing `a[i:j:k]`;
- calls with keyword arguments (`max(L, key=len)`);
- the six methods in [§5](#5-methods);
- comprehensions `[...]`, `{...}`, `{k: v ...}`, with several `for` and `if` clauses and tuple
  unpacking (`for k, v in d.items()`);
- generator expressions, also as the only argument without extra parentheses
  (`sum(x for x in L)`);
- line breaks anywhere (they count as spaces); names with non-ASCII letters.

**Not allowed** (a syntax error naming the construct; the validator reports it, and the engine
when it first evaluates the expression):
- assignment: `=`, `:=`, `+=` and the other augmented forms;
- `lambda`, `yield`, `await`, `async`, and statement keywords (`def`, `import`, …);
- names that start with `_` (also as keyword argument or loop variable);
- attributes other than the six methods (`x.append` is an error);
- bit operators `| & ^ ~ << >>` and `@`;
- `*` and `**` unpacking in calls and lists (`**` inside a dict literal is allowed);
- f-strings, bytes (`b''`), complex numbers (`1j`), `...`;
- comments (`#`), `;`, a lone `!`;
- more than one expression;
- a positional argument after a keyword argument; a generator argument next to other arguments
  without its own parentheses (`sum(x for x in L, 0)`).

Text escapes: `\n \t \r \0 \\ \' \"`, `\xhh`, `\uhhhh`, `\Uhhhhhhhh`, backslash-newline; any other
backslash stays as is. In `r'...'` nothing is escaped.

Since `|` is not allowed, a set union is written `set(list(a) + list(b))`.

## 3. Meaning

- `and`/`or` return an operand, not `True`/`False`: `0 or 'x'` is `'x'`. They evaluate no more
  than needed: `1 and 0 and 1/0` is `0`.
- A comparison chain stops at the first that fails: `1 < 0 < 1/0` is `False`.
- `None`, `False`, `0`, and empty text, lists, tuples, dicts and sets are false; everything else
  is true.
- **Arithmetic:**
  - `/` always divides exactly (`7/2` is `3.5`);
  - `//` rounds down (`-7 // 2` is `-4`);
  - `%` takes the sign of the divisor (`-7 % 3` is `2`);
  - dividing by zero is a `ZeroDivisionError`; so is `0 ** -1`.
- `+` joins texts, lists, or tuples of the same kind. `*` repeats them with an integer.
- **Sets:** `-` gives the difference; `<=`, `<`, `>=`, `>` test subsets. Set elements must be
  hashable: `None`, booleans, numbers, text, tuples of those. A list or dict in a set is a
  `TypeError`.
- **Ordering** (`<` etc., `sorted`, `min`, `max`): numbers with numbers, text with text, or lists
  (or tuples) of the same kind, element by element. Anything else is a `TypeError`.
- **Equality** is deep: lists, tuples, dicts and sets compare by content. A list never equals a
  tuple.
- `is` compares identity; use it only with `None` (`x is None`).
- `in`: element of a list, tuple or set; key of a dict; substring of a text.
- **Indexing:**
  - negative indexes count from the end;
  - a slice out of range gives fewer elements;
  - text is indexed per character (code point);
  - a missing key is a `KeyError`, an index out of range an `IndexError`.
- Iterating over a dict gives its keys.
- **Comprehensions** have their own scope: loop variables do not leak out, and the first `in`
  value is computed outside that scope.
- Generators are lazy: `any(1/x for x in [1, 0])` is `True` without dividing by zero. A
  generator can be consumed only once and has no `len`.

## 4. Built-in functions

These are all the built-in functions; any other name must come from the model.

| Function | Meaning |
|---|---|
| `len(x)` | Length of text, list, tuple, dict or set |
| `any(it)`, `all(it)` | Lazy; stop at the first value that decides |
| `min(...)`, `max(...)` | From one iterable or several arguments; `key=f`, `default=v` (for an empty iterable). On ties the first wins |
| `sum(it, start=0)` | Sum (also lists with `start=[]`); not for text. Numbers are summed with compensation like Python ≥ 3.12: `sum([1, 0.1, 0.2]) == 1.3` |
| `range(n)`, `range(a, b[, step])` | List of integers (at most 10,000,000) |
| `abs(x)` | Absolute value |
| `round(x)`, `round(x, n)` | Half to even (`round(2.5)` is `2`), exact on the decimal value (`round(2.675, 2)` is `2.67`) |
| `sorted(it, key=f, reverse=False)` | Stable; `reverse` keeps equal values in their order |
| `list(x)`, `tuple(x)`, `set(x)` | Convert any iterable (no argument: empty) |
| `dict(x)`, `dict(k=v)` | From a dict, from pairs with text keys, and/or keyword arguments |
| `enumerate(it, start=0)`, `zip(a, b, ...)` | Lazy; yield tuples |
| `int(x)` | Truncates toward zero; text must be an integer (`int('3.5')` is a `ValueError`) |
| `float(x)` | Number or text (`'inf'`, `'nan'` allowed) |
| `str(x)` | Text form (Python notation; see [§10](#10-differences-from-python)) |
| `bool(x)` | Truth value |
| `sigmoid(x)` or `σ(x)` | 1 / (1 + e^−x) |
| `exp(x)`, `sqrt(x)`, `log(x[, base])` | Maths; `log(0)` and `sqrt(-1)` are a `ValueError` (`math domain error`) |

Functions the model or engine adds:

| Function | When | Meaning |
|---|---|---|
| `modified(stat, value, **context)` | Always (not in `init_x`) | `value` after all active modifiers for `stat`; the keyword arguments are names in the modifiers' `if_x` and `change_x`. See [reference.md](https://tabletwin.com/docs/reference/#15-modifiers) |
| `cells`, `directions`, `xy`, `cell`, `step`, `leap`, `ray`, `neighbours`, `distance`, `path`, `path_cost`, `reachable`, `line_of_sight`, `shape` | When the model has `boards` | Board geometry, board name first. See [board-geometry.md](https://tabletwin.com/docs/board-geometry/) |
| Own functions | From `functions` | Called by position or by keyword. See [board-geometry.md](https://tabletwin.com/docs/board-geometry/#3-own-functions) |

## 5. Methods

Only these, and without keyword arguments:

| On | Method |
|---|---|
| dict | `.get(k)`, `.get(k, default)`, `.items()`, `.keys()`, `.values()` |
| list, tuple, text | `.count(x)`, `.index(x)` (`ValueError` if absent; on text `x` must be text) |

`.items()`, `.keys()` and `.values()` return lists. Any other method is an `AttributeError` at
run time if the name is one of the six, and a syntax error otherwise.

## 6. Names in scope

Every expression sees the **global part**:

| Name | Value |
|---|---|
| constants | Under their own name |
| variables, zones | Under their own name (a player zone is a list of lists) |
| derived values | Under their own name, computed when used |
| `players` | `[0, 1, …, n−1]` |
| `n_players` | Number of players |
| `eliminated` | List of eliminated players |
| `results` | `{subflow: result}` with result `'win'`, `'loss'` or `'draw'`, for scoped end conditions |
| `content` | The `content` layer |
| `modified` | See [§4](#4-built-in-functions) |
| board functions, own functions, builtins | See [§4](#4-built-in-functions) |

Then, depending on the place, **local names**:

| Place | Extra names |
|---|---|
| Flow: `over_x`, `until_x`, `when_x`, step `actor_x` and `visible_to_x` | None. Use the loop variable (`as`), which is a global variable |
| End conditions: `if_x`, `who_x`, `returns_x` | None |
| Action `pre_x` | `actor` (the step's actor, or who has priority in a window) |
| Ops in `cost` and `effect` | `actor`, plus every name bound by earlier ops (`bind` of `choose`, `roll`, `let`, `look`, `search`, `create`); names bound in `cost` stay for `effect` |
| `for_each` body | Also the `as` name (default `it`) |
| `search` `filter_x` | Also the item, as `it` (or `as`) |
| In a priority window | Also `window` (its name) and `stack` (list of `{action, actor, cancelled}`, bottom first); for a `window` op also the op's local names |
| `protocol.first_x` | For a window on a node: none. For a `window` op: the op's local names |
| Ability on a content item (`pre_x`, `cost`, `effect`) | As an action, plus `self` (the item) |
| `exec` effect | The local names of the `exec`, plus `self` (the item) |
| Trigger `if_x`, `controller_x`, `do` | The local names at the `emit`, plus `event`; `self` for a content trigger. On an `end_event` only `event` |
| Content `active_x` | `self`, plus the local names of the trigger or modifier being checked |
| Modifier `if_x`, `change_x` | `value` (the value so far), the keyword arguments of `modified()`, `self` for a content modifier, and for `modify` the local names at that time |
| Outcome `derived_x`, `p_x`, `effect` | The local names of the `sample`, plus earlier `derived_x` names |
| Agent `policy_x` | `options` (list of labels), `decider` (the player) |
| Variable `init_x` | Only: builtins, constants, `content`, `players`, `n_players`, `eliminated`, `results`, board and own functions, and variables declared above. No zones, derived values or `modified` |
| Zone `init_x` | As variable `init_x`, with all variables |
| Own function `let`, `x` | Its parameters and earlier `let`s, plus the global part; not the caller's local names |
| Tactic expressions | See [tactics.md](https://tabletwin.com/docs/tactics/) (`me`, `pool`, `chosen`, `o`, `i`, `opts`, `labels`, `where`) |

**Lookup order** when names collide: local names, then variables, then zones, then the global
names. Among the global names: `modified`, own functions, board functions, the reserved names
(`content`, `players`, `n_players`, `eliminated`, `results`), constants, builtins, in that order
of precedence. So a local `cell` hides the board function `cell()`, and a variable `max` hides
the builtin. Pick names that do not collide.

## 7. Twin fields `_x`

A field named `<name>_x` holds an expression; `<name>` without `_x` is text for people (or, for
some fields, a literal value). See [reference.md § Conventions](https://tabletwin.com/docs/reference/#1-conventions) for
which fields accept literals and what happens to text without `_x`.

All expression fields the engine reads:

| Where | Fields |
|---|---|
| Flow node | `over_x`, `until_x`, `actor_x`, `visible_to_x`; case `when_x` |
| Action | `pre_x` |
| Ops | `value_x`, `amount_x`, `of_x`, `what_x`, `at_x`, `n_x`, `with_x`, `die_x`, `options_x`, `min_x`, `max_x`, `actor_x`, `visible_to_x`, `filter_x`, `items_x`, `until_x`, `cond_x`, `target_x`, `change_x`, `if_x` (modify) |
| Trigger | `if_x`, `controller_x` |
| Modifier | `if_x`, `change_x` |
| Content item | `active_x` |
| Priority protocol | `first_x` |
| State | `init_x` (zone, var); `derived` (`x`, or the value itself) |
| Outcome model | `derived_x` (dict of expressions), `p_x` |
| Agent | `policy_x` |
| End condition | `if_x`, `who_x`, `returns_x` |
| Function | `let` (dict of expressions), `x` |

An `_x` value may be a YAML string, number or boolean. The validator compiles every `_x` field
with a text or number value, every `derived_x` and `functions` expression, and `derived` entries
written as `{x: ...}`, so their syntax errors show up before play. A derived value written as a
plain string is only compiled when it is first used.

Quote expressions in YAML when they contain `:`, `#`, `{`, `[`, or start with a quote:
`pre_x: "hand[actor] != []"`.

## 8. Errors

Syntax errors (reported by the validator):

| Message | Cause |
|---|---|
| `syntax error in expression "<src>": <what> (position <n>)` | Not valid syntax (`empty expression`, `unterminated string`, `comments are not allowed`, `f-strings are not allowed`, …) |
| `<Construct> is not allowed in "<src>"` | A forbidden construct: `Lambda`, `Yield`, `Await`, `assignment`, `NamedExpr`, `Starred`, `BitOr`, `BitAnd`, `BitXor`, `Invert`, `LShift`, `RShift`, `MatMult`, `Ellipsis`, `semicolon`, … |
| `attribute .<name> is not allowed in "<src>"` | An attribute other than the six methods |
| `name <name> is not allowed in "<src>"` | A name starting with `_` |

Run-time errors:

```
error evaluating '<src>': <Kind>: <message>
```

`<Kind>` is named as in Python: `TypeError`, `ValueError`, `KeyError`, `IndexError`,
`ZeroDivisionError`, `NameError` (unknown name at that place), `AttributeError`,
`RecursionError`. A few errors come without that wrapper: `dict keys must be text, not int`,
`string formatting with % is not allowed; use str() and +`.

## 9. Examples

```python
score[actor] >= GOAL
[c for c in hand[actor] if c['cost'] <= gold[actor]]
max(players, key=total_of)            # total_of from functions
sum(c['value'] for c in table)
{**unit, 'damage': 0}
'Ranged' in self.get('keywords', '')
sorted(hand[actor], key=card_value, reverse=True)[:2]   # card_value from functions
```

## 10. Differences from Python

The language follows Python's semantics, with these deliberate differences:

1. **One number type.** `2.0` and `2` are the same number: `str(4/2)` is `'2'` (Python
   `'2.0'`), and `L[4/2]` works (Python: `TypeError`). Use `int()` when an integer is meant.
2. **Dict keys are text.** `{1: 'a'}` and `dict([(1, 2)])` are errors. `k in d` with a non-text
   `k` is `False`.
3. **Key order.** Dicts keep insertion order, except text keys that are integers (`'2'`, `'10'`):
   they come first, ascending. Sort before relying on such an order.
4. **`range`, `.keys()`, `.values()` and `.items()` return lists.** `range(3) == [0, 1, 2]` is
   `True`.
5. **Set order** is insertion order (Python: arbitrary). Use `sorted()` when order matters.
6. **No `%` formatting on text.** Use `str()` and `+`.
7. **No complex numbers or bytes.** `(-8) ** 0.5` is `nan`.
8. **Integers above 2^53** lose precision.
9. **Dates in YAML** stay text.


<!-- https://tabletwin.com/docs/guide.md -->

# Guide: from rulebook to model

This guide takes you from a rulebook to a model that validates and plays. It is written for people
and for AI agents: with the rulebook, this guide and the [reference](https://tabletwin.com/docs/reference/) you should be
able to write a working model without further help. All you need besides a text editor is the
site: the [validator](https://tabletwin.com/validate/) checks a model, the
[player](https://tabletwin.com/play/) plays it and the [diagram](https://tabletwin.com/diagram/)
draws it.
The [expression language](https://tabletwin.com/docs/expressions/) and the [engine](https://tabletwin.com/docs/engine/) pages give the exact
behaviour; this page gives the workflow, the decisions and the patterns. The
[quick reference](https://tabletwin.com/docs/cheatsheet/) has the essentials of all of them on one page.

The guide has four parts:

1. [What you build](#what-you-build): one YAML file, two levels.
2. [Tutorial](#tutorial-pig-from-rulebook-to-executable-model): a complete game, step by step,
   with what the validator and the player show.
3. [The workflow for any game](#the-workflow-for-any-game), [decision rules](#decision-rules) and
   [patterns](#patterns) for everything Pig does not need.
4. [Pitfalls](#pitfalls) and the [checklist](#checklist-before-you-call-a-model-done).

## What you build

A model is one YAML file that describes the rules of one game: what lies on the table (`state`),
the course of play (`flow`), what players can do (`actions`), reactions (`triggers`, windows,
`modifiers`), cards and dice as data (`content`) and how the game ends (`end`).

Every rule can be written at two levels:

| Level | You write | You get |
|---|---|---|
| **Diagram** | Structure and text: `pre: "has enough gold"` | The flow diagram and the rules overview on the site |
| **Executable** | Next to each text field an expression `<field>_x`: `pre_x: "gold[actor] >= 3"` | Test games in the validator, games in the player, tactics |

The text stays when you add the expression: people and the diagram read `pre`, the engine reads
`pre_x`. Always write the diagram level first and add the `_x` fields afterwards. A model may be
partly executable; the validator reports the percentage.

Two other kinds of files sit next to a model, and neither changes the rules:

| File | What | Page |
|---|---|---|
| A tactic | How someone plays: rules per decision place | [tactics](https://tabletwin.com/docs/tactics/) |
| A view | How the table looks in the player | [views](https://tabletwin.com/docs/views/) |

### The smallest model

```yaml
game: my-game              # short id: lower case, hyphens
label: My game             # display name
num_players: 2
mode: competitive          # or cooperative
state:
  vars:
    done: {scope: global, type: bool, init: false}
flow:
  id: game
  kind: sequence
  children:
    - {id: move, kind: step, do: do_something}
actions:
  do_something:
    effect: [{op: set, var: done, value: true}]
end:
  - {id: over, if: the move is done, if_x: done, result: draw}
```

The flow has one step; the step runs the action; the action sets a flag; after the step the engine
checks `end`, finds `done` true and ends the game in a draw. Paste it into the
[validator](https://tabletwin.com/validate/): no errors, 100% executable, and 20 of 20 test games
end with `over`.

To get completion and checking in VS Code (YAML extension by Red Hat), put this on the first line
of a model file:

```yaml
# yaml-language-server: $schema=https://tabletwin.com/models/docs/schema.json
```

## Tutorial: Pig from rulebook to executable model

We model Pig, a dice game, from its rules to a tested, executable model. Write the model in any
text editor and check it by pasting it into the [validator](https://tabletwin.com/validate/). The
finished model of the same game, with the rulebook as comments, is
[pig.yaml](https://tabletwin.com/models/docs/examples/pig.yaml); it differs from this one in small
details, and it is in the player as "Pig".

The rulebook:

> **Pig** (2 players). Players take turns. On your turn, roll a die as often as you like and add
> each result to a running total for this turn, the *pot*. If you roll a 1, the pot is lost and your
> turn ends. You may stop after any roll; the pot is then added to your score and your turn ends.
> The first player to reach 20 points wins.

### Step 1: write down the facts

Before writing YAML, answer five questions from the rulebook:

| Question | Pig |
|---|---|
| How many players? | 2 |
| Competitive or cooperative? | Competitive |
| How does the game end, and who wins? | As soon as a player has 20 points or more; that player wins |
| What is the course of play? | Turns in order; within a turn, roll or stop until the turn ends |
| What does the rulebook not say? | Who starts. Whether you may stop before your first roll |

The last row becomes `open_questions` (step 9). Do not guess silently: a recorded question is
worth more than an invented rule that looks convincing.

### Step 2: header

```yaml
game: pig
label: Pig
players: "2 players"
num_players: 2
mode: competitive
summary: >
  A push-your-luck dice game. On your turn you roll as often as you like and add the pips to a
  pot. A 1 empties the pot and ends your turn; stopping banks the pot. First to 20 wins.
```

Players are numbered from 0: "player 1" in a rulebook is index 0.

### Step 3: state

Everything that lies on the table or must be remembered. Pig has no cards, so there are no zones,
only variables. Fixed numbers from the rulebook become constants, so they are easy to find and
change.

```yaml
constants:
  GOAL: 20

state:
  vars:
    score: {scope: player, type: int, init: 0}       # one value per player: score[0], score[1]
    pot: {scope: global, type: int, init: 0}
    current: {scope: global, type: ref, init: 0, note: "set by the turn loop"}
    turn_over: {scope: global, type: bool, init: false}
```

`current` is the loop variable of the turn loop. `turn_over` is a flag the inner loop tests.

### Step 4: flow, at diagram level

The flow is the skeleton of rounds, turns and phases. Pig is a loop over the players; inside each
turn there is a start and then a loop of "roll or stop".

```yaml
flow:
  id: game
  label: Game
  kind: loop
  over: all players in turn
  as: current
  order: fixed
  children:
    - id: turn
      label: Turn
      kind: sequence
      children:
        - {id: start, label: Start of turn, kind: step, do: start_turn}
        - id: rolling
          label: Roll until you stop or roll a 1
          kind: loop
          until: the turn is over
          children:
            - {id: choice, label: Roll or stop, kind: step, actor: the current player, do: [roll, stop]}
```

The outer loop has no `until`: after the last player it starts a new round with the first player,
and it keeps doing so until an end condition fires. A step with a list in `do` is a choice between
actions.

### Step 5: actions, at diagram level

```yaml
actions:
  start_turn:
    effect:
      - {op: set, var: pot, value: 0}
      - {op: set, var: turn_over, value: false}
  roll:
    effect:
      - {op: roll, die: [1, 2, 3, 4, 5, 6], bind: pips}
      - op: if
        cond: a 1
        then:
          - {op: set, var: pot, value: 0}
          - {op: set, var: turn_over, value: true}
        else:
          - {op: add, var: pot, amount: the pips}
  stop:
    pre: the pot is not empty
    effect:
      - {op: add, var: "score[current]", amount: the pot}
      - {op: set, var: turn_over, value: true}
```

`roll` binds the result to the local name `pips`. `stop` has a condition (`pre`): stopping with an
empty pot is pointless, which also answers the second open question. Inside an action's `pre`,
`cost` and `effect`, the local name `actor` is the player who acts (the step's `actor_x`), so
`score[actor]` would work here as well as `score[current]`.

### Step 6: end

```yaml
end:
  - {id: reached_goal, if: the current player has reached the goal, result: win}
```

### Step 7: validate

Paste steps 2 to 6 into the [validator](https://tabletwin.com/validate/) and press Check
(or Ctrl+Enter). It shows:

- **No errors**, and no warnings. The model is a valid diagram.
- **43% executable**, with rules 43%, content `-`, steps 2, ops 9, code 0%, open questions 0.
- **What the engine still misses**, the gap list:

```text
== Pig: executable 43% (rules 6/14), 8 gaps
  text: 8
      action roll: if.cond
      action roll: add.amount
      action stop: pre
      action stop: add.amount
      flow game: loop.over
      flow rolling: loop.until
      … and 2 more
```

  The two not shown are `step.actor` (who chooses in step `choice`) and `end.if/who`.
- **Test games: 0 of 20 finished**, with under "Where games stopped":
  `20× Not executable: action stop: pre is text without pre_x`. The engine cannot decide whether
  `stop` is legal, because `pre` is text for people.
- **The flow as a tree** (click to open), to compare with the rulebook:

```text
loop Game for each current in all players in turn (no until)
  sequence Turn
    - Start of turn: start_turn
    loop Roll until you stop or roll a 1 until the turn is over
      - Roll or stop: roll | stop · by the current player
          stop allowed if: the pot is not empty
```

"Open in the player" stays disabled until at least one test game finishes.

### Step 8: add the expressions

Add an `_x` field next to every text field the gap report lists. Keep the text.

```yaml
  over: all players in turn
  over_x: players                    # the list [0, 1]
  ...
          until: the turn is over
          until_x: turn_over
  ...
            - {id: choice, ..., actor: the current player, actor_x: current, do: [roll, stop]}
  ...
        cond: a 1
        cond_x: "pips == 1"
  ...
          - {op: add, var: pot, amount: the pips, amount_x: pips}
  ...
    pre: the pot is not empty
    pre_x: "pot > 0"
  ...
      - {op: add, var: "score[current]", amount: the pot, amount_x: pot}
  ...
  - {id: reached_goal, if: the current player has reached the goal, if_x: "score[current] >= GOAL", result: win, who_x: current}
```

Quote expressions that contain `:`, `#`, `[`, `{`, or start with a number or a quote.
Check again. Now the validator shows **100% executable** (the gap list is gone), and:

```text
Test games: 20 of 20 finished
On average 26 requests per game. How they ended:
  reached_goal: 20×
```

Every game ends the way the rulebook says, and "Open in the player" is enabled.

Why `who_x: current` works: the engine checks the end conditions right after each step, before
the turn loop moves on, so `current` still holds the player who just stopped.

### Step 9: play one game and read it

Press "Open in the player". The [player](https://tabletwin.com/play/) opens with "Your model: Pig",
random players and game (seed) 1. On the left is the track of the rules with the train at the
current step; on the right, what is asked now, what was chosen and what happened until the next
question; below, the table and a timeline. Step through the questions with the playback buttons.

Game 1 goes like this:

- The first question is already a die roll. Player 0's turn has started, and with an empty pot
  only `roll` is legal, so the engine took it without asking: one legal option is not a decision.
- Question 1 is a chance at `action roll`, out of 6 equally likely outcomes: a 1. Under "Effect
  until the next question" you see the `if` reset the pot and set `turn_over`; the inner loop
  ends and the train moves on to player 1's turn. "automatic" lists
  `step choice: player 1 → roll`: player 1's first roll is not a decision either.
- Player 1 rolls 6; at `step choice` (options `roll`, `stop`) chooses `roll` and rolls 5, chooses
  `roll` again and rolls 2, then chooses `stop`: `score` becomes `[0, 13]`.
- After a few more turns player 1 stops with 25 points. The game ends after 15 questions with
  "End: reached_goal" and the payoff player 0 −1 · player 1 1.

"Zones and values" in the table shows `score`, `pot`, `current` and `turn_over` at every question.
"Game (seed)" picks the game: the same seed and the same players give the same game, and "Random
game" tries another one.

To try a specific line of play, play a seat yourself: under Players choose "You play player 0
(others: random)". The player stops at each of your decisions ("Your turn") and offers the options
as buttons. "Everyone by hand (one screen)" lets you make every choice. To try another goal,
change `GOAL` in the model and check it again.

### Step 10: record what the rulebook does not say

```yaml
open_questions:
  - id: first_player
    about: setup
    question: Who starts? The rulebook does not say.
    status: assumed
    answer: Player 0 starts; the turn loop goes over players in index order.
```

`status` is `open` (undecided), `assumed` (the model follows the `answer`) or `answered` (the
source or the designer settled it).

### Step 11: a player who is better than random

How a good player chooses is not part of the rules. A [tactic](https://tabletwin.com/docs/tactics/) is a separate file
with rules per decision place:

```yaml
tactic: pig-hold-at-8
game: pig
rules:
  - at: step choice
    when_x: "pot >= 8 or score[me] + pot >= GOAL"
    pick: stop
  - at: step choice
    pick: roll
```

The built-in Pig in the player has this tactic. Choose "Pig (roll until you stop)" as the game and
"tactic stop at 8 vs random" under Players, and follow its choices; or play a seat yourself
against it. Loading your own tactic files is not yet available on the site.

Playing thousands of games to measure balance is not yet available on the site either. For the
record: over 2000 games with random players the first player wins about 55% (a goal of 50 shrinks
that advantage), and the tactic above wins about 75% against a random player.

### The finished model

```yaml
game: pig
label: Pig
players: "2 players"
num_players: 2
mode: competitive
summary: >
  A push-your-luck dice game. On your turn you roll as often as you like and add the pips to a
  pot. A 1 empties the pot and ends your turn; stopping banks the pot. First to 20 wins.

constants:
  GOAL: 20

state:
  vars:
    score: {scope: player, type: int, init: 0}
    pot: {scope: global, type: int, init: 0}
    current: {scope: global, type: ref, init: 0, note: "set by the turn loop"}
    turn_over: {scope: global, type: bool, init: false}

flow:
  id: game
  label: Game
  kind: loop
  over: all players in turn
  over_x: players
  as: current
  order: fixed
  children:
    - id: turn
      label: Turn
      kind: sequence
      children:
        - {id: start, label: Start of turn, kind: step, do: start_turn}
        - id: rolling
          label: Roll until you stop or roll a 1
          kind: loop
          until: the turn is over
          until_x: turn_over
          children:
            - {id: choice, label: Roll or stop, kind: step, actor: the current player, actor_x: current, do: [roll, stop]}

actions:
  start_turn:
    effect:
      - {op: set, var: pot, value: 0}
      - {op: set, var: turn_over, value: false}
  roll:
    effect:
      - {op: roll, die: [1, 2, 3, 4, 5, 6], bind: pips}
      - op: if
        cond: a 1
        cond_x: "pips == 1"
        then:
          - {op: set, var: pot, value: 0}
          - {op: set, var: turn_over, value: true}
        else:
          - {op: add, var: pot, amount: the pips, amount_x: pips}
  stop:
    pre: the pot is not empty
    pre_x: "pot > 0"
    effect:
      - {op: add, var: "score[current]", amount: the pot, amount_x: pot}
      - {op: set, var: turn_over, value: true}

end:
  - {id: reached_goal, if: the current player has reached the goal, if_x: "score[current] >= GOAL", result: win, who_x: current}

open_questions:
  - id: first_player
    about: setup
    question: Who starts? The rulebook does not say.
    status: assumed
    answer: Player 0 starts; the turn loop goes over players in index order.
```

## The workflow for any game

Work in this order; each step builds on the previous one. Validate after every step, not only at
the end.

1. **Read the rulebook and write down the facts**: number of players, competitive or cooperative,
   how the game ends and who wins, the course of a round (usually a section like "Playing the
   game"), and everything the rulebook leaves open.
2. **Header**: `game`, `label`, `num_players`, `mode`, `summary` (two or three sentences in your own
   words), optionally `players` ("2–4 players").
3. **State**:
   - things that *lie* somewhere (cards, tokens, pieces, cells) → `zones`;
   - numbers, flags, whose turn it is → `vars` (one per player: `scope: player`);
   - fixed numbers and tables from the rulebook → `constants`;
   - values you can compute from the state → `state.derived`;
   - a board with distances, lines of sight or paths → `boards` ([board geometry](https://tabletwin.com/docs/board-geometry/)).
4. **Flow**: rounds, turns and phases as a tree of `sequence`, `loop`, `branch`, `subflow` and
   `step`. Each step names one action, or a list of actions the actor chooses from. Follow the
   rulebook's headings: a phase in the rulebook is a node in the flow.
5. **Actions**: per action when it is allowed (`pre`) and what it does (`effect`, a list of ops).
6. **End**: when the game stops and what every player gets.
7. **Reactions and exceptions**: triggers (something happens automatically after an event),
   priority windows (players may play something in between), modifiers (a value is adjusted).
8. **Content and open questions**: cards and dice faces as data (`content`); every gap or
   ambiguity as `open_questions`.
9. **Expressions**: add the `_x` fields until the validator's list "What the engine still misses"
   is gone (or only lists what you deliberately leave as text).
10. **Check**: read the test games in the validator, follow single games in the player, compare
    with the rulebook (see [checking a model](#checking-a-model)).

## Decision rules

**Step, action or op?**

- *Step*: a moment in the course of play ("draw a card", "choose an action"). It sits in the flow.
- *Action*: something that can be done, with a condition and an effect. A step chooses from actions.
- *Op*: one elementary operation inside an effect (set, add, draw, roll, choose).

**A list in `do`, or `choose`?**

- The player chooses *which action* (build, trade, pass): `do: [build, trade, pass]` with
  `actor_x` on the step. Each action has its own `pre` and `effect`; the engine offers only the
  legal ones.
- The player chooses *a parameter of one action* (which cell, which card, how many): `choose`
  inside the effect, with the options as a list or an expression.
- The player chooses *a subset* (1 to 3 cards): `choose` with `min` and `max`.

**Zone or variable?** Can you move it, draw it, or point at it on the table? Zone. Is it a number
or a status? Variable. A number per player is a variable with `scope: player`.

**Flow step, trigger or window?**

- It always happens at a fixed moment of the round: flow step.
- It happens *in response to* something ("whenever you take damage", "when a card is revealed"):
  a trigger on an event (`emit` + `triggers`).
- Players may *play something in between* at a moment ("actions may be played after the quest
  phase", "in response you may cast a counterspell"): a priority window.

**Constant or variable?** Does it change during play? Variable. Is it a fixed setting of the game
(target score, number of rounds)? Constant.

**Rule or tactic?** What the rulebook prescribes belongs in the model. How a good player chooses
among legal options belongs in a [tactic](https://tabletwin.com/docs/tactics/).

## Patterns

Each pattern has a minimal snippet, cut from a small model that validates and plays. Snippets leave
out declarations that do not matter for the pattern; the referenced files show the pattern in a
complete model.

### Taking turns

A `loop` with `over_x: players` and `as: <variable>` sets that variable for each player in turn;
the step uses it as `actor_x`. Without `until_x` the loop repeats: after the last player it starts
the next round with the first, round after round, until an end condition fires and ends the game.
The end check comes right after the step, before the loop moves on, so the `as` variable still
points at the player who just moved: "whoever just moved wins" is `who_x: current`.

Inside the action, `actor` is the acting player (the step's `actor_x`): write `gold[actor]` in
`pre_x`, `cost` and `effect`. Flow expressions and end conditions have no `actor`; they use the
loop variable.

```yaml
flow:
  id: game
  kind: loop
  over_x: players
  as: current
  children:
    - {id: turn, kind: step, actor_x: current, do: [build, trade, pass_turn]}
```

Declare the `as` variable in `state.vars` (an undeclared one only exists once the loop has set
it). Example: [pig.yaml](https://tabletwin.com/models/docs/examples/pig.yaml).

### Setup: a step without an actor

Setup ("shuffle the deck, deal two cards to each player") is a step without `actor_x`: a system
action. The engine runs it without asking anyone, because there is one action and nothing to
choose. It may roll, draw and shuffle (chance is fine), but it must not need a decision: a
`choose` with two or more options there needs its own `actor_x`.

```yaml
flow:
  id: game
  kind: sequence
  children:
    - {id: setup, kind: step, do: deal}                  # no actor_x
    - id: rounds
      kind: loop
      over_x: players
      as: current
      children: [{id: turn, kind: step, actor_x: current, do: [play, pass_turn]}]
actions:
  deal:
    effect:
      - {op: shuffle, zone: deck}
      - {op: for_each, items_x: players, as: p, body: [{op: draw, from: deck, to: "hand[p]", n: 2}]}
```

### A round that stops halfway (bidding)

A turn loop always completes the round: `until_x` is only tested before the next round. If play
must stop in the middle of a round ("whoever passes loses the auction"), use a `loop` **without**
`over_x`, with your own turn variable that each action passes on, and a flag in `until_x`.

```yaml
state:
  vars:
    bidder: {init: 0}
    bid: {init: 0}
    over: {init: false}
    winner: {init: null}
flow:
  id: auction
  kind: loop
  until_x: over
  children:
    - {id: bid_or_pass, kind: step, actor_x: bidder, do: [raise, pass_out]}
actions:
  raise:
    pre_x: "bid < 5"
    effect:
      - {op: add, var: bid, amount: 1}
      - {op: set, var: bidder, value_x: "1 - bidder"}
  pass_out:
    effect:
      - {op: set, var: winner, value_x: "1 - bidder"}
      - {op: set, var: over, value: true}
end:
  - {id: sold, if_x: over, result: score, returns_x: "[5 - bid if p == winner else 0 for p in players]"}
```

Example: [auction.yaml](https://tabletwin.com/models/docs/examples/auction.yaml).

### Each player once

"Each player may engage one enemy": a `loop` with `over_x: players`, `as: <variable>` and
`once: true`. Without `once` the loop repeats the round until `until_x` holds. `over_x` may be any
list, for example the engaged enemies, with `as: enemy`.

```yaml
- id: engagements
  kind: loop
  over_x: players
  as: p
  once: true
  children:
    - {id: engage, kind: step, actor_x: p, do: [engage, decline]}
```

### Repeat until something happens; push your luck

A `loop` with `until_x`, tested only at the start of each round. Set a flag in an effect and test
it in `until_x`. "Roll or stop" is a step with `do: [roll, stop]` inside such a loop; give an action
that is pointless now a `pre_x`. See the tutorial.

### A grid of cells

A grid of R × C cells can be one zone with one element per cell, for example `init_x: "[None] * 9"`
for 3 × 3 (cell `r * 3 + c`). `place` with `at_x` puts something in a cell (replacing what was
there). The cell is chosen with `choose` and `options_x` that computes the free cells. Fixed
patterns (lines, neighbours) are tables in `constants`, tested with `any(...)` and `all(...)`. A free
cell is `None`; test it with `is None`.

```yaml
constants:
  LINES: [[0, 1, 2], [3, 4, 5], [6, 7, 8], [0, 3, 6], [1, 4, 7], [2, 5, 8], [0, 4, 8], [2, 4, 6]]
  MARKS: [X, O]
state:
  zones:
    board: {kind: grid, init_x: "[None] * 9"}
  vars:
    current: {init: 0}
  derived:
    line_done:
      text: some line holds three equal marks
      x: "any(board[a] is not None and board[a] == board[b] == board[c] for a, b, c in LINES)"
flow:
  id: game
  kind: loop
  over_x: players
  as: current
  children:
    - {id: turn, kind: step, actor_x: current, do: mark}
actions:
  mark:
    effect:
      - {op: choose, options_x: "[i for i in range(9) if board[i] is None]", bind: cell}
      - {op: place, what_x: "MARKS[actor]", to: board, at_x: cell}
end:
  - {id: three, if_x: line_done, result: win, who_x: current}
  - {id: full, if_x: "None not in board", result: draw}
```

The `choose` is inside the effect, so the step needs `actor_x` even though it has one action.
Examples: [tictactoe.yaml](https://tabletwin.com/models/games/tictactoe.yaml),
[neighbours.yaml](https://tabletwin.com/models/docs/examples/neighbours.yaml).

### A board with space: moving, range, line of sight

When distance, paths, sliding or line of sight matter (chess, draughts, dungeon fights), declare
the board in `boards` and track what is where: a variable `{cell: piece}`, or instances with a cell
property. The geometry functions compute the space (`ray` to the first piece, `reachable` with
costs and blockers, `line_of_sight`, `shape` for area attacks). Rules that recur ("is this cell
attacked", "where does this monster move") go into `functions`. Compute expensive things (the legal
moves) once after each move and keep them in a variable instead of recomputing them in every end
condition.

```yaml
boards:
  grid: {kind: square, width: 4, height: 4, neighbours: 4}
state:
  vars:
    pos: {init: "0,0"}
actions:
  walk:
    effect:
      - {op: choose, options_x: "neighbours('grid', pos)", bind: to}
      - {op: set, var: pos, value_x: to}
end:
  - {id: home, if_x: "pos == '3,3'", result: win, who_x: "0"}
```

See [board geometry](https://tabletwin.com/docs/board-geometry/); examples
[chess.yaml](https://tabletwin.com/models/games/chess.yaml) and
[hex-skirmish.yaml](https://tabletwin.com/models/docs/examples/hex-skirmish.yaml).

### Deck, hand, hidden cards, secret choices

- Deck: a zone with `visibility: hidden`, `shuffled: true` and `init_x` with the cards. Drawing
  from a shuffled zone is a chance node; from a zone that is not shuffled you always get the first
  element.
- Hand per player: a zone with `owner: player`, `visibility: owner`; path `hand[i]` in ops, and
  `hand[i]` is a list in expressions.
- Secret choice: `secret: true` on `choose` (or on the step). Show it later with `reveal` and
  `what_x`: everyone (or `visible_to_x`) observes the value; the zone's visibility does not change.
- A card nobody sees (set aside, face down): move or draw it into a zone with
  `visibility: hidden`.

```yaml
constants:
  CARDS: [1, 2, 3, 4, 5, 6, 7, 8]
state:
  zones:
    deck: {kind: stack, visibility: hidden, shuffled: true, init_x: "CARDS"}
    hand: {kind: set, owner: player, visibility: owner}
    played: {kind: set, owner: player, visibility: hidden}
  vars:
    p: {init: 0}
flow:
  id: game
  kind: sequence
  children:
    - {id: deal, kind: step, do: deal}
    - id: secret_turns
      kind: loop
      over_x: players
      as: p
      once: true
      children:
        - {id: play, kind: step, actor_x: p, do: play_card}
    - {id: show, kind: step, do: reveal_all}
actions:
  deal:
    effect:
      - op: for_each
        items_x: players
        as: q
        body:
          - {op: draw, from: deck, to: "hand[q]", n: 2}
  play_card:
    effect:
      - {op: choose, options_x: "hand[actor]", bind: card, secret: true}
      - {op: move, what_x: card, from: "hand[actor]", to: "played[actor]"}
  reveal_all:
    effect:
      - op: for_each
        items_x: players
        as: q
        body:
          - {op: reveal, what_x: "played[q][0]"}
```

Players choose one after the other, but because the choice is secret and the card goes to a hidden
zone, the second player cannot see the first card: this is how simultaneous secret choices are
modelled. Examples: [higher-lower.yaml](https://tabletwin.com/models/docs/examples/higher-lower.yaml),
[kuhn-poker.yaml](https://tabletwin.com/models/games/kuhn-poker.yaml).

### Cards with their own state (instances)

A card, monster or unit that changes during play (damage, exhausted, tokens) is an *instance*: a
dict in a zone with a unique `uid`. Make instances with `create` from a content item (`n: 3` for
three copies, `with_x` for initial state), or let a zone's `init_x` produce dicts. Change a
property with `set`/`add` and `of_x` + `attr`; read it as `target['damage']`.

```yaml
content:
  monsters:
    goblin: {id: goblin, label: Goblin, hp: 3, status: verified}
actions:
  spawn:
    effect:
      - {op: create, what_x: "content['monsters']['goblin']", to: board, n: 2, with_x: "{'damage': 0}"}
  hit:
    effect:
      - {op: let, bind: target, value_x: "board[0]"}
      - {op: add, of_x: target, attr: damage, amount: 2}
      - {op: set, of_x: target, attr: exhausted, value: true}
      - op: if
        cond_x: "target['damage'] >= target['hp']"
        then: [{op: move, what_x: target, from: board, to: discard}]
```

An instance keeps its properties when it moves. If it can come back (reshuffled, redrawn), reset
damage and tokens where it leaves play. Example:
[stack-game.yaml](https://tabletwin.com/models/tests/stack-game.yaml).

### Looking at, ordering and searching a deck

- "Look at the top 3": `look` with `n: 3` and `bind`. Their order is fixed afterwards.
- "Put it on the bottom" or "on top": `move`, `create` or `draw` with `position: bottom` or `top`.
- "Shuffle the deck": `shuffle` with `zone`; what was known on top or at the bottom is unknown
  again.
- "Search your deck for a card of type X": `search` with `filter_x` (the candidate is `it`, or the
  name in `as`), then `move` and usually `shuffle`.

```yaml
actions:
  peek:
    effect:
      - {op: look, from: deck, n: 2, bind: top}
      - {op: move, what_x: "top[0]", from: deck, to: deck, position: bottom}
  dig:
    effect:
      - {op: search, from: deck, filter_x: "it % 2 == 0", bind: found}
      - {op: move, what_x: found, from: deck, to: hand}
      - {op: shuffle, zone: deck}
```

If nothing matches, `search` binds `None` (or `[]` with `min`/`max`), and the `move` after it
fails; guard it with an `if`. Example:
[stack-game.yaml](https://tabletwin.com/models/tests/stack-game.yaml).

### Dice

`roll` with `die: [1, 2, 3, 4, 5, 6]` (or `die_x`) and `bind`. Every face is equally likely; an
uneven die repeats faces (`[0, 1, 1, 2]`). Faces may be text (a coin: `[heads, tails]`) or
instances (`die_x: "hand[p]"` picks a random card from a hand). Several dice: several `roll` ops,
or a `for_each`/`repeat`.

### Score and winner

| Rulebook | `end` |
|---|---|
| One winner | `result: win`, `who_x: <index>`; everyone else gets −1 |
| One loser | `result: loss`, `who_x: <index>`; everyone else gets +1 |
| Points | `result: score`, `returns_x: "[...]"` with one number per player |
| Draw | `result: draw` |
| Solo game | `num_players: 1`, `mode: competitive`, `result: score` with `returns_x: "[score]"` |
| Cooperative win / loss | `mode: cooperative`, `result: win` or `loss` without `who_x`: everyone +1 or −1 |
| A player drops out | `result: eliminate` with `who_x` (index or list); the game goes on |

With two players `[1, -1]`, `[-1, 1]` or `[0, 0]` is the usual score; for a zero-sum game the
returns add up to 0. Returns may be larger than 1 (chips, points). `utility: {min, max}` documents
the range of returns; the engine does not use it. Examples:
[auction.yaml](https://tabletwin.com/models/docs/examples/auction.yaml),
[coop-clock.yaml](https://tabletwin.com/models/tests/coop-clock.yaml).

### Eliminating players

`result: eliminate` adds players to `eliminated`; checking continues with the next condition, so
put the "last one standing" condition after it. Loops do not skip eliminated players by
themselves: filter them in `over_x`. A list in `over_x` is computed at the start of the round, so a
player eliminated halfway still gets that round's turn unless `pre_x` forbids it.

```yaml
flow:
  id: game
  kind: loop
  over_x: "[q for q in players if q not in eliminated]"
  as: p
  children:
    - {id: turn, kind: step, actor_x: p, do: [poke_left, poke_right]}
end:
  - {id: out, if_x: "True", result: eliminate, who_x: "[q for q in players if hp[q] <= 0]"}
  - {id: last, if_x: "len(eliminated) == n_players - 1", result: win, who_x: "[q for q in players if q not in eliminated][0]"}
```

Priority windows do skip eliminated players.

### Reacting to an event (triggers)

An `emit` op marks a moment ("damage"). Triggers with the same `event` react to it. `timing`:
`when`/`before` run before the `impact`, `instead` replaces the impact (the first one that fires),
`after` runs afterwards (default). `optional: true` makes it a `use`/`skip` choice for
`controller_x`.

```yaml
actions:
  hit:
    effect:
      - {op: let, bind: target, value: 1}
      - op: emit
        event: damage
        impact:
          - {op: add, var: "hp[target]", amount: -2}
triggers:
  - id: block
    event: damage
    timing: instead
    if_x: "shield[target] > 0"
    do:
      - {op: add, var: "shield[target]", amount: -1}
  - id: cry_out
    event: damage
    optional: true
    controller_x: target
    do:
      - {op: add, var: "rage[target]", amount: 1}
```

A trigger reads the local names of the place that emits (`target` here). If another place emits
the same event without binding that name, `if_x` fails with a `NameError`: make every emitter bind
the same names, or keep the value in a variable. Example:
[triggers.yaml](https://tabletwin.com/models/tests/triggers.yaml).

### Playing in between (priority windows)

`window: <name>` on a flow node opens a window after that node. Actions with a `speed` that the
window `allows` can be played there; players get priority in turn and play a legal fast action or
pass. The protocol (`priority.protocol`) decides who starts (`first_x`), when the window closes
and how effects resolve: `immediate` or `lifo_stack` (on a stack; last played resolves first).
`cost` happens when played, `effect` when it resolves; `cancel` cancels an item on the stack, and
`stack` can be read in the window (in `pre_x`, `cost` and `effect`).

```yaml
state:
  vars:
    hp: {scope: player, init: 3}
    counters: {scope: player, init: 1}
priority:
  protocol:
    first_x: "0"
    closes: all_pass_in_succession
    resolution: lifo_stack
    after_action: next
  windows:
    response: {label: Responses, allows: [fast]}
flow:
  id: game
  kind: loop
  children:
    - {id: attack, kind: step, do: attack, window: response}
actions:
  bolt:
    speed: fast
    pre_x: "len(stack) == 0"
    cost:
      - {op: let, bind: target, value_x: "1 - actor"}    # chosen when played, kept until it resolves
    effect:
      - {op: add, var: "hp[target]", amount: -1}
  counter:
    speed: fast
    pre_x: "counters[actor] > 0 and any(s['actor'] != actor and not s['cancelled'] for s in stack)"
    cost:
      - {op: add, var: "counters[actor]", amount: -1}
      # the topmost item of another player that is not cancelled yet; cost ops see `stack`
      - {op: let, bind: target, value_x: "max(i for i, s in enumerate(stack) if s['actor'] != actor and not s['cancelled'])"}
    effect:
      - {op: cancel, target_x: target}                   # `cancelled` becomes true only now
```

- Bind a target that is fixed when the action is played in `cost` with `let`. Names bound in `cost`
  are kept until the effect resolves, and `actor` is then the player who played it.
- A stack item's `cancelled` turns true only when the `cancel` op runs, so in the effect: when the
  counter resolves, not when it is played. Until then another counter may target the same item.
  Cancelling it twice does no harm.
- After an item resolves, priority goes back to the player `first_x` gave when the window opened
  (it is not evaluated again).
- Give fast actions a cost or a limit (`counters` here). Free responses that are always legal can
  keep a window open forever (`window does not close` after 10,000 turns).
- The engine checks the end after each effect that resolves, not when the window closes. If the
  result depends on "the window is over", put `end_event: <event>` on the node with the window and
  a trigger on that event that sets a flag: the end check right after the event sees it. A step
  after the window that sets the flag works too.
- A node that only opens a window: `{id: combat, kind: sequence, children: [], window: combat}`.
- `pass` is offered by the engine; do not name a fast action `pass`.

Examples: [ambush.yaml](https://tabletwin.com/models/docs/examples/ambush.yaml),
[spell-duel.yaml](https://tabletwin.com/models/tests/spell-duel.yaml).

### Choosing a subset

`choose` with `min` and `max`: the engine asks for one element at a time, in the fixed order of the
options, plus `done` once `min` is reached, and binds the list of chosen options.

```yaml
- {op: choose, options: [a, b, c, d], min: 1, max: 2, bind: cards}
```

In the player the first question is at `action pick · 1` with the options `a`, `b`, `c`, `d`; after
picking `b`, the next is at `action pick · 2` with `c`, `d`, `done`: only later options remain.
Example: [subset.yaml](https://tabletwin.com/models/tests/subset.yaml).

### Values changed by effects (modifiers)

Declare `modifiers` with `stat`, `layer` and `change_x` (where `value` is the value so far) and read
the value with `modified('stat', base)`. Layers go from low to high. Temporary: the op `modify` with
`until: <event>`. On a content item: active while its `active_x` holds.

```yaml
modifiers:
  - {id: frenzy, stat: attack, layer: 1, if_x: "rage[attacker] > 2", change_x: "value + 2"}
actions:
  strike:
    effect:
      - {op: modify, stat: attack, change_x: "value + 1", until: round_end}
      - {op: add, var: "hp[1 - actor]", amount_x: "-modified('attack', 1, attacker=actor)"}
```

Keyword arguments of `modified()` (`attacker=actor`) are local names in `if_x` and `change_x`.
Example: [modifiers.yaml](https://tabletwin.com/models/tests/modifiers.yaml).

### Until the end of the phase or round

Put `end_event: phase_end` on every phase node (and `end_event: [phase_end, round_end]` on the
last one, or `end_event: round_end` on the round node), and use `until: phase_end` on `modify`. The
engine emits the event when the node is done, after its window. Triggers on that event do what
happens "at the end of the phase".

```yaml
- id: round
  kind: sequence
  end_event: round_end
  children:
    - {id: planning, kind: step, do: plan, end_event: phase_end}
    - {id: combat, kind: step, do: fight, end_event: phase_end}
```

### Permission and costs that depend on cards

"You may only travel here if ...": read a yes/no value with `modified('can_travel', True, card=c)`
in `pre_x` and `options_x`, and let the card set it to `False` with a modifier. The same pattern fits
"cannot draw cards" (`modified('draw_count', n)`) and "does not ready" (`modified('readies', True,
card=c)`). A cost that the card adds is a trigger on an event emitted just before the act
(`traveling_to`).

```yaml
modifiers:
  - {id: no_heal_on_odd_rounds, stat: can_heal, if_x: "round % 2 == 1", change_x: "False"}
actions:
  heal:
    pre_x: "modified('can_heal', True)"
    effect: [{op: add, var: "hp[actor]", amount: 1}]
```

### Campaign: scenarios with lasting state

- What lasts between scenarios: `persist: campaign` on the variable or zone.
- Start of each scenario: the op `reset`; everything without `persist` gets its initial value again
  (`init_x` is recomputed and may read lasting variables).
- A scenario is a `subflow`; an end condition with `scope: <name>` ends only that subflow and sets
  `results['<name>']` to `win`, `loss` or `draw`. `<name>` is the key in `flows`.
- `results['<name>']` is cleared when that subflow starts again. Read it right after the subflow
  with `results.get('<name>')`: a reward step after the subflow node pays out for a won scenario.
- The scenario's inner loop needs no `until_x`: the scoped end conditions end it.

A complete model (one player; `swing` gains gold and costs health, `guard` heals):

```yaml
game: guide-campaign
label: Guide campaign
num_players: 1
state:
  vars:
    scenario_no: {init: 1, persist: campaign}
    wins: {init: 0, persist: campaign}
    gold: {init: 0, persist: campaign}
    hp: {init: 2}
flows:
  scenario:
    id: scenario
    kind: sequence
    children:
      - {id: setup, kind: step, do: setup}
      - id: fight
        kind: loop                                        # no until_x: the scoped end conditions stop it
        children: [{id: swing, kind: step, actor_x: "0", do: [swing, guard]}]
flow:
  id: campaign
  kind: loop
  until_x: "scenario_no > 3"
  children:
    - {id: play_scenario, kind: subflow, ref: scenario}
    - {id: tally, kind: step, do: tally}
actions:
  setup:
    effect: [{op: reset}]                                 # hp back to 2; gold, wins, scenario_no stay
  swing:
    effect:
      - {op: roll, die: [0, 1, 2], bind: loot}
      - {op: add, var: gold, amount_x: loot}
      - {op: add, var: hp, amount: -1}
  guard:
    pre_x: "hp < 2"
    effect: [{op: add, var: hp, amount: 1}]
  tally:                                                  # the reward step after each scenario
    effect:
      - op: if
        cond: the scenario was won
        cond_x: "results.get('scenario') == 'win'"
        then:
          - {op: add, var: wins, amount: 1}
          - {op: add, var: gold, amount: 1}               # reward: 1 extra gold
      - {op: add, var: scenario_no, amount: 1}
end:
  - {id: scenario_won, scope: scenario, if_x: "gold >= 3 * scenario_no", result: win}
  - {id: scenario_lost, scope: scenario, if_x: "hp <= 0", result: loss}
  - {id: campaign_over, if_x: "scenario_no > 3", result: score, returns_x: "[wins]"}
```

The order of events in one scenario: `setup` resets `hp`; after each `swing` or `guard` the end
check runs; when `gold >= 3 * scenario_no` the condition `scenario_won` sets
`results['scenario'] = 'win'` and ends the subflow; the campaign loop continues with `tally`,
which rewards the win; the end check after `tally` ends the game once `scenario_no > 3`.

Examples: [expedition.yaml](https://tabletwin.com/models/docs/examples/expedition.yaml),
[campaign.yaml](https://tabletwin.com/models/tests/campaign.yaml).

### Skill or physics (outcome models)

What is not a rule but skill (a pool shot, a dexterity flick) becomes an outcome model: a
probability distribution over outcomes with `p_x`, which may depend on skill and difficulty. The op
`sample` draws an outcome and runs its effect.

```yaml
constants: {SKILL: 0.6}
outcomes:
  shot:
    skill: true
    derived_x:
      p_pot: "SKILL * (1 - difficulty)"
    outcomes:
      - {id: potted, p: "p_pot", p_x: "p_pot", effect: [{op: add, var: score, amount: 1}]}
      - {id: missed, p: "the rest", p_x: "1 - p_pot"}
actions:
  shoot:
    effect:
      - {op: let, bind: difficulty, value: 0.25}
      - {op: sample, model: shot}
```

Each outcome needs `p` (text, for the validator and the diagram) and `p_x`. Example:
[eightball.yaml](https://tabletwin.com/models/games/eightball.yaml).

### Cards and faces as data (content)

What is printed on cards belongs in `content`: catalogues of items (`id`, `label`, `status`,
`text`, and behaviour). `exec` with `of_x` runs an item's `effect` (`self` is the item).

| Card text | On the item |
|---|---|
| "When revealed", "Forced: after X", "Response: after X" | `triggers` on event X; `optional: true` + `controller_x` for "may" |
| "+2 attack per token", "while active: no cards are drawn" | `modifiers` with `stat` and `if_x` |
| "Action: ..." (played by a player) | `abilities`: an action with `speed`, playable in windows |
| "Sentinel", "Ranged" | `keywords`; the rules ask for them (`'Ranged' in c.get('keywords', '')`) |

```yaml
content:
  cards:
    spider:
      id: spider
      label: Forest Spider
      status: verified
      text: "When revealed: each player loses 1 hp."
      triggers:
        - event: revealed
          if_x: "card['id'] == self['id']"
          do:
            - {op: for_each, items_x: players, as: q, body: [{op: add, var: "hp[q]", amount: -1}]}
    potion:
      id: potion
      label: Potion
      status: verified
      text: "Action: gain 1 hp."
      abilities:
        - {id: drink, speed: action, pre_x: "hp[actor] < 3", effect: [{op: add, var: "hp[actor]", amount: 1}]}
actions:
  reveal:
    effect:
      - {op: create, what_x: "content['cards']['spider']", to: staging, bind: card}
      - {op: emit, event: revealed}
```

- A trigger belongs to the card *type*, not to one copy: select the copy through the local names of
  the event (`card` here). Make sure every place that emits the event binds the same names.
- "At this moment" ("each character currently questing gets −1"): record the `uid`s and pass them
  on, `{op: let, bind: ids, value_x: "[c['uid'] for c in in_play if c.get('questing')]"}` and then
  `modify` with `if_x: "card['uid'] in ids"`. Otherwise cards that arrive later are affected too.
- An ability sees its card as `self`; find the copy in play with
  `[c for c in allies[actor] if c['id'] == self['id']]`.
- `status`: `verified`, `uncertain` or `missing`. `exec` on an item with `status: missing` or
  without `effect` is `NotExecutable`.

Examples, as rules structure in the diagram (their content and source are not published):
[The Lord of the Rings LCG](https://tabletwin.com/diagram/#lotr-lcg) (all card texts as
triggers, modifiers and abilities) and [Too Many Bones](https://tabletwin.com/diagram/#too-many-bones)
(content and open questions at diagram level). Small published examples:
[stack-game.yaml](https://tabletwin.com/models/tests/stack-game.yaml) and
[triggers.yaml](https://tabletwin.com/models/tests/triggers.yaml).

### Rule procedures that cards call

When the same procedure recurs ("reveal an encounter card", "whoever has enough damage is
destroyed", "a full location is explored"), make it a trigger on an event of its own and emit that
event wherever it is needed. Cards then use the same procedure: a travel cost "reveal the top card"
is `{op: emit, event: reveal_card}`, damage from a card ends with `{op: emit, event: damage}`. No
card repeats the rules.

## Pitfalls

1. **Text without `_x` does nothing in the engine.** `pre: "has money"` is for people; without
   `pre_x` the engine stops with `NotExecutable`. For a loop's `until`/`over` and an end
   condition's `if` it is worse: the engine silently ignores them. The validator lists them under
   "What the engine still misses".
2. **Literal or expression.** `value: open` sets the text `'open'`; `value_x: open` reads the
   variable `open`. `amount` must be a number or `amount_x`. In every other field text is a
   description: write a literal string as a quoted expression, `what_x: "'sword'"`.
3. **Players count from 0.** `players` is `[0, 1, ...]`.
4. **End conditions are checked only after a step that ran, after each resolved effect in a
   window, and after each `end_event`**, in the order of `end`; the first that holds decides. Not
   after a cost, not when a window closes, not in loops. A step with no legal action is skipped
   without a check.
5. **A flow that runs out without an end condition** ends with 0 for everyone and reason `flow
   finished without an end condition`. Almost always a bug.
6. **Drawing from a zone that is not shuffled always gives the first element.** For randomness set
   `shuffled: true`. The op `shuffle` only forgets known positions; the randomness is in drawing.
7. **`move` removes the first equal element** and fails if it is not there.
8. **Local names** (`bind` of `choose`, `roll`, `let`) live in the effect of that action, including
   `then`/`else`. A `for_each` body, an `emit` impact, triggers, outcome effects and `exec` work on a
   copy: what they bind is gone afterwards. Use a variable to remember something.
9. **YAML.** Quote expressions that contain `:`, `#`, `[`, `{` or start with a number. Models are
   read as YAML 1.1: `yes`, `no`, `on` and `off` are booleans. As a key (`on:`) that is an error
   (`key true is not text; put it in quotes`); triggers use `event`, a branch uses `switch` as text.
   As a value, quote them when you mean text (`options: ["yes", "no"]`).
10. **One option is not a choice.** The engine takes a single option without asking. That is
    intended, but it changes the number of decisions.
11. **Competitive games need `who_x`** on `win` and `loss`; cooperative games do not. `score` needs
    `returns_x` with exactly one number per player.
12. **A window without fast actions** (no action with a `speed` the window allows) closes at once
    without asking anyone.
13. **Who chooses.** A `choose` with more than one option needs a chooser: `actor_x` on the op, or
    `actor_x` on the step. That holds even if the step has one action.
14. **Names are visible.** Action ids are the options players and agents see. Choose readable,
    stable ids.
15. **A trigger reads the local names of whoever emits.** If another place emits the same event
    without that name, `if_x` fails with a `NameError`.
16. **Instances keep their state.** An instance keeps its properties in a discard pile. If it comes
    back, it still has damage or tokens; reset them where it leaves play.
17. **Text without behaviour counts as a gap.** A content item with `text` and no triggers,
    modifiers, abilities or used keywords is not executable.
18. **The validator does not know your names.** A misspelled variable in an expression passes
    validation and fails as a `NameError` in the test games or in the player. Always read the test
    games and follow a few games.

## Checking a model

Do this after every step of the workflow, not only at the end. Everything runs in the browser;
nothing is uploaded.

| Tool | Use it for |
|---|---|
| [Validator](https://tabletwin.com/validate/) | Paste the model and press Check: errors and warnings (structure, references, syntax, unknown keys), `% executable`, "What the engine still misses", 20 random test games and "The flow as a tree" |
| [Player](https://tabletwin.com/play/) | "Open in the player" in the validator: one game, question by question. Change "Game (seed)" or press "Random game" for other games; play a seat yourself to test one line of play |
| [Diagram](https://tabletwin.com/diagram/) | "Draw your own model": the flow as a track diagram, with markers for choice, chance, hidden information and windows per step |

What to look for:

- The validator shows no errors. Every warning is either a deliberate choice or a bug.
- "Test games: 20 of 20 finished", with the end reasons you expect and a plausible number of
  requests per game. Nothing under "Where games stopped", and no games that did not end within
  5000 requests.
- Every action occurs in a few games; an action that never occurs usually has a wrong `pre_x`.
  Follow games in the player with several seeds.
- Every trigger fires. After each question the player shows the events and the triggers they set
  off; a trigger whose event never appears, or whose effect never shows in the state, usually has a
  wrong `if_x` or listens to an event nobody emits (the validator warns about the latter).
- Test card texts one by one: set up the situation (a small test model whose setup creates it),
  emit the event and check in the player that exactly what the text says happens.
- Known facts match: if the rulebook or the community gives game length or difficulty, compare.
  Win rates over thousands of games cannot be measured on the site yet.
- Put the flow ("The flow as a tree", or the diagram) next to the rulebook: does every heading of
  the course of play appear?

## Checklist before you call a model done

- [ ] `game`, `label`, `num_players`, `mode`, `summary` are set.
- [ ] Every rule in the rulebook appears in the flow, an action, a trigger, a modifier, content, or
      an open question.
- [ ] The validator shows no errors; every warning is understood.
- [ ] The validator shows 100% executable, or only gaps you list in `open_questions` or a `note`.
- [ ] 20 of 20 test games finish, with the reasons you expect.
- [ ] A few games followed in the player, with different seeds, read like the rulebook.
- [ ] Every ambiguity is an `open_questions` entry with a status.


<!-- https://tabletwin.com/docs/authoring-with-ai.md -->

# Authoring with an AI agent

This page is for anyone who wants an AI agent to turn a rulebook into a Tabletwin model, and for
the agent itself. It gives the workflow, the rules the agent must follow, a prompt to copy, and
a checklist for when the model is done.

The short version: give the agent the documentation and an example, let it write the model in
small steps, and check it with the [validator](https://tabletwin.com/validate/) after every step
until there are no errors, the model is executable and test games finish.

## What the agent needs

| Input | Where |
|---|---|
| All documentation in one file | [`https://tabletwin.com/llms-full.txt`](https://tabletwin.com/llms-full.txt) |
| Everything needed on one page (keys, ops, flow, end conditions, names in scope, patterns) | [Quick reference](https://tabletwin.com/docs/cheatsheet/) |
| An index of the docs, schemas and example models | [`https://tabletwin.com/llms.txt`](https://tabletwin.com/llms.txt) |
| The JSON schema of a model | [`https://tabletwin.com/models/docs/schema.json`](https://tabletwin.com/models/docs/schema.json) |
| Example models to copy patterns from | [`/games/`](https://tabletwin.com/games/), and the files under `https://tabletwin.com/models/` |
| The rulebook | from the person who asks: a PDF, text or the publisher's rules page |
| A way to check its work | the [validator](https://tabletwin.com/validate/) in the browser; an agent without a browser asks the person to paste the model in (see [checking the model](#checking-the-model)) |

Pick the example that is closest to the game:

| The game has … | Start from |
|---|---|
| turns, a deck, hidden hands | [higher-lower.yaml](https://tabletwin.com/models/docs/examples/higher-lower.yaml) |
| dice and a push-your-luck choice | [pig.yaml](https://tabletwin.com/models/docs/examples/pig.yaml) |
| a board with squares or hexes, movement, line of sight | [hex-skirmish.yaml](https://tabletwin.com/models/docs/examples/hex-skirmish.yaml), [chess.yaml](https://tabletwin.com/models/games/chess.yaml) |
| reactions and a stack (players respond to each other) | [ambush.yaml](https://tabletwin.com/models/docs/examples/ambush.yaml) |
| bidding | [auction.yaml](https://tabletwin.com/models/docs/examples/auction.yaml) |
| several scenarios with lasting state | [expedition.yaml](https://tabletwin.com/models/docs/examples/expedition.yaml) |
| skill shots or other physical actions | [eightball.yaml](https://tabletwin.com/models/games/eightball.yaml) (outcome models) |
| a very small complete game | [tictactoe.yaml](https://tabletwin.com/models/games/tictactoe.yaml), [kuhn-poker.yaml](https://tabletwin.com/models/games/kuhn-poker.yaml) |

The validator's "Start from" menu loads these examples too.

## The workflow

Work in this order. Check the model with the validator after every step and fix what it reports
before you go on.

1. **Read the rulebook and list what exists.** Players, components (cards, dice, boards,
   tokens), where components can be (these become *zones*), numbers that change (these become
   *variables*), and the structure of a game: setup, rounds, phases, turns, how it ends. Write
   rules you are unsure about as `open_questions` right away; do not guess silently.
2. **Write the skeleton.** `game`, `label`, `players`, `num_players`, `mode`, `summary`, then
   `state` (zones and variables), `flow` (the nested sequence, loops, branches and steps),
   `actions` (empty effects are fine for now) and `end`. The validator must accept this.
3. **Fill the actions with ops.** Each action's `effect` is a list of ops: `move`, `draw`,
   `shuffle`, `set`, `add`, `choose`, `roll`, `if`, `for_each`, `emit`, and so on (see the
   [reference](https://tabletwin.com/docs/reference/)). Write readable text fields first if that helps (`cond: "player has
   no cards"`), then add the executable twin (`cond_x: "len(hand[actor]) == 0"`).
4. **Make it executable.** Every field the engine needs must have an `_x` expression or a literal
   value. The validator's executability (and its list of gaps) tells you what is missing. Aim for
   100% on the rules layer.
5. **Add the end conditions** with `if_x` and, in competitive games, `who_x`. A game that never
   ends shows up in the test games as "did not end within 5000 requests".
6. **Play test games.** The validator plays 20 games with random choices. All of them should
   finish, and the endings should look plausible (not every game ending the same way unless the
   game is like that). Open the model in the player and follow one game step by step.
7. **Add content** (cards, monsters, scenarios) as data under `content`, with effects in the same
   ops. Give every item a `status`: `verified` (checked against the source), `uncertain` or
   `missing`. Card texts are descriptions in your own words, never copied text.
8. **Record what is open.** Every rule that the rulebook leaves unclear goes into
   `open_questions` with `status: open` (or `assumed` with the assumption you made in the model).
9. **Optional: a view** for how the table looks in the player (paste it into the validator's view
   field next to the model), and a **tactic** for how a reasonable player plays (it cannot be
   loaded on the site yet). See [views](https://tabletwin.com/docs/views/) and [tactics](https://tabletwin.com/docs/tactics/).

## Rules for the agent

- **Follow the documentation, not your memory of other formats.** Keys, op names and field names
  must exist in the [reference](https://tabletwin.com/docs/reference/). The engine ignores keys it does not know, so a
  misspelled key silently does nothing; the [JSON schema](https://tabletwin.com/models/docs/schema.json) catches most of them,
  and the validator reports them as `unknown key` warnings (outside `content`).
- **Expressions are the expression language, not Python.** Only the syntax and functions in
  [expressions](https://tabletwin.com/docs/expressions/) are allowed. No imports, no attributes except `get`, `count`,
  `index`, `items`, `keys` and `values`, no names starting with `_`.
- **Names are short English snake_case** (`draw_pile`, `end_turn`). Labels are for people.
- **Own words.** Rules and card texts are paraphrased. Official names of cards and components may
  be used; long rule or card texts may not be copied.
- **Do not invent rules.** If the rulebook does not say it, make an `open_questions` entry and,
  if the model needs a choice, mark it `assumed` and say what you assumed.
- **Keep the model honest about what it cannot run.** Something too complex for the ops goes in
  `code` with a `doc` and `kind: content` or `kind: algorithm`; the validator counts it as a gap.
- **Small steps.** Validate after each change. Fix errors before warnings.

## Checking the model

The [validator](https://tabletwin.com/validate/) is the agent's check. Paste the model into
"Model (YAML)" (and a view, if any, into "View (optional YAML)") and press Check. It runs in the
browser and shows:

- errors and warnings, including `unknown key` warnings for misspelled keys;
- `% executable`, with "What the engine still misses": every field that still needs an `_x`;
- "Test games: X of 20 finished", with how the games ended, where games stopped (engine errors such
  as a `NameError`), and games that did not end within 5000 requests;
- "The flow as a tree", to compare with the rulebook.

When at least one test game finished, "Open in the player" opens the model in the
[player](https://tabletwin.com/play/), where a game can be followed question by question.

**Agents without a browser.** An agent that cannot open web pages hands the model to the person
and asks them to paste it into the validator and send back what it shows: the errors and
warnings, the executability and the gap list, and the test-game summary with "Where games
stopped". The agent fixes what was reported and hands over the next version. Ask for the full
text of each message; the place names in them (`action stop`, `step choice`) point to the line to
fix.

Simulating many games (win rates, comparing variants or tactics) is not yet available on the site;
"done" is judged by the validator and the player.

## A prompt to copy

Replace the parts in angle brackets.

```
You are writing a Tabletwin model: a board game as YAML, run by the Tabletwin engine.

Read first: https://tabletwin.com/llms-full.txt (all documentation and two example models).
Closest example to start from: <URL of an example model from https://tabletwin.com/llms.txt>.

The game: <name>. The rules: <attached rulebook / pasted rules>.

Write the model as one YAML file, <game-id>.yaml, following the workflow in "Authoring with an
AI agent": skeleton first, then actions, then expressions until the model is executable, then end
conditions, then content. After every step, check it with the validator at
https://tabletwin.com/validate/ and fix all errors. If you cannot open web pages, give me the
model and I will paste it into the validator and send you what it shows.

Rules: only keys, ops and functions from the reference; English snake_case names; rules and
card texts in your own words; every unclear rule becomes an open_questions entry; nothing
invented.

Done means: no validator errors, 100% executable on the rules layer, 20 of 20 test games finish,
and a short list of open questions. Report the open questions and any rule you could not model.
```

## Done checklist

- [ ] The validator reports no errors; warnings are understood.
- [ ] Rules layer 100% executable (content may be lower while content is still being added).
- [ ] 20 of 20 test games finish, with plausible endings.
- [ ] One game followed step by step in the player looks like the real game.
- [ ] Every content item has a `status`; unclear rules are in `open_questions`.
- [ ] No copied rule or card text.


<!-- https://tabletwin.com/docs/index.md -->

# Tabletwin documentation

A Tabletwin model describes the rules of a board or card game in one YAML file: the rules as data.
You write the model; the site does the rest, in your browser:

| Tool | What it does with your model |
|---|---|
| [Validator](https://tabletwin.com/validate/) | Paste a model (and optionally a view): errors, warnings, how much of it the engine can run, what is still missing, the flow as a tree, and 20 random test games. Then "Open in the player" |
| [Player](https://tabletwin.com/play/) | Plays a game question by question: watch the computer play it, or play seats yourself. Your model from the validator appears as an extra game, next to the built-in ones |
| [Diagram](https://tabletwin.com/diagram/) | Draws the rules as a text tree and as a track diagram; "Draw your own model" draws a pasted model |

Nothing is uploaded: the validator keeps your text in your own browser only. Simulating thousands
of games to measure balance and compare strategies is not yet available on the site.

## Pages

| Read | For |
|---|---|
| [Guide](https://tabletwin.com/docs/guide/) | From rulebook to model: a complete tutorial, the workflow, decision rules, patterns, pitfalls and checks. **Start here.** |
| [Quick reference](https://tabletwin.com/docs/cheatsheet/) | Everything needed to write a model on one page: keys, flow, ops, end conditions, names in scope, checking, complete patterns |
| [Authoring with an AI agent](https://tabletwin.com/docs/authoring-with-ai/) | The workflow and prompt for letting an AI agent write a model from a rulebook |
| [Reference](https://tabletwin.com/docs/reference/) | Every key of a model file: state, actions, ops, flow, windows, triggers, content, end conditions |
| [Expressions](https://tabletwin.com/docs/expressions/) | The expression language of the `_x` fields: syntax, built-in functions, names in scope |
| [Board geometry](https://tabletwin.com/docs/board-geometry/) | Square and hex boards, the geometry functions and own functions |
| [Tactics](https://tabletwin.com/docs/tactics/) | Players as a separate layer: rules per decision place, look-ahead |
| [Views](https://tabletwin.com/docs/views/) | How the table looks in the player: view files |
| [How the engine runs a model](https://tabletwin.com/docs/engine/) | Requests, chance, who sees what, windows, end conditions, executability, the validator's messages, limits |
| [Diagram](https://tabletwin.com/docs/diagram/) | How the diagram is drawn from a model, and the step markers |
| [schema.json](https://tabletwin.com/models/docs/schema.json), [tactic.schema.json](https://tabletwin.com/models/docs/tactic.schema.json) | JSON Schemas for models and tactics: completion and checking in your editor |

To get completion and checking in VS Code (YAML extension by Red Hat), put this on the first line
of a model file:

```yaml
# yaml-language-server: $schema=https://tabletwin.com/models/docs/schema.json
```

and `# yaml-language-server: $schema=https://tabletwin.com/models/docs/tactic.schema.json` on the
first line of a tactic file.

## Examples

Small, fully executable examples, each for a group of patterns. Each model is also a built-in game
in the player and can be loaded in the validator with "Start from".

| File | Patterns |
|---|---|
| [pig.yaml](https://tabletwin.com/models/docs/examples/pig.yaml) | Turn loop, repeat until something happens, push your luck, a die, a winner. The rulebook as comments |
| [pig-tactic.yaml](https://tabletwin.com/models/docs/examples/pig-tactic.yaml) | A tactic: rules per decision place (for `pig.yaml`) |
| [higher-lower.yaml](https://tabletwin.com/models/docs/examples/higher-lower.yaml) | Shuffled deck, a hand per player, hidden information, secret choice, reveal, score |
| [ambush.yaml](https://tabletwin.com/models/docs/examples/ambush.yaml) | Priority window, fast actions with costs, the stack, cancelling |
| [neighbours.yaml](https://tabletwin.com/models/docs/examples/neighbours.yaml) | A grid of cells, choosing a free cell, patterns as a table, whoever just moved wins |
| [auction.yaml](https://tabletwin.com/models/docs/examples/auction.yaml) | A round that stops halfway, an own turn variable, returns larger than 1 |
| [expedition.yaml](https://tabletwin.com/models/docs/examples/expedition.yaml) | Campaign: scenarios, lasting state, reset, end conditions with a scope |
| [hex-skirmish.yaml](https://tabletwin.com/models/docs/examples/hex-skirmish.yaml) | Hex map with gaps, obstacles and difficult terrain; initiative; choosing, resting and losing cards; monsters with focus, movement and line of sight; area attacks with rotation; modifier decks |

More small models, each focused on one feature (all but `modifiers.yaml` are built-in games in the
player):

| File | Patterns |
|---|---|
| [stack-game.yaml](https://tabletwin.com/models/tests/stack-game.yaml) | Cards as instances with their own state, looking at a deck, putting cards on the bottom, shuffling, searching |
| [triggers.yaml](https://tabletwin.com/models/tests/triggers.yaml) | Trigger timing, optional triggers, triggers on content |
| [modifiers.yaml](https://tabletwin.com/models/tests/modifiers.yaml) | Modifiers in layers, temporary modifiers, modifiers on content |
| [spell-duel.yaml](https://tabletwin.com/models/tests/spell-duel.yaml) | Priority windows with `lifo_stack`, costs paid on play, counterspells |
| [subset.yaml](https://tabletwin.com/models/tests/subset.yaml) | Choosing a subset |
| [coop-clock.yaml](https://tabletwin.com/models/tests/coop-clock.yaml) | A cooperative game |
| [campaign.yaml](https://tabletwin.com/models/tests/campaign.yaml) | A small campaign |

Games:

| File | Shows |
|---|---|
| [tictactoe.yaml](https://tabletwin.com/models/games/tictactoe.yaml) | The smallest complete game on a grid |
| [kuhn-poker.yaml](https://tabletwin.com/models/games/kuhn-poker.yaml) | Hidden cards and betting |
| [chess.yaml](https://tabletwin.com/models/games/chess.yaml) | A square board, move generation in own functions (`ray`, `leap`, `neighbours`), castling, en passant, promotion, mate, stalemate and draw rules |
| [eightball.yaml](https://tabletwin.com/models/games/eightball.yaml) | An outcome model for skill, a heuristic agent (`agents` with `policy_x`; "heuristic threshold" in the player) |

The commercial games on the site (The Lord of the Rings LCG, Gloomhaven, Arkham Horror LCG,
Aeon's End, Too Many Bones, Codenames) are shown in the [diagram](https://tabletwin.com/diagram/)
as their rules structure only; their model files are not published. The Lord of the Rings LCG is
the largest executable model: cards as instances, card texts as triggers, modifiers and abilities,
rule procedures as triggers, `end_event` for "until the end of the phase", windows, and loops over
players and enemies (`once`).

Published tactics: [chess-material.yaml](https://tabletwin.com/models/tactics/chess-material.yaml)
and [hex-skirmish-basic.yaml](https://tabletwin.com/models/tactics/hex-skirmish-basic.yaml).
Published views: [chess.yaml](https://tabletwin.com/models/views/chess.yaml),
[hex-skirmish.yaml](https://tabletwin.com/models/views/hex-skirmish.yaml) and
[tictactoe.yaml](https://tabletwin.com/models/views/tictactoe.yaml). The
[commented metamodel](https://tabletwin.com/models/metamodel.yaml) lists every layer of a model in
one file. All games and examples are listed on the [games page](https://tabletwin.com/games/).


<!-- https://tabletwin.com/docs/board-geometry.md -->

# Board geometry and own functions

A model can describe space. A **board** (`boards`) says which cells exist, which cells are
neighbours, and where walls and holes are. **Board functions** in the expression language compute
with it: neighbours, distance, sliding until the first piece, cheapest path, line of sight, area
patterns. **Own functions** (`functions`) bundle rules that come back often, such as "is this
square attacked" in chess or "which cell does this monster walk to" in a skirmish game.

Two fully executable examples, both playable in the [player](https://tabletwin.com/play/) with
their board drawn from the geometry:

| Model | What it shows |
|---|---|
| [chess.yaml](https://tabletwin.com/models/games/chess.yaml) | Square board with 8 neighbours and letter names; all move generation in `functions`, including castling, en passant and promotion |
| [hex-skirmish.yaml](https://tabletwin.com/models/docs/examples/hex-skirmish.yaml) | Hex map with holes, obstacles and difficult terrain; monsters that pick a target, walk and check line of sight; an area attack with rotation |

## 1. Boards

```yaml
boards:
  board: {kind: square, width: 8, height: 8, names: letters, neighbours: 8}
  map:
    kind: hex
    width: 7
    height: 5
    missing: ["3,0", "3,1", "2,3", "1,4"]     # holes: these cells do not exist
    walls: [["0,0", "1,0"]]                    # a wall between two neighbours
```

| Field | On | Default | Meaning |
|---|---|---|---|
| `kind` | all | `square` | `square` or `hex` |
| `width`, `height` | square (required); hex as a rectangle | – | Integers |
| `names` | square | `xy` | `xy`: cell `"3,4"`. `letters`: cell `"e4"` (column `a`…`z`, row from 1; at most 26 columns) |
| `neighbours` | square | 4 | `4` (orthogonal) or `8` (also diagonal) |
| `radius` | hex | – | A hexagonal board around `0,0` with this radius |
| `cells` | hex | – | A list of cells `"q,r"` (any shape) |
| `missing` | all | – | Cells that do not exist: you cannot stand on, move through or see through them. Each must be a cell of the board |
| `walls` | all | – | Pairs of neighbouring cells with a wall between them: blocks `step`, `ray`, `neighbours`, paths and sight, not `leap`. On a square board only orthogonal neighbours can have a wall |
| `label`, `note` | all | – | For people |

A hex board uses `cells` if given, else `radius`, else `width` and `height`.

**Coordinates.** Square: `x` to the right, `y` up; cell `a1` (or `"0,0"`) is `x = 0, y = 0`.
Hex: axial coordinates `q,r` with pointy tops; `r` grows downward. With `width`/`height`, odd rows
are shifted half a cell to the right so the map is a rectangle; the cell names stay axial (row 2
starts at `q = -1`, row 4 at `q = -2`).

**Directions.** Square with 4 neighbours: `n e s w`; with 8: `n ne e se s sw w nw`; `n` is
`y + 1`. Hex, clockwise from east: `e se sw w nw ne` (`e` is `q + 1`, `se` is `r + 1`, `ne` is
`q + 1, r − 1`). Wherever a direction is expected you may also give a vector `[dx, dy]` (hex:
`[dq, dr]`) of integers.

**Cell order.** `cells(b)` lists the cells row by row: square from `y = 0` up, `x` ascending
(`a1, b1, …`); hex rectangle from `r = 0` down; hex radius from `r = −radius`, `q` ascending;
hex `cells` in the given order. Holes are left out.

A board is fixed during play. What stands on it lives in the state: a variable
`{cell: piece}`, or instances in a zone with a `cell` attribute.

**Errors in a board** are validator errors, and `NotExecutable` when the engine loads the model:
`board 'b': kind 'x'; use square or hex`, `... width must be an integer, not None`,
`... names 'x'; use xy or letters`, `... names letters allows at most 26 columns`,
`... neighbours 6; use 4 or 8`, `... cells must be a list of 'q,r' cells`,
`... hex cell 'x'; write 'q,r' with integers`, `... missing names unknown cell 'x'`,
`... cell 'x' appears twice`, `... wall [...]; write [cell, cell]`,
`... wall at unknown cell 'x'`, `... wall between 'a' and 'b'; those cells are not adjacent`.
The validator also warns about a board whose name never appears (in quotes) in any expression.

## 2. Board functions

Available in every expression when the model has `boards`. The first argument is always the
board name. Optional arguments (`?`) default to `None` and may be given by name:
`path('map', a, b, costs=TERRAIN)`.

| Function | Returns | Meaning |
|---|---|---|
| `cells(board)` | list | All cells, in cell order |
| `directions(board)` | list | The direction names of this board |
| `xy(board, cell)` | tuple | Coordinates `(x, y)` (hex: `(q, r)`) |
| `cell(board, x, y)` | cell or `None` | The cell at these integer coordinates; `None` off the board or on a hole |
| `step(board, cell, direction)` | cell or `None` | One step; `None` off the board, onto a hole, or through a wall |
| `leap(board, cell, direction)` | cell or `None` | Like `step`, but over walls (a knight's move is `[1, 2]`) |
| `ray(board, cell, direction, occupied?)` | list | Cells in that direction up to the edge, a hole or a wall, or up to and including the first cell in `occupied` |
| `neighbours(board, cell)` | list | Adjacent cells, without walls and holes, in the order of `directions` |
| `distance(board, a, b)` | integer | Hex: steps. Square: with 4 neighbours `abs(dx) + abs(dy)`, with 8 `max(abs(dx), abs(dy))`. Ignores walls and holes |
| `path(board, start, goal, blocked?, costs?, through?)` | list or `None` | Cheapest path: the cells after `start`, ending with `goal`. `[]` if `start == goal` |
| `path_cost(board, start, goal, blocked?, costs?, through?)` | number or `None` | Cost of that path; `0` if `start == goal` |
| `reachable(board, start, points, blocked?, costs?, through?)` | list | Cells reachable with at most `points`, cheapest first, without `start` |
| `line_of_sight(board, a, b, corners?, blockers?)` | bool | Is there a clear line from `a` to `b` |
| `shape(board, cell, pattern, turns?)` | list | The cells of a pattern placed at `cell`, rotated `turns` times clockwise |

`occupied`, `blocked`, `through` and `blockers` are anything that supports `in`: a list, a set,
or a dict (its keys).

**Paths.** Dijkstra over `neighbours`.
- `blocked`: cells you may not enter (enemies, obstacles).
- `through`: cells you may pass but not end on (allies).
- `costs`: `{cell: cost}`, the cost of entering that cell (default 1; must be a number ≥ 0),
  e.g. 2 for difficult terrain.
- `path` and `path_cost` give `None` if `goal` is unreachable, or is in `blocked` or `through`
  (unless `start == goal`). `start` itself is never checked against `blocked`.
- `reachable` leaves out `start` and the `through` cells.
- On equal cost the path found first wins (neighbours in the order of `directions`), so the
  result is always the same.

**Line of sight.** The line runs from centre to centre. With `corners` true, the engine tries
lines from every corner of `a` to every corner of `b` (corners moved 5% toward the centre) and
there is sight if any one of them is clear. A line is blocked if a sample point falls off the
board or on a hole, if it crosses a wall between two consecutive cells, or if it enters a cell in
`blockers` (other than `a` and `b`). The line is sampled 8 times per unit of length (a square
cell is 1 wide; hex centres are √3 apart), so a line that grazes a corner exactly does not count
as blocked. `a == b` is always `True`.

**Patterns.** A list of directions or vectors, relative to `cell`. `[[0, 0], 'e', 'se']` is a
triangle of three hexes. `turns` rotates clockwise by 60° (hex) or 90° (square); negative values
rotate counter-clockwise. Cells off the board or on holes are left out; duplicates appear once;
walls do not matter. All rotations: `[shape('map', t, P, k) for k in range(6)]`.

**Errors.** Board function errors are `ValueError`s and appear like any expression error
(`error evaluating '...': ValueError: ...`), for example:
`cell 'z9' does not exist on board 'map'`, `direction 'up' does not exist on board 'map'`,
`direction [1]: a vector is [dx, dy] with integers`, `board 'mpa' does not exist`,
`x must be an integer, not 1.5`, `costs must be a dict {cell: cost}, not [...]`,
`cost of '2,2' must be a number ≥ 0, not -1`, `reachable: points must be a number, not None`,
`shape: pattern must be a list of vectors or directions, not 'e'`, and for arguments:
`path() is missing argument 'goal'`, `path() has no argument 'cost'`,
`path() got 'blocked' twice`, `step() takes at most 3 arguments, not 4`.

With English names, take care not to hide a board function: a local name, variable or zone named
`cell`, `step` or `path` hides the function of that name (see
[expressions.md § Names in scope](https://tabletwin.com/docs/expressions/#6-names-in-scope)). An own function may not
take such a name.

## 3. Own functions

```yaml
functions:
  enemy:
    params: [k]
    x: "'b' if k == 'w' else 'w'"
  in_reach:
    text: "within range (around walls) and in sight"
    params: [a, b, reach]
    let:
      cost: "path_cost('map', a, b) if distance('map', a, b) <= reach else None"
    x: "cost is not None and cost <= reach and line_of_sight('map', a, b, True)"
```

| Field | Meaning |
|---|---|
| `params` | Parameter names (`^[A-Za-z][A-Za-z0-9_]*$`). `name?` is optional (default `None`). Call by position or by name |
| `let` | Helper values `{name: expression}`, computed top to bottom; each sees the parameters and earlier `let`s |
| `x` | The result (required) |
| `text`, `note` | For people |

A function sees its parameters, its `let`s, the constants, `content`, the state (zones,
variables, derived values), `modified`, the board functions and the other functions (itself too:
recursion is allowed up to 100 calls deep). It does **not** see the local names of its caller
(`actor`, `self`, bound names): pass them as arguments. A parameter hides a variable or zone of
the same name. A function changes nothing; ops do that.

Functions work wherever an expression is allowed: `pre_x`, `options_x`, `value_x`, end
conditions, `init_x`, tactics. The name must not clash with a constant, variable, zone, derived
value, builtin, board function (when the model has boards) or reserved name; the validator and
the engine both reject it (`function 'x': that name already exists`). Other validator checks:
`no x`, `params must be a list of names`, `parameter 'x' is not a name`,
`let must be a dict {name: expression}`, and a warning for a function that is never called.

Argument errors look like those of board functions: `in_reach() is missing argument 'reach'`.

## 4. Patterns

**Sliding pieces.** With a variable `pieces` of the form `{cell: piece}` (a piece is text like
`'wR'`, colour first) and `colour` the side to move, all rook moves from `c`:

```python
[n for d in ['n', 'e', 's', 'w'] for n in ray('board', c, d, pieces) if pieces.get(n, '-')[0] != colour]
```

`ray` stops on the first occupied cell and includes it, so an own piece is filtered out and an
enemy piece can be captured. A knight: `[n for v in [[1, 2], [2, 1], [2, -1], [1, -2], [-1, -2],
[-2, -1], [-2, 1], [-1, 2]] for n in [leap('board', c, v)] if n is not None]`.

**Is a cell attacked?** Look outward from the cell: knight leaps, king neighbours, pawn
diagonals, and per line the first piece (`ray(...)[-1]`). A function `legal` then drops the
moves after which the own king is attacked. [chess.yaml](https://tabletwin.com/models/games/chess.yaml)
does it this way.

**A monster walking to its target.**
1. Attack cells: empty cells from which the monster can hit a hero (`in_reach` above).
2. Focus: the hero with the cheapest attack cell (`path_cost` with enemies as `blocked` and
   allies as `through`).
3. Destination: the cheapest attack cell within its movement (`reachable`), else the cell that
   gets closest to one.

**Area attack.** For each cell in range and in sight, and each rotation, the targets in
`shape(...)`; count each hit once.

```python
[[c for c in shape('map', t, AREA, k) if c in occupied] for t in targets for k in range(6)]
```

(`targets` being the cells in range and in sight, `AREA` a pattern constant and `occupied` the
cells with monsters. Sets have no `&`; filter with `in` instead.)

[hex-skirmish.yaml](https://tabletwin.com/models/docs/examples/hex-skirmish.yaml) works these out
in full.

## 5. Limits

- On a square board with 8 neighbours a wall only blocks the orthogonal step across it; a
  diagonal step past the end of a wall is still possible.
- Line of sight is sampled: a line that crosses less than an eighth of a unit through the corner
  of a hole can be missed.
- Boards are fixed. A map that changes during play (a door that opens) is modelled with a
  variable passed as `blocked` or `blockers`.


<!-- https://tabletwin.com/docs/tactics.md -->

# Tactics: players as a separate layer

A model describes the rules. A **tactic** describes how someone plays: at which decision they
choose what. It is a separate YAML file next to the model, written in the same
[expression language](https://tabletwin.com/docs/expressions/). The engine runs it like any other player, so a tactic can
be watched game by game, compared with another tactic, and get look-ahead on top.

**On the site.** The [player](https://tabletwin.com/play/) has tactics for some of its built-in
games: Pig ("stop at 8"), chess ("material") and the hex skirmish ("basic"). Pick one under
Players and follow its decisions question by question. Loading your own tactic file is not yet
available on the site, and neither are look-ahead or comparing tactics over many games. This page
describes the tactic language, so that tactics can be written, read and shared now.

The JSON schema for editor completion is
[tactic.schema.json](https://tabletwin.com/models/docs/tactic.schema.json); put
`# yaml-language-server: $schema=https://tabletwin.com/models/docs/tactic.schema.json` on the
first line of a tactic file. The published tactics are
[pig-tactic.yaml](https://tabletwin.com/models/docs/examples/pig-tactic.yaml),
[chess-material.yaml](https://tabletwin.com/models/tactics/chess-material.yaml) and
[hex-skirmish-basic.yaml](https://tabletwin.com/models/tactics/hex-skirmish-basic.yaml).

## The smallest example

For a Pig model with a step `choice` that offers `roll` and `stop`, a variable `pot`, a per-player
`score` and a constant `GOAL` (see [pig.yaml](https://tabletwin.com/models/docs/examples/pig.yaml)):
keep rolling until the pot is 8, or until stopping wins.

```yaml
tactic: pig-hold-at-8
game: pig
rules:
  - at: step choice
    when_x: "pot >= 8 or score[me] + pot >= GOAL"
    pick: stop
  - at: step choice
    pick: roll
```

Against a random player this tactic wins about 75% of games (measured over 2000 games). The
finished example is [pig-tactic.yaml](https://tabletwin.com/models/docs/examples/pig-tactic.yaml):
in the player, choose Pig and "tactic stop at 8 vs random" to watch it.

## The file

| Key | Type | Default | Meaning |
|---|---|---|---|
| `tactic` | text | `?` | Name of the tactic |
| `game` | text | | `game` id of the model the tactic is for |
| `label`, `summary`, `note` | text | | For people |
| `extends` | path | | Base tactic, relative to this file (see [variants](#variants-with-extends)) |
| `let` | `{name: expression}` | `{}` | Helper values, computed lazily per decision |
| `rules` | list | `[]` | Rules, tried top to bottom |
| `default` | `random` / `first` | `random` | What happens when no rule decides |
| `search` | dict | `{}` | Places where look-ahead is used (see [look-ahead](#look-ahead-search)) |

The schema requires `tactic`, and `rules` or `extends`.

## Decision places

The engine asks each decision at a **place**. The name follows from the model:

| Place | When | Options |
|---|---|---|
| `step <id>` | A step with several legal actions in `do` | action names |
| `action <name>` | A `choose` or `search` in an action's `effect` (also an ability on a content item) | the options of the choice |
| `action <name> (cost)` | A `choose` in an action's `cost` | idem |
| `trigger <id>` | An optional trigger (`use`, `skip`), or a `choose` in a trigger's `do` | idem |
| `window <name>` | A priority window | the playable fast actions and `pass` |
| `content <id>` | A `choose` in a content item's `effect` run by `exec` | the options of the choice |

A subset choice (`choose` with `min`/`max`) asks one element at a time at `<place> · 1`,
`<place> · 2`, ...; tactics match the place without that suffix. A `choose` inside the impact of an
`emit` has the place `<place of the emit> · <event>`. The [engine page](https://tabletwin.com/docs/engine/#places-where) has
the full list.

To see the places of a model, open it in the player: every question shows its place, its options
and who decides. A rule whose `at` names a place that never occurs is simply never used, so check
the spelling against what the player shows.

## Rules

Rules are tried from top to bottom; the first rule that decides, picks. If none decides, `default`
does: `random` (a random option) or `first` (option 0).

| Field | Meaning |
|---|---|
| `at` | Place, or list of places. Required. Shell-style wildcards: `*`, `?`, `[abc]`, `[!abc]` (`window *`, `trigger *`) |
| `options` | The rule only applies if the option labels are exactly this list, in order (`[use, skip]`) |
| `when_x` | The rule only applies if this expression is true |
| `pick` | Pick the option with this label. If there is none, the rule does not decide |
| `pick_x` | An expression that returns an option or a label; the option that is the same object or has the same label is picked. No match: the rule does not decide |
| `max_x` / `min_x` | Score each option `o` (index `i`); the highest (lowest) wins, the first on a tie. A tuple compares field by field |
| `take_x` | For subset choices: take candidate `o`? The first candidate for which it is true is picked; none: `done`; if `done` is not offered yet (fewer than `min` chosen): the first candidate |
| `note` | For people |

Every rule needs exactly one of `pick`, `pick_x`, `max_x`, `min_x`, `take_x`, and an `at`;
otherwise the tactic cannot be loaded (`NotExecutable: tactic <name>: rule 3 (...) has 2 pick
fields`).

```yaml
rules:
  - at: trigger guard_dog
    options: [use, skip]
    pick: use
  - at: action attack
    max_x: "(o['damage'], -o['cost'])"          # most damage, then cheapest
  - at: window *
    when_x: "hp[me] <= 2"
    pick: heal
  - at: window *
    pick: pass
```

**Subsets.** The engine asks a subset one element at a time: each time the remaining candidates
plus `done` (once the minimum is reached). `take_x` is computed per candidate, with `pool` (all
options of the choice) and `chosen` (what is already chosen). Compute what you want once in a `let`
and ask per candidate whether it belongs: `take_x: "o['uid'] in questers"`.

## What is in scope

| Name | What |
|---|---|
| Everything global in the model | Zones, variables, derived values, constants, `content`, `players`, `n_players`, `eliminated`, `results`, board and own functions, `modified(...)` |
| `opts`, `labels` | The options of this decision (for a subset: the items behind the labels, `None` for `done`) and their labels |
| `o`, `i` | In `max_x`, `min_x`, `take_x`: the option and its index |
| `pool`, `chosen` | For a subset: all options of the choice, and what is chosen so far. Otherwise `pool` is `opts` and `chosen` is `[]` |
| `where`, `me` | The place (without ` · n`) and the deciding player |
| names from `let` | Helper values, computed only when a rule uses them (also through another `let`) |

The local names of the engine at that moment (`actor`, `stack` and `window` in a priority window,
names bound by `let` or `choose` in the action) are **not** in scope; use `me` for the deciding
player. If a tactic needs to know what is on the stack, the model must keep it in a variable. A
tactic reads the full state, including hidden zones and other players' hands: not reading what the
player cannot know is up to the author.

The expression language has no `lambda`. Sort by a key with tuples:
`[t[2] for t in sorted((-c['willpower'], i, c) for i, c in enumerate(pool))]` (the index `i`
keeps the sort from comparing the cards themselves on equal keys).

## Look-ahead (`search`)

A tactic can name places where a player looks ahead instead of following the rules blindly.
Look-ahead is not yet available on the site; this section describes what the `search` key means.

At the places in `search.at` the player compares every other option with the option the rules
pick:

1. Each round takes `n` new random seeds (`search.rollouts`, default 8).
2. For each option and each seed it makes a copy of the state in which what the player cannot know
   is redistributed (see below), plays that option, and plays the game out with the tactic for all
   players. All options use the same seeds (paired).
3. After each round, per alternative `a`, with `d` the per-seed differences between `a` and the
   rules' option, `m` their mean and `se` its standard error:
   - `m + z·se <= 0` (worse, or not distinguishable): `a` drops out;
   - `m − z·se > 0` (proven better): `a` is a candidate.
   If there are candidates, the one with the highest mean is chosen.
4. When no alternative is left, or after `max_rollouts` rollouts per option, the rules' choice
   stands.

```yaml
search:
  at: [action commit, step defend]     # places (wildcards allowed)
  rollouts: 8          # seeds per round
  max_rollouts: 32     # default 4 × rollouts
  z: 2                 # standard errors of proof needed to deviate from the rules (default 2)
```

Decisions with fewer than two options, and places not in `search.at`, are never searched.

**Why a test.** In a game like LotR LCG good and less good options differ by a few percentage
points of win rate. That is less than the noise of a few dozen rollouts. "Take the highest mean"
then picks by chance, and chance makes a good player worse. Measured: without the test the
standard LotR tactic dropped from 25% to 5% wins, while a diagnosis with 200 rollouts per option
showed that the rules often already picked the best option.

**No peeking.** A copy of the state knows everything, face-down cards included. So the search
first redistributes what the player cannot know. Drawing from a shuffled zone is already fair: the
order is only fixed when a card is drawn. Face-down cards that are already on the table (shadow
cards on an enemy) must be marked in the model with `drawn_from`:

```yaml
shadow: {kind: set, visibility: hidden, drawn_from: encounter_deck}
```

The search then shuffles those cards together with the unknown part of the encounter deck and
deals them back. Counts and identities (`uid`) stay the same; only which card each one is changes.

## Comparing tactics

The fair way to compare two players is on the same rules and the same seeds (paired), over
hundreds or thousands of games, with a confidence interval on the difference in win rate. A
variant that changes one rule then measures exactly that rule. Running such comparisons is not yet
available on the site.

## Variants with `extends`

Do not copy a tactic to change one thing; build on it with `extends`:

```yaml
tactic: lotr-quest-wide
game: lotr-lcg
extends: lotr-standard.yaml
let:
  quest_margin: "5"     # the base uses 2
```

How the files merge:

- `rules`: the variant's rules come first, then the base's;
- `let`: merged, the variant's values win;
- every other key (`label`, `default`, `search`, ...): the variant's value replaces the base's
  (`search` as a whole, not per field);
- `extends` paths are relative to the file that names them; a cycle is an error.

So put the numbers you want to vary in the base as `let`.

## Testing a tactic

- Expressions in `let` and in the rules must be valid expressions; every rule needs an `at` and
  exactly one pick field.
- Every rule belongs to a place that exists: compare the `at` values with the places the player
  shows. Places without a rule of their own fall back to general rules (`window *`) or to
  `default`.
- Watch it choose. For the built-in games with a tactic, pick the tactic under Players in the
  player and step through a game: at each question you see the options and what was picked. Play
  a seat yourself against it to try situations.
- If the same strategy exists elsewhere (as another tactic, or written down as rules of thumb),
  check that both take the same decisions in the same positions.

## Pitfalls

1. **Order.** The first rule that decides wins. Put specific rules (one trigger) above general ones
   (`trigger *`).
2. **`pick` on a missing label does not decide.** The next rule gets its turn; put a catch-all at
   the bottom if that is not intended.
3. **Optional triggers and choices in the same trigger share their place.** Tell them apart with
   `options: [use, skip]`.
4. **One option is not a decision.** The engine asks nothing when there is only one option; a rule
   for that place is then never used.
5. **A tactic is not a rule.** What the rulebook prescribes belongs in the model. A tactic only
   chooses among what the rules allow.
6. **No engine locals in a tactic.** `actor`, `stack` and bound names give a `NameError`. Use `me`.


<!-- https://tabletwin.com/docs/views.md -->

# Views: how a game lies on the table

A game has three layers, each in its own file:

| Layer | File | Read by |
|---|---|---|
| Rules | the model | engine, validator, diagram, player |
| Players | a tactic | the engine, as a player (see [tactics](https://tabletwin.com/docs/tactics/)) |
| View | a view | the [player](https://tabletwin.com/play/): the Board tab of the table |

The engine never reads a view: it changes nothing about the rules or the results.

**Using a view with your model.** In the [validator](https://tabletwin.com/validate/), paste the
view into "View (optional YAML)" below the model and press Check. "Open in the player" then opens
your model with that view. The validator only checks that the view is readable YAML ("The view
cannot be read" otherwise); a slot that names a zone, variable or board the model does not have
shows up in the player (for example "board x not found"). The built-in games of the player come
with their own views; "Start from" in the validator loads an example together with its view.

Without a view the player lays out the table itself: shuffled or hidden zones as a deck, open
zones as a row, a meter for every per-player variable with a numeric `init`, and an area per
player for the zones with `owner: player`.

Cards are drawn as typographic cards (name, type, numbers, tokens), never as the original artwork.
What a viewer sees follows the visibility in the model: in the player you can "view as player p",
and hidden zones and other players' hands then show only card backs.

## Structure

```yaml
view: my-card-game                  # label only; the view belongs to the model it is used with

card:
  lang: en                          # language of card names, for hyphenation (default en)
  type_field: type                  # field with the card type (small text in the colour band)
  type_names: {hero: Hero, ally: Ally}            # optional: display names of the types
  color:                            # colour band: the first entry that matches
    - {field: sphere, values: {leadership: "#6d4c9f", tactics: "#a53a2c"}}
    - {field: type, values: {enemy: "#6b4a32"}}
  corner: [cost, threat]            # number top right: the first of these fields the card has
  stats:                            # numbers at the bottom, with an icon
    - {field: willpower, icon: "✦", name: willpower}
    - {field: hp, icon: "♥", name: hit points}
  tokens:                           # numbers on the instance shown as tokens on the card
    damage: {color: "#c0392b", name: damage}
  sideways: exhausted               # turn the card sideways while this property is true

table:                              # the middle of the table, row by row
  - row:
      - {zone: encounter_deck, as: deck}
      - {zone: encounter_discard, as: discard}      # top card face up
      - {quest: {var: quest_card, catalogue: quests, progress: progress, goal: quest_points}}
      - {zone: staging, name: staging area, wide: true}

player:                             # the area of every player (per-player zones show that player's part)
  - row:
      - {meter: {var: threat, max: 50, name: threat}}
      - {zone: heroes, attachments: {zone: attachments, field: host}}
      - {zone: hand, small: true, wide: true}
```

### `card`

| Key | Type | Default | Meaning |
|---|---|---|---|
| `lang` | text | `en` | Language of the card names (the `lang` attribute, for hyphenation) |
| `type_field` | text | `type` | Field that holds the card type |
| `type_names` | `{type: name}` | | Display name per type; otherwise the type itself |
| `color` | list of `{field, values}` | | Colour band: the first entry whose `field` value is in `values`. No match: a colour derived from the type |
| `corner` | list of fields | | Number in the top right corner: the first listed field that holds a number |
| `stats` | list of `{field, icon, name}` | the first 4 numeric fields of the content item | Numbers along the bottom; `name` is the tooltip |
| `tokens` | `{property: {color, name}}` | | Numeric properties of the instance shown as coloured tokens. Without `tokens`, every positive number on the instance that the content item does not have is shown as a token |
| `sideways` | property | | The card is turned sideways while this property is true |

A card's fields are the content item's fields (looked up by `id`) overlaid with the current
properties of the instance. Properties that are `true` (other than `sideways`) show as tags.

### `table` and `player`

Both are lists of rows: `- row: [slot, slot, ...]`. `table` is drawn once; `player` once per
player, and a per-player zone in it shows that player's part.

| Slot | Key | Meaning |
|---|---|---|
| Zone | `zone` | Name of a zone in the model |
| | `as` | `row` (all cards side by side), `deck` (a face-down pile with a count) or `discard` (a pile with the top card face up, if the viewer may see it). Default: `deck` for shuffled or hidden zones, `row` otherwise |
| | `name` | Heading; default the zone name |
| | `wide` | Take the rest of the row |
| | `small` | Smaller cards |
| | `attachments: {zone, field}` | Cards from that zone whose `field` equals the `uid` of a card in this zone are shown under it |
| Meter | `meter: {var, max, name}` | A dial for a numeric variable; for a per-player variable, that player's value. `max` default: the larger of 10 and the value |
| Quest | `quest: {var, catalogue, progress, goal}` | A landscape card: the item `content[catalogue][<value of var>]` (or the content item with that `id`), with the variable `progress` against `goal` (a derived value or variable; default the card's `quest_points`) |
| Grid | `board: {zone \| var, columns}` | A grid of cells from a zone or a list variable, `columns` wide (default 3); `None` shows as empty |
| Board | `board: {geometry, ...}` | A board from the model's `boards` with pieces; see below |

Every slot may have a `name`. Cards that are new since the previous request get a highlight, and a
meter shows its change.

The smallest view, for a 3 × 3 grid kept in a zone `board`:

```yaml
view: tictactoe
table:
  - row:
      - {board: {zone: board, columns: 3}, name: board}
```

## Boards with geometry

A board from `boards` (see [board geometry](https://tabletwin.com/docs/board-geometry/)) is drawn with the same geometry as
the engine: square with coordinates, hex with gaps drawn as walls, walls between cells as lines.
Cells that changed since the previous request get a highlight (in chess: the from and to squares).

```yaml
table:
  - row:
      - name: chessboard
        board:
          geometry: board                 # name in the model's boards
          pieces: {var: pieces}           # a dict cell → piece
          checkered: true
          flip: true
          names: true
          icons:
            wK: {icon: "♚", color: white}
            bK: {icon: "♚", color: black}
      - name: dungeon
        board:
          geometry: map
          pieces: {zone: figures, field: cell}           # instances with a property cell
          color: {field: side, values: {hero: "#2f6fb3", monster: "#a53a2c"}}
          value: hp                                      # number on the token
          cells:                                         # highlighted cells (with a legend)
            - {const: OBSTACLES, color: "rgba(120, 100, 70, .65)", name: obstacle}
            - {const: TERRAIN, color: "rgba(110, 160, 80, .42)", name: difficult terrain}
```

| Key | Meaning |
|---|---|
| `geometry` | Name of the board in the model's `boards`. Unknown: a "board not found" notice |
| `pieces` | `{var}`: a dict cell → piece (text, or a dict whose `label` or `id` names it). `{zone, field}`: the instances in a global zone, placed on the cell in their property `field` (default `cell`); fixed fields come from the content item, or from a dict with that `id` in `constants` |
| `icons` | Piece label (or `id`) → icon text, or `{icon, color}` with `color: white`, `black` or a CSS colour. Without an icon: a round token with the first letters of the label |
| `color` | `{field, values}`: token colour from a property of the piece |
| `value` | Property shown as a number on the token |
| `cells` | List of `{const \| var, color, name}`: the cells in a constant or variable (a list of cell names, or a dict whose keys are cell names) get that colour; `name` goes into the legend |
| `checkered` | Alternate light and dark squares (square boards) |
| `flip` | Turn the board around when viewing as player 1 |
| `names` | Show cell names (square: `a–h` and `1–8` for `letters` boards, else numbers; hex: the cell name in each cell) |

Clicking a piece or card shows its properties. Complete views, used by the player for the
built-in games of the same name: [chess](https://tabletwin.com/models/views/chess.yaml),
[hex-skirmish](https://tabletwin.com/models/views/hex-skirmish.yaml) and
[tictactoe](https://tabletwin.com/models/views/tictactoe.yaml).


<!-- https://tabletwin.com/docs/engine.md -->

# How the engine runs a model

The engine runs a model as a sequence of **requests**. At each request whoever plays (a person in
the [player](https://tabletwin.com/play/), or an agent) answers with one of the options, or chance
picks an outcome. The same engine runs the [validator's](https://tabletwin.com/validate/) test
games and the player, in your browser. This page describes exactly what the engine does with each
part of a model, who sees what, how executability is measured and what the validator reports. The
keys themselves are listed in the [reference](https://tabletwin.com/docs/reference/); the expression language is in
[expressions](https://tabletwin.com/docs/expressions/).

## Requests

| Request | What it carries | The answer |
|---|---|---|
| **Decision** | The deciding player, the options, the place (`where`), and who sees the answer | One of the options |
| **Chance** | The possible outcomes with their probabilities, the place, and who sees the outcome | One outcome, drawn with those probabilities |
| **End** | The payoff per player (one number each) and the reason | Nothing: the game is over |

- Who sees the answer is either everyone, or a list of players (an empty list: nobody).
- A decision inside a subset choice (`choose` with `min`/`max`) also knows the item behind each
  option (nothing for `done`), all options of the choice, and what has been picked so far. Tactics
  read these as `opts`, `pool` and `chosen`.
- The reason is the `id` of the end condition that ended the game, or
  `flow finished without an end condition`.
- An option is shown by its label: a dict shows its `label`, else its `id`, else its `uid`, else
  `?`. Two instances of the same card therefore look the same to a player.

### Places (`where`)

Every request names the place it comes from. Tactics match rules on these names (`at:`), and the
player shows the place of every question.

| Place | Where it comes from |
|---|---|
| `step <id>` | Choosing between the legal actions of a step |
| `action <name>` | An op in the `effect` of action `<name>` (also an ability on a content item) |
| `action <name> (cost)` | An op in the `cost` of that action |
| `trigger <id>` | An optional trigger (`use` / `skip`), or an op in a trigger's `do`. A trigger on a content item without its own `id` uses the item's `id` |
| `window <name>` | Priority in window `<name>`: the playable fast actions plus `pass`. A window opened with `window: true` (no name) is `window None` |
| `content <id>` | An op in the `effect` of a content item run by `exec` |

Suffixes: a subset choice adds ` · n` (the n-th element being chosen, from 1); an op in the
`impact` of an `emit` gets ` · <event>` after the place of the `emit`; a `sample` chance adds
` · <outcome model>`. The ops `if`, `for_each`, `repeat` and the effect of an outcome keep the
place of their parent. Two more names only appear in error messages: `end <node id>` (emitting an
`end_event`) and `<place> · window` (a `window` op). Decisions inside a window opened by a `window`
op are still `window <name>`, and the actions played there are `action <name>`.

## Start of a game

1. **Constants**, as written in the model.
2. **Variables**, in declaration order. `init_x` may read constants, `content`, `players`,
   `n_players`, board and own functions and the variables declared *before* it (not zones, not
   derived values). `init` is copied as is (`null` is `None`). With `scope: player` a value that is
   not a list is repeated for every player; a list is taken as the per-player list.
3. **Zones**, in declaration order. `init_x` gives the contents (for `owner: player`: a list of
   lists) and may read every variable. Without `init_x` a zone is empty (per player: one empty list
   each). Every dict in the initial contents becomes an **instance** with its own `uid`.

The site always runs a model with the values written in it. To try another value, change the
constant in the model and check it again.

**Instances.** `create` (and a zone's `init_x`) turn a dict into an instance: a fresh dict with a
unique `uid`. A dict that is model data (from `content` or `constants`) is not copied whole: its
atomic fields (numbers, text, booleans, `null`) are copied and the source dict itself is kept under
the key `origin` (so nested fields stay readable as `x['origin']['effect']`). Writing an attribute of
model data is an error (`... is model data; make an instance with create first`).

## Running the flow

The engine walks the flow tree depth first.

| Node | What happens |
|---|---|
| `sequence` | Children in order |
| `loop` | Before every round: if `until_x` is true, the loop ends. With `over_x`: the list is evaluated at the start of the round; for each value the variable named in `as` is set and all children run. Without `over_x`: the children run once per round. With `once: true` the loop stops after one round. After 10,000 rounds: `ExprError: flow <id>: loop does not end` |
| `branch` | The children of the first case whose `when_x` is true; none true: nothing. A case without `when_x` is `NotExecutable` |
| `subflow` | Clears `results[<ref>]`, then runs flow `flows.<ref>` as a scope (see end conditions with `scope`) |
| `step` | See below |

After a node has finished: if it has `window`, that priority window opens; then, if it has
`end_event`, each listed event is emitted in order, with an end check after each. On a loop both
happen once, after the whole loop, not per round.

`until_x` is only tested at the start of a round, never halfway. `over_x` is not re-evaluated
during a round: a player who is eliminated halfway still gets a turn in that round unless an action
condition prevents it.

### A step

1. Evaluate `actor_x` if present (otherwise there is no actor).
2. The legal actions are those in `do` whose `pre_x` is true, with `actor` in scope (and `self` for
   an ability). An action with `pre` but no `pre_x` is `NotExecutable`.
3. No legal action: the step is skipped. **No end check.**
4. One legal action: it is taken without asking. The player lists it under "automatic", with
   what happened after the previous question.
5. Several: a decision for `actor` at `step <id>` (no actor: `NotExecutable: step <id>: choice
   between actions without actor_x`). With `secret: true` only the actor sees the choice; with
   `visible_to_x` the listed players.
6. Run the action's `cost`, then its `effect`, with local names `{actor}`.
7. **End check.**

## Effects and ops

An effect is a list of ops run top to bottom. Local names (`actor`, names bound by `choose`, `roll`,
`let`, `look`, `search`, `create`) live in one dict per action run: `cost` and `effect` share it,
and so do `if` branches and `repeat` bodies. Four places get a **copy**, so names bound inside are
gone afterwards: a `for_each` body (per item), the impact and the triggers of an `emit`, the effect
of an outcome model, and the effect of an `exec`. Use a variable to remember something across
those boundaries.

Which ops ask something:

| Op | Request |
|---|---|
| `choose` | A decision when there are 2+ options. One option: taken without asking. No options: `ExprError` (except a subset choice, which then binds `[]` when `min` is 0) |
| `search` | A decision among the matches (via `choose`; secret unless `visible_to_x`) |
| `roll` | A chance, uniform over the faces |
| `sample` | A chance with the probabilities `p_x` of the outcome model (must add up to 1 within 1e-6) |
| `draw` from a `shuffled` zone | A chance, uniform over the cards whose position is not known, unless the top card is known or only one unknown card is left |
| `look` at a `shuffled` zone | A chance per looked-at card whose position is not yet known |
| `window` | The decisions of the priority window |
| `emit` | `use` / `skip` decisions for optional triggers, plus whatever the triggers ask |

### Fields: text or expression

For most fields the engine reads `<field>_x` (an expression) if present, else `<field>` if it is a
literal that is not text (number, list, bool). Text without `_x` is a description for people:
the engine stops with `NotExecutable: <place>: field '<field>' is text without <field>_x`. The
exception is `value` on `set` and `let`, where text is a literal string (`value: open` sets
`'open'`). A required field that is missing gives `NotExecutable: <place>: field '<field>' is
missing`.

The engine reads only `pre_x`, `cond_x`, `if_x` (triggers, modifiers, end conditions), `when_x`,
`until_x`, `over_x`, `actor_x`, `who_x`, `returns_x`, `first_x`, `controller_x`, `change_x`,
`active_x`, `filter_x`, `visible_to_x`, `with_x`, `of_x` (exec) and `p_x` as expressions; their
text twins are documentation. A trigger `if`, a branch case `when`, an action `pre`, an `if` op
`cond`, `exec` `of` and `protocol.first` without their `_x` are `NotExecutable`. A loop's `until`
or `over` without `_x`, and an end condition without `if_x`, are **silently ignored**: the loop
runs forever (until an end condition) or not per player, and the end condition never fires.
The validator's gap list ("What the engine still misses") shows all of these.

### Deck order

Index 0 of a zone is the top. `draw` and `look` take from the top. A zone with `shuffled: true` has
an unknown order except for a known top and bottom:

- known on top: after `look`, or after `move`/`create`/`draw` with `position: top`;
- known at the bottom: after `move`/`create`/`draw` with `position: bottom`;
- everything else is unordered; a chance decides which card it is only when it is drawn or looked
  at;
- an item added without `position` goes between the unknown cards (or at the end if no bottom is
  known);
- `shuffle` (with `zone`) forgets the known top and bottom. It does not reorder anything: the
  randomness is in drawing.

Drawing takes the known top first, then a chance over the unknown middle, and only when that is
empty the known bottom. From a zone that is not shuffled, `draw` always takes element 0. `draw`
stops early when the source is empty.

### Events and triggers

`emit` appends the event name to the game's event list and runs:

1. triggers with `timing: when` or `before`;
2. triggers with `timing: instead`: the **first** one that fires replaces the impact;
3. the `impact` ops, if no instead-trigger fired;
4. triggers with `timing: after` (the default).

Within each phase: mandatory triggers first, then optional ones; within those, model triggers in
model order, then triggers on content items. `if_x` is evaluated just before the trigger would
fire, so an earlier trigger can switch off a later one. A content trigger only counts while the
item's `active_x` is true (default: always). An optional trigger asks its controller (`controller_x`,
else the `actor` of the emitting place; neither: `NotExecutable`) `use` or `skip` at
`trigger <id>`. An instead-trigger that fires adds the event `instead:<id>`.

Triggers see the local names of the place that emitted, plus `event` (the event name) and, on a
content item, `self`. A trigger that reads a name another emitting place does not bind fails with
a `NameError` there. Triggers may emit events; more than 50 nested emits is
`ExprError: ... trigger chain too deep`. When the emit is done, temporary modifiers whose `until`
equals this event expire.

A trigger belongs to a content *item* (the card type), not to one instance: with two copies in
play it still fires once per event. Select the instance in `if_x` through the emitter's local
names, for example `"card['id'] == self['id']"`.

### Modifiers

`modified('stat', base, name=value, ...)` starts from `base` and applies every active modifier
for `stat`: the model's `modifiers`, those on content items, and temporary ones from `modify`.
Order: by `layer` (low first, default 0); within a layer, static modifiers in model order and then
temporary ones in the order they were added. For each: skip it if the item's `active_x` or the
modifier's `if_x` is false; else `value` becomes `change_x`. Scope: `value`, the keyword arguments
of `modified()`, `self` on a content item, and for `modify` the local names at the time it ran
(minus `stack` and `self`). A modifier without `change_x` is `NotExecutable`; modifiers that call
`modified()` on each other more than 20 deep raise `ExprError: modifiers for 'x' refer to each
other in a cycle`. A `modify` without `until` lasts until the next campaign `reset`.

### Priority windows

A window opens after a flow node with `window: <name>` (or `window: true`), or through the op
`{op: window, name: <name>}`. Candidates are all actions and content abilities with a `speed` that
the window's `allows` lists (`window: true` or a `window` op without `name`: every speed). The name
must exist in `priority.windows`.

1. No candidates at all: the window closes at once, without a request.
2. `first_x` decides who gets priority first (evaluated once). Without it: the local `actor` (for
   a `window` op), else player 0. `protocol.first` as text without `first_x` is `NotExecutable`.
3. The player with priority gets a decision at `window <name>` between the legal candidates
   (`pre_x` true with `actor` = that player, `window` = the name, `stack` = the open stack) and
   `pass`. A player without a legal candidate passes automatically, without a request.
   Eliminated players are skipped.
4. Playing an action: its `cost` runs at once (place `action <name> (cost)`). Then:
   - `resolution: immediate` (default) or `nested`: the `effect` runs at once, followed by an end
     check. (`nested` is accepted and currently behaves exactly like `immediate`.)
   - `resolution: lifo_stack`: the action goes on the stack (`{action, actor, cancelled}`),
     event `stack:<name>`. The local names of the cost are kept for the effect.
   Then priority goes to the next player (`after_action: next`, default) or stays
   (`after_action: same`).
5. Closing (`closes`): `all_pass_in_succession` (default) closes when every non-eliminated player
   has passed in a row; any action resets the count. `single_pass_each`: a player who passes is out
   for the rest of the window; it closes when all are out.
6. With `lifo_stack`, when the window would close and the stack is not empty, the top item
   resolves instead: a cancelled item is removed with event `cancelled:<name>` and no effect and
   no end check; otherwise event `resolves:<name>`, its effect runs with the player who played it
   as `actor`, the names bound in its cost, and `stack` without the item, followed by an end
   check. Then the pass count is reset and the same first player gets priority again: the value
   `first_x` gave when the window opened, not a new evaluation. The window closes only when
   everyone passes with an empty stack.
7. `cancel` with `target_x` marks stack item `target` (an index into `stack`, bottom first, so
   `len(stack) - 1` is the top) as cancelled at the moment the op runs: in an `effect`, when that
   effect resolves, not when the action is played. Cancelling an item twice is allowed; `None`
   does nothing. Without an open window: `ExprError`. To fix the target when the action is
   played, bind its index in `cost` (cost ops see `stack`); see
   [reference § cancel](https://tabletwin.com/docs/reference/#cancel).

More than 10,000 turns of priority in one window is `ExprError: ... window does not close`.
`pass` is reserved: an action with a `speed` may not be called `pass`.

## End conditions

The engine checks `end` at these moments, and only these:

- after every step that ran an action;
- in a window, after every effect that resolves (with `immediate`, after every played action);
- after each event of an `end_event`.

Not after a cost, not after a cancelled stack item, not when a window closes, not at the start or
end of a loop round, not when a step is skipped.

The conditions are tested in list order; the first one that fires ends the game (or its subflow)
and the rest are not tested. `eliminate` and `continue` never stop the scan:

| Condition | Effect |
|---|---|
| no `if_x` | ignored |
| `scope: <flow>` while that subflow is not running | ignored |
| `scope: <flow>`, result `win`/`loss`/`draw`, `if_x` true | `results['<flow>']` is set to the result, event `<flow>:<result>`, and that subflow ends; the calling flow continues. Checking stops |
| `result: eliminate` | Every player in `who_x` (an index or a list) not yet eliminated is added to `eliminated` (event `eliminated:<p>`). Checking **continues** with the next condition |
| `result: continue` | ignored |
| other result, `if_x` false | next condition |
| `draw` | the game ends: 0 for everyone |
| `score` | the game ends with `returns_x` (one number per player, else `ExprError`) |
| `win` / `loss`, cooperative | the game ends: everyone +1 (win) or −1 (loss) |
| `win` / `loss`, competitive | needs `who_x` (one index): that player gets +1 (win) or −1 (loss), all others the opposite. A list, tuple or set is an `ExprError` (it would match no player) |

A `scope` equal to the `id` of the main flow means the whole game. `scope` only changes the meaning
of `win`, `loss` and `draw`; any other result with a scope is only tested while that subflow runs
and then acts as without scope. If the main flow runs out without an end condition, the game ends
with 0 for everyone and reason `flow finished without an end condition`.

## Engine events

Besides the names you emit, the engine adds these to the event list. The player shows them after
each question: emitted events with the triggers they set off, the others under "messages".

| Event | When |
|---|---|
| `<event>` | every `emit` and every `end_event` |
| `instead:<trigger id>` | an instead-trigger replaced an impact |
| `stack:<action>`, `resolves:<action>`, `cancelled:<action>` | priority window with `lifo_stack` |
| `<flow>:win`, `<flow>:loss`, `<flow>:draw` | an end condition with `scope` ended a subflow |
| `eliminated:<player>` | a player was eliminated |
| `<model>:<outcome id>` | a `sample` from an outcome model |
| `exec:<content id>` | an `exec` ran a content item |
| `destroy:<label>` | a `destroy` |
| `reset:<scope>` | a campaign `reset` (default scope label `scenario`) |

## Information: who sees what

The engine keeps a list of **observations**. Each one has a place, a kind, a visibility and a label.

| Event | Who sees the outcome |
|---|---|
| Decision | Everyone; with `secret` only the chooser; with `visible_to_x` the listed players |
| `roll` | Everyone, or `visible_to_x` |
| `sample` | Everyone |
| `draw` | By destination zone: `public` everyone, `owner` the owner, `hidden` nobody; or `visible_to_x` |
| `look` | The actor (`actor_x` or the local `actor`), or `visible_to_x`; with no actor, everyone |
| `search` | The searcher sees the whole zone; the choice is secret unless `visible_to_x` |
| `reveal` | Everyone, or `visible_to_x`. Zone visibility does not change |

What player `p` knows is everything they observed, in order, with a blank for what they could not
see. In the player, "view as" a player shows the table and the questions as that player saw them:
hidden zones and other players' hands show card backs, and a hidden outcome says who can see it.

A player that looks ahead (see [tactics](https://tabletwin.com/docs/tactics/#look-ahead-search)) must not peek. Before it
tries options, everything that player cannot know is redistributed:

- Drawing from a shuffled zone is already fair: the order is only fixed when a card is drawn.
- Hidden cards that are already on the table (shadow cards dealt face down) must be marked with
  `drawn_from: <source zone>` on their zone. The contents of every such zone that `p` cannot see
  are shuffled together with the unknown middle part of the source zone, and dealt back. Counts and
  identities (`uid`) stay; only which card each one is changes.

```yaml
shadow: {kind: set, visibility: hidden, drawn_from: encounter_deck}
```

A tactic (and a policy) reads the full state, hidden zones included. Not reading what the player
cannot know is up to the author.

## Executability

A model can be partly executable. The validator (and the diagram) measure it in two layers:

- **rules**: every slot the engine needs in flow, actions, triggers, modifiers, the priority
  protocol, outcome models and end conditions has an `_x` or a literal.
- **content**: every content item with behaviour or card text (`effect`, `triggers`, `modifiers`,
  `abilities`, `keywords`, `text`, or `status: missing`) counts as one slot, executable when it has
  behaviour, its own ops and triggers have no gaps, and its status is not `missing`. An item with
  only `text` is a gap. Keywords count as behaviour when every keyword occurs in quotes in some rule
  expression (`'Sentinel' in c.get('keywords', '')`). A `call` to code of kind `content` counts as
  a content gap.

`executable` is the share over both layers together.

The slots in the rules layer:

| Where | Slot is executable when |
|---|---|
| action with `pre` | `pre_x` exists |
| `choose` | `options`, `min`, `max` (those present) have `_x` or a non-text literal |
| `if` | `cond_x` exists |
| `for_each`, `repeat` | `items`, `until` likewise |
| `set`, `let` | `value` has `_x`, a non-text literal, or text that is a plain name (`open`, `face_up`) |
| `add` | `amount` likewise (no text) |
| `set`/`add` with `attr` | `of` likewise |
| `place`, `create`, `move`, `destroy`, `reveal` | `what`, and `at` (place) and `n` (create) when present |
| `draw`, `look` | `n` when present |
| `roll`, `cancel` | `die`, `target` |
| `modify`, modifier | `stat` and `change_x` |
| `call` | never (counted as `code:<kind>`) |
| `say` | never (counted as `language`) |
| trigger with `if` | `if_x` exists |
| `priority.protocol` (if any action has a `speed`) | `first_x` exists, or no `first` |
| outcome | `p_x` exists |
| branch case | `when_x` exists |
| loop with `until` / `over` | `until_x` / `over_x` exists |
| step with several actions, or a `choose` without `actor_x` | `actor_x` on the step (or one action whose `choose` ops all have `actor_x`) |
| end condition `score` | `if_x` and `returns_x` |
| other end condition | `if_x`, plus `who_x` for `eliminate` and for competitive `win`/`loss` without a subflow scope |

Below 100%, the validator lists the missing slots under "What the engine still misses", per kind
(`text`, `code:<kind>`, `language`, and `content:...` for gaps inside content items) with their
place.

### The validator

The [validator page](https://tabletwin.com/validate/) shows **errors** (must be fixed) and
**warnings** (check them: each is either a deliberate choice or a bug). Only a model without errors
gets test games.

| Errors | Warnings |
|---|---|
| `mode` not `competitive`/`cooperative`; `persist` not `campaign` | `drawn_from` source not shuffled; `drawn_from` on a public zone |
| duplicate flow `id`; unknown `kind` or loop `order`; branch without `cases`; subflow or `run` flow missing; window not in `priority.windows`; step action missing; loop `as` not declared in `state.vars` | action never used by a step (unless it has `speed` or `note`); named flow never called |
| unknown op; zone in `from`/`to`/`zone` not declared; `code`, outcome model or agent not declared; `exec` content catalogue missing | `say` without `agent`; `exec` without `content` or `of_x` |
| expression syntax error in any `_x`, derived value or function | board never named in an expression; function never called |
| invalid board; function name taken; function without `x`; bad `params` or `let` | trigger event never emitted (model and content); optional trigger without `controller_x` |
| trigger `timing` unknown; `resolution`/`closes` unknown; action with `speed` named `pass` | `speed` not allowed by any window; fast action always playable in an opened window (no `pre_x`, no `cost`, nothing in its effect an end condition reads) |
| `end` `scope` not a named flow; `end_event` not a name; competitive `win`/`loss` whose `who_x` is obviously a list (list/tuple/set literal, comprehension, `list()`, `sorted()`, `set()`, `tuple()`) | modifier or `modify` stat never read with `modified('stat', ...)` |
| content ability without `id` or with a name that is already an action; dice face type not in `face_types`; outcome model without outcomes or an outcome without `p` | content item `status` not `verified`/`uncertain`/`missing`; keyword not used by any rule; ability without `speed` |
| open question without `question` | open question `status` not `open`/`assumed`/`answered` |
| | key not allowed by the [JSON schema](https://tabletwin.com/models/docs/schema.json) (`unknown key 'x' at actions.y`; `content` is not checked) |

Before that, the page checks that the text is readable YAML ("The YAML cannot be read") and that it
is a model at all, a mapping with a `flow` ("This is not a model").

The validator does **not** check that the names in an expression exist; a wrong name shows up as a
`NameError` when the engine evaluates it. The test games find most of these (under "Where games
stopped"); follow games in the player to find the rest.

### What the validator shows

| Part | Meaning |
|---|---|
| Errors and warnings | As above |
| `executable` | Executability over rules and content together, with a bar |
| rules | Executability of the rules layer |
| content | Executability of the content layer: `pct (ok/total)`, or `-` without content |
| steps | Number of step nodes in the flow |
| ops | Number of ops in actions, triggers, outcome models and content |
| code | Share of `call` ops among all ops |
| open questions | Number of `open_questions` |
| What the engine still misses | The gap list, below 100% |
| Test games | 20 games with random choices and random chance: how many finished, the average number of requests, how they ended (per reason), where games stopped (engine errors), and how many did not end within 5000 requests |
| The flow as a tree | The flow as a text tree: nodes, who acts, actions and their `pre`, windows, end events |

The markers of each step (choice, chance, hidden, window, ...) are shown in the
[diagram](https://tabletwin.com/docs/diagram/#markers).

## Checking and running a model on the site

Everything runs in your browser; nothing is uploaded.

| Tool | What it does |
|---|---|
| [Validator](https://tabletwin.com/validate/) | Paste a model (and optionally a [view](https://tabletwin.com/docs/views/)). Errors, warnings including unknown keys, executability, the gaps, the flow as a tree, and 20 random test games. "Start from" loads one of the site's examples |
| [Player](https://tabletwin.com/play/) | After at least one test game finished, "Open in the player" adds your model to the player as an extra game ("Your model: ..."). The player plays one game question by question: the track of the rules, what was asked, what was chosen, what changed, and the table |
| [Diagram](https://tabletwin.com/diagram/) | "Draw your own model": the rules as a text tree and as a track diagram, with markers per step. See [diagram](https://tabletwin.com/docs/diagram/) |

In the player:

- **Players** chooses who plays: one seat by hand ("You play player 0") with the others played by
  the computer, everyone by hand on one screen, random players, a heuristic from the model's
  `agents` (`policy_x`), or always the first option. The built-in games also offer their tactics
  ([tactics](https://tabletwin.com/docs/tactics/)); tactics for your own model cannot be loaded on the site yet.
- **Game (seed)** fixes the random numbers: the same seed and the same players give the same game.
  "Random game" picks another seed.
- **View as** shows the game as one player saw it.
- The table has two tabs: **Board** (laid out by the view, or automatically without one) and
  **Zones and values**.
- At the end: "End: <reason>" and the payoff per player. An engine error stops the game and shows
  the message.

Playing thousands of games to measure win rates, comparing rule variants or tactics, and changing
constants per run are not yet available on the site.

## Error messages

The engine stops with one of two kinds of error. **NotExecutable**: the model lacks something the
engine needs (the site shows it as "Not executable: ..."). **ExprError**: something went wrong
while running, such as an expression that fails or a loop that never ends (the site shows it as
"Error: ..."). The validator lists them under "Where games stopped" with the number of test games
that stopped there; the player shows the message where the game stopped.

| Message | Meaning | Fix |
|---|---|---|
| `NotExecutable: action X: pre is text without pre_x` | The engine needs an expression | Add `pre_x` |
| `NotExecutable: <place>: field 'amount' is text without amount_x` | A text field where the engine needs a value | Add the `_x` field, or a literal |
| `NotExecutable: step X: choice between actions without actor_x` | Several legal actions, nobody to choose | `actor_x` on the step |
| `NotExecutable: <place>: choose without actor_x and without an actor on the step` | A `choose` with 2+ options and no chooser | `actor_x` on the op or the step |
| `NotExecutable: end condition X: a competitive game needs who_x` | A win without a winner | `who_x` on the condition |
| `ExprError: end condition X: who_x gives a list ([0, 1]); a competitive win needs one player index ...` | `who_x` gave several players; with a list no player would match | One index; several winners: `result: score` with `returns_x` |
| `ExprError: <place>: window does not close` | Players kept playing fast actions (10,000 priority turns in one window) | A `pre_x` or `cost` that limits the action (the validator warns: `always playable in window`) |
| `NotExecutable: trigger X: optional without controller_x or actor` | Nobody to ask `use`/`skip` | `controller_x` on the trigger |
| `NotExecutable: code 'x' → m:f is not implemented` | A `call` to code outside the model | Model it with ops; a model cannot bring its own code |
| `ExprError: error evaluating '...': NameError: name 'x' is not defined` | Name unknown at that place | See the scope table in [expressions](https://tabletwin.com/docs/expressions/); local names do not exist in flow and `end` |
| `ExprError: zone 'x' not declared` / `zone 'x' belongs to a player; write x[player]` | Bad zone path | Declare the zone, or index it |
| `ExprError: variable 'x' not declared` | `set`/`add` on an undeclared variable | Declare it under `state.vars` |
| `ExprError: <place>: move: 'x' is not in <zone>` | The item is not in `from` | Follow the game in the player and look at the zone and the value |
| `ExprError: flow X: loop does not end` | `until_x` never becomes true (10,000 rounds) | Set a flag in an effect |
| `ExprError: end condition X: returns_x gives 1 values, expected 2` | `returns_x` length differs from `num_players` | One number per player |
| `ExprError: outcome model X: probabilities add up to 0.900000, not 1` | `p_x` values do not sum to 1 | Fix the probabilities |
| End reason `flow finished without an end condition` (in the test games and the player) | The main flow ran out | Check `end` and when it is checked |
| `N games did not end within 5000 requests: a loop without an end?` (validator), "cut off" (player) | A loop that never ends | Check the loop conditions and end conditions |

## Limits

| Limit | Value |
|---|---|
| Rounds of one loop, iterations of `repeat`, turns of priority in one window | 10,000 |
| Nested emits (trigger chains) | 50 |
| Nested calls of own functions | 100 |
| Nested `modified()` calls | 20 |
| Requests in one test game of the validator | 5,000 |


<!-- https://tabletwin.com/docs/diagram.md -->

# The diagram

The [diagram page](https://tabletwin.com/diagram/) of the site draws every model in two views,
directly from the YAML: a **tree** (text) and a **track diagram** (visual). Nothing is drawn by
hand: what you put in the model appears, and what you leave out does not.

## What appears where

| In the model | In the diagram |
|---|---|
| `label`, `summary`, `demonstrates`, `players` | Title, summary, and the subtitle in the game list (`demonstrates`, else `players`). The site's built-in games may show a title of their own, in the language of the page |
| Flow nodes | The tree and the track diagram. A node is named by its `label`, else its `id` |
| `loop` with `over`/`over_x` and `order` | A loop back, with an icon for the turn order |
| `branch` with `cases` | A split into parallel tracks, with `when` and `label` per case |
| `step` | A card with `actor`, the actions in `do`, its window and its markers. Expanding it shows each action's `pre` and the effects as pseudo-code, with the `_x` expressions under them |
| `end_event` | "end: …" on a step, "event after: …" on a group |
| `note` | An explanation under the node |
| `end` | The End panel: `if`, `check`, `scope` and the expression |
| Zones, variables, constants, derived values | The State, Constants and Derived panels; `persist` shows as Persistent |
| `triggers`, `modifiers`, `priority` | Their own panels; windows with their fast actions (`label`, `allows`, `note`) and the protocol |
| `outcomes` | Outcome models, marked Skill or Chance |
| `content`, `open_questions` | Content (with dice faces from `faces` and `face_types`) and the gap report. Per item: the text, keywords, and under "effect" the item's abilities, triggers and modifiers; abilities also appear with the windows in which they can be played |
| Executability | `rules`, content, code share and the total, as the validator computes them |

## Markers

The diagram derives per step what happens in it; you do not set markers yourself.

| Marker | When |
|---|---|
| Choice | `do` is a list, or the step's actions contain `choose`, `say` or `search` |
| Chance | `roll`, `shuffle`, `draw` from a shuffled zone, `look` at a shuffled zone, or `sample` from an outcome model without `skill` |
| Skill | `sample` from an outcome model with `skill: true` |
| Hidden | `choose` with `secret`, `search`, `look`, or `move`/`draw` into a zone that is `hidden` or `owner` and not shuffled |
| Window | `window` on the step, or a `window` op |
| Trigger | `emit` of an event that some trigger (in the model or on content) listens to |
| Language | `say`, or `choose` with an agent of `kind: llm` |
| Persistent | `set`/`add` on a variable with `persist`, `move`/`draw`/`place`/`create` into a zone with `persist`, or `reset` |
| Code | `call` |

The ops of a flow run with `run` count for the step that runs it. Ops of triggers do not count for
the step that emits. Choices in a priority window count as Window, not as Choice. Markers belong to
steps: a `window` on a `sequence` or `loop` shows on that node, but is not a step marker.

## Viewing your own model

- On the [diagram page](https://tabletwin.com/diagram/), open "Draw your own model", paste the
  YAML and press "Draw model". "Fill with current game" puts the YAML of the game on screen in the
  box, as a start. The model needs at least a `flow` with a `kind`; references to missing actions
  or zones show up empty.
- The [validator page](https://tabletwin.com/validate/) checks a pasted model, shows the flow as a
  text tree ("The flow as a tree") and opens the model in the player.
- Commercial games on the site are shown as their rules structure only, without content or model
  source.

## A readable diagram

- Give nodes a short `label` in the words of the rulebook ("Planning phase", not `phase2`).
- Follow the rulebook's headings: a phase in the rulebook is a node in the flow.
- Write `pre`, `cond`, `if` and `when` as short sentences; the expression is shown under them.
- Put exceptions and doubts in `note` or `open_questions`, not in labels.


## Example: games/tictactoe.yaml

```yaml
game: tictactoe
label: Tic-tac-toe
players: "2 players"
mode: competitive
num_players: 2
demonstrates: "basics · lower bound · executable"
summary: >
  Perfect information, no chance, one decision per turn. The lower bound of the metamodel,
  and the first fully executable model: every rule has an `_x` expression.

constants:
  SYMBOL: ["X", "O"]
  LINES: [[0, 1, 2], [3, 4, 5], [6, 7, 8], [0, 3, 6], [1, 4, 7], [2, 5, 8], [0, 4, 8], [2, 4, 6]]

state:
  entity_types:
    mark: {attrs: {symbol: "enum[X, O]"}}
  zones:
    board: {kind: grid, size: [3, 3], owner: global, visibility: public, holds: mark, init_x: "[None] * 9"}
  vars:
    current: {scope: global, type: ref, init: 0, note: "0 = X, 1 = O"}

flow:
  id: game
  label: Game
  kind: loop
  over: players
  over_x: players
  as: current
  order: fixed
  note: "ends through the end conditions"
  children:
    - id: place
      label: Place your mark on an empty square
      kind: step
      actor: current
      actor_x: current
      do: place_mark

actions:
  place_mark:
    actor: current
    pre: "at least one empty square"
    pre_x: "None in board"
    effect:
      - op: choose
        actor: current
        options: "empty squares"
        options_x: "[i for i in range(9) if board[i] is None]"
        bind: cell
      - {op: place, what: "mark of current", what_x: "SYMBOL[current]", to: board, at_x: cell}
      - {op: emit, event: mark_placed}

triggers:
  - {id: check_line, source: rule, event: mark_placed, timing: after, do: [{op: emit, event: end_check}]}

end:
  - id: three_in_row
    check: immediate
    if: "three in a row for current"
    if_x: "any(all(board[i] == SYMBOL[current] for i in L) for L in LINES)"
    who_x: current
    result: win
  - id: full
    check: immediate
    if: "board full without a line"
    if_x: "None not in board"
    result: draw
```


## Example: docs/examples/hex-skirmish.yaml

```yaml
# Patterns: hex map with walls, obstacles and difficult terrain; initiative each round; choosing
# cards, resting and losing cards; monsters with a fixed way of thinking (focus, move to an attack
# cell, attack); range and line of sight; area attack with a rotated pattern; attack modifier
# decks that are reshuffled after x2 or a miss.
game: hex-skirmish
label: Hex Skirmish
players: "2 players, together"
num_players: 2
mode: cooperative
summary: >
  Two heroes (warrior and seer) against three monsters in a corridor with a wall and a gap.
  Each round every hero secretly picks a card (initiative, movement, attack or healing);
  the monsters draw one behaviour card per type. Lowest initiative goes first. Monsters pick
  their own target and walk to a cell from which they can attack. Win when all monsters are
  defeated; lose when both heroes fall or after eight rounds.
scope: >
  Our own small setup in the spirit of tactical dungeon games; no existing cards. A hero plays one
  card per round (no top and bottom halves). On equal distance a monster picks the hero with the
  lowest player number, not the one with the lowest initiative.

boards:
  map:
    kind: hex
    width: 7
    height: 5
    label: corridor with a wall
    missing: ["3,0", "3,1", "2,3", "1,4"]

constants:
  MAX_ROUNDS: 8
  HEROES: [warrior, seer]
  OBSTACLES: ["5,2"]
  TERRAIN: {"2,2": 2, "1,2": 2}
  AROUND: [e, se, sw, w, nw, ne]
  MONSTERS:
    guard: {move: 2, attack: 3, range: 1}
    archer: {move: 2, attack: 2, range: 3}
  MODIFIERS: [0, 0, 0, 0, 1, 1, -1, -1, 2, -2, x2, miss]
  SETUP:
    - {id: warrior, label: Warrior, side: hero, player: 0, hp: 10, max: 10, shield: 1, cell: "0,1"}
    - {id: seer, label: Seer, side: hero, player: 1, hp: 7, max: 7, shield: 0, cell: "-1,3"}
    - {id: guard1, label: Guard 1, side: monster, type: guard, hp: 6, max: 6, shield: 1, cell: "5,1"}
    - {id: guard2, label: Guard 2, side: monster, type: guard, hp: 6, max: 6, shield: 1, cell: "4,3"}
    - {id: archer1, label: Archer, side: monster, type: archer, hp: 4, max: 4, shield: 0, cell: "6,0"}

content:
  hero_cards:
    warrior:
      - {id: charge, label: Charge, status: verified, ini: 15, move: 4, attack: 2, range: 1, note: "Move 4, attack an adjacent enemy for 2."}
      - {id: heavy_blow, label: Heavy Blow, status: verified, ini: 40, move: 2, attack: 4, range: 1, note: "Move 2, attack an adjacent enemy for 4."}
      - {id: whirlwind, label: Whirlwind, status: verified, ini: 28, move: 1, attack: 2, range: 1, around: true, pattern: [e, se, sw, w, nw, ne], note: "Move 1, attack every adjacent enemy for 2."}
      - {id: cautious, label: Cautious, status: verified, ini: 60, move: 3, attack: 3, range: 1, note: "Move 3, attack an adjacent enemy for 3."}
    seer:
      - {id: spark, label: Spark, status: verified, ini: 20, move: 2, attack: 2, range: 3, note: "Move 2, attack at range 3 for 2."}
      - {id: fireball, label: Fireball, status: verified, ini: 55, move: 1, attack: 2, range: 3, pattern: [[0, 0], e, se], note: "Move 1, hit a triangle of three cells within range 3 for 2; it may be rotated."}
      - {id: restore, label: Restore, status: verified, ini: 35, move: 2, heal: 3, range: 2, note: "Move 2, heal 3 on yourself or a hero within range 2."}
      - {id: slip_away, label: Slip Away, status: verified, ini: 12, move: 4, attack: 1, range: 2, note: "Move 4, attack at range 2 for 1."}
  monster_cards:
    guard:
      - {id: gd_step, label: Step and Strike, status: verified, ini: 45, move: 0, attack: 0}
      - {id: gd_quick, label: Quick Lunge, status: verified, ini: 30, move: 1, attack: -1}
      - {id: gd_heavy, label: Crushing Blow, status: verified, ini: 70, move: -1, attack: 1}
    archer:
      - {id: ar_shot, label: Shot, status: verified, ini: 20, move: 0, attack: 0}
      - {id: ar_walk, label: Running Fire, status: verified, ini: 50, move: 1, attack: -1}
      - {id: ar_aim, label: Take Aim, status: verified, ini: 65, move: -1, attack: 1}

functions:
  heroes:
    x: "[f for f in figures if f['side'] == 'hero']"
  monsters:
    x: "[f for f in figures if f['side'] == 'monster']"
  hero:
    text: "the figure of player p (None if it has fallen)"
    params: [p]
    x: "([f for f in figures if f.get('player') == p] + [None])[0]"
  fig:
    params: [i]
    x: "([f for f in figures if f['id'] == i] + [None])[0]"
  blocked:
    text: "cells a figure of this side cannot pass through: obstacles and enemies"
    params: [side]
    x: "OBSTACLES + [f['cell'] for f in figures if f['side'] != side]"
  passable:
    text: "cells of allies: you may pass through, but not end there"
    params: [side, own_id]
    x: "[f['cell'] for f in figures if f['side'] == side and f['id'] != own_id]"
  free:
    params: [c, own_id]
    x: "c not in OBSTACLES and not any(f['cell'] == c and f['id'] != own_id for f in figures)"
  in_range:
    text: "within range (counted around walls) and in sight (corner to corner)"
    params: [a, b, reach]
    let:
      cost: "path_cost('map', a, b) if distance('map', a, b) <= reach else None"
    x: "cost is not None and cost <= reach and line_of_sight('map', a, b, True)"
  attack_cells:
    text: "empty cells from which monster m can attack hero h"
    params: [m, h, reach]
    x: "[c for c in cells('map') if distance('map', c, h['cell']) <= reach and free(c, m['id']) and in_range(c, h['cell'], reach)]"
  route:
    text: "movement points for monster m from cell a to cell b (None: unreachable)"
    params: [m, a, b]
    x: "path_cost('map', a, b, blocked('monster'), TERRAIN, passable('monster', m['id']))"
  focus:
    text: "the hero the monster can attack with the least movement; on a tie: lowest player number"
    params: [m, reach]
    let:
      scores: >-
        [(min([k for k in [route(m, m['cell'], c) for c in attack_cells(m, h, reach)] if k is not None] + [999]), n, h['id'])
         for n, h in enumerate(heroes())]
    x: "min(scores)[2] if scores and min(scores)[0] < 999 else None"
  destination:
    text: "the cheapest reachable cell from which the monster can attack; otherwise as close as possible"
    params: [m, h, movement, reach]
    let:
      candidates: "[m['cell']] + reachable('map', m['cell'], movement, blocked('monster'), TERRAIN, passable('monster', m['id']))"
      targets: "attack_cells(m, h, reach)"
      direct: "[c for c in candidates if c in targets]"
    x: >-
      (direct[0] if direct else
       min([(min([k for k in [route(m, c, d) for d in targets] if k is not None] + [999]), n, c)
            for n, c in enumerate(candidates)])[2])
  attack_options:
    text: "whom a hero with card c can hit: one target, everything around, or a rotated pattern on a cell in sight"
    params: [me, c]
    let:
      pat: "c['origin'].get('pattern')"
      sets: >-
        ([[m] for m in monsters() if in_range(me['cell'], m['cell'], c['range'])] if not pat
         else [[m for m in monsters() if m['cell'] in shape('map', me['cell'], pat)]] if c.get('around')
         else [[m for m in monsters() if m['cell'] in shape('map', t, pat, d)]
               for t in cells('map') if in_range(me['cell'], t, c['range']) for d in range(6)])
    x: "list({str([m['id'] for m in s]): s for s in sets if s}.values())"
  damage:
    params: [base, mod, shield]
    x: "0 if mod == 'miss' else max(0, (base * 2 if mod == 'x2' else base + mod) - shield)"

state:
  zones:
    figures: {kind: hexgrid, owner: global, visibility: public, init_x: SETUP, note: "figures on the map; cell = where they stand"}
    defeated: {kind: set, owner: global, visibility: public}
    hand: {kind: set, owner: player, visibility: owner, init_x: "[content['hero_cards'][h] for h in HEROES]"}
    discard: {kind: stack, owner: player, visibility: public}
    lost: {kind: set, owner: player, visibility: public}
    hero_mod_deck: {kind: stack, owner: global, visibility: hidden, shuffled: true, init_x: MODIFIERS, note: "attack modifiers of the heroes"}
    hero_mod_discard: {kind: stack, owner: global, visibility: public}
    monster_mod_deck: {kind: stack, owner: global, visibility: hidden, shuffled: true, init_x: MODIFIERS, note: "attack modifiers of the monsters"}
    monster_mod_discard: {kind: stack, owner: global, visibility: public}
  vars:
    round_no: {scope: global, type: int, init: 1}
    p: {scope: global, type: ref, init: 0, note: "player choosing a card"}
    who: {scope: global, type: str, init: null, note: "figure whose turn it is"}
    order: {scope: global, type: list, init: []}
    card: {scope: player, type: dict, init: null, note: "card chosen this round"}
    monster_card: {scope: global, type: dict, init: {}, note: "behaviour card per monster type this round"}
    reshuffle_hero: {scope: global, type: bool, init: false}
    reshuffle_monster: {scope: global, type: bool, init: false}

flow:
  id: battle
  label: Battle
  kind: loop
  note: "stops through the end conditions"
  children:
    - id: choose_cards
      label: Heroes choose a card
      kind: loop
      over_x: "[f['player'] for f in heroes()]"
      as: p
      once: true
      children:
        - {id: choose, label: Choose a card (or rest), kind: step, actor_x: p, do: choose_card}
    - {id: monster_cards, label: Monsters draw a behaviour card, kind: step, do: draw_monster_cards}
    - {id: order, label: Order by initiative, kind: step, do: set_order}
    - id: turns
      label: Turns
      kind: loop
      over_x: order
      as: who
      once: true
      children:
        - id: turn
          kind: branch
          switch: "hero or monster (and still on the map)"
          cases:
            - when: hero
              when_x: "fig(who) is not None and fig(who)['side'] == 'hero'"
              children: [{id: hero_turn, label: Hero acts, kind: step, actor_x: "fig(who)['player']", do: hero_acts}]
            - when: monster
              when_x: "fig(who) is not None and fig(who)['side'] == 'monster'"
              children: [{id: monster_turn, label: Monster acts, kind: step, do: monster_acts}]
    - {id: end_round, label: End of round, kind: step, do: finish_round}

actions:
  choose_card:
    effect:
      - op: if
        cond: "no cards in hand: rest"
        cond_x: "len(hand[actor]) == 0"
        then:
          - op: if
            cond: "fewer than two discarded cards: exhausted"
            cond_x: "len(discard[actor]) < 2"
            then:
              - {op: move, what_x: "hero(actor)", from: figures, to: defeated}
              - {op: emit, event: exhausted}
            else:
              - {op: move, what_x: "list(discard[actor])", from: "discard[actor]", to: "hand[actor]"}
              - {op: roll, die_x: "hand[actor]", bind: gone}
              - {op: move, what_x: gone, from: "hand[actor]", to: "lost[actor]"}
              - {op: emit, event: rested}
      - op: if
        cond_x: "len(hand[actor]) > 0 and hero(actor) is not None"
        then:
          - {op: choose, options: "cards in hand", options_x: "hand[actor]", bind: c, secret: true}
          - {op: move, what_x: c, from: "hand[actor]", to: "discard[actor]"}
          - {op: set, var: "card[actor]", value_x: c}
        else:
          - {op: set, var: "card[actor]", value: null}

  draw_monster_cards:
    effect:
      - op: for_each
        items_x: "sorted(set(m['type'] for m in monsters()))"
        as: t
        body:
          - {op: roll, die_x: "content['monster_cards'][t]", bind: mc}
          - {op: set, var: "monster_card[t]", value_x: mc}

  set_order:
    effect:
      - op: set
        var: order
        value: "by initiative; on a tie heroes first"
        value_x: >-
          [t[3] for t in sorted(
             [(card[f['player']]['ini'], 0, n, f['id']) for n, f in enumerate(figures)
              if f['side'] == 'hero' and card[f['player']] is not None]
           + [(monster_card[f['type']]['ini'], 1, n, f['id']) for n, f in enumerate(figures) if f['side'] == 'monster'])]

  hero_acts:
    effect:
      - {op: let, bind: me, value_x: "hero(actor)"}
      - {op: let, bind: c, value_x: "card[actor]"}
      - op: choose
        options: "where to (staying is allowed)"
        options_x: "[me['cell']] + reachable('map', me['cell'], c['move'], blocked('hero'), TERRAIN, passable('hero', me['id']))"
        bind: dest
      - {op: set, of_x: me, attr: cell, value_x: dest}
      - op: if
        cond: "healing card"
        cond_x: "c.get('heal')"
        then:
          - {op: choose, options: "hero in range", options_x: "[h for h in heroes() if in_range(me['cell'], h['cell'], c['range'])]", bind: target}
          - {op: set, of_x: target, attr: hp, value_x: "min(target['max'], target['hp'] + c['heal'])"}
          - {op: emit, event: healed}
        else:
          - {op: let, bind: choices, value_x: "attack_options(me, c)"}
          - op: if
            cond_x: "len(choices) > 0"
            then:
              - {op: choose, options: "whom you hit", options_x: choices, bind: hit}
              - op: for_each
                items_x: hit
                as: target
                body:
                  - op: if
                    cond_x: "len(hero_mod_deck) == 0"
                    then: [{op: move, what_x: "list(hero_mod_discard)", from: hero_mod_discard, to: hero_mod_deck}, {op: shuffle, zone: hero_mod_deck}]
                  - {op: draw, from: hero_mod_deck, to: hero_mod_discard}
                  - {op: if, cond_x: "hero_mod_discard[-1] in ('x2', 'miss')", then: [{op: set, var: reshuffle_hero, value: true}]}
                  - {op: set, of_x: target, attr: hp, value_x: "max(0, target['hp'] - damage(c['attack'], hero_mod_discard[-1], target['shield']))"}
                  - {op: emit, event: monster_hit}
                  - op: if
                    cond_x: "target['hp'] <= 0"
                    then: [{op: move, what_x: target, from: figures, to: defeated}, {op: emit, event: monster_defeated}]

  monster_acts:
    effect:
      - {op: let, bind: m, value_x: "fig(who)"}
      - {op: let, bind: mc, value_x: "monster_card[m['type']]"}
      - {op: let, bind: movement, value_x: "max(0, MONSTERS[m['type']]['move'] + mc['move'])"}
      - {op: let, bind: attack, value_x: "max(0, MONSTERS[m['type']]['attack'] + mc['attack'])"}
      - {op: let, bind: reach, value_x: "MONSTERS[m['type']]['range']"}
      - {op: let, bind: h, value_x: "focus(m, reach)"}
      - op: if
        cond: "there is a hero to focus on"
        cond_x: "h is not None"
        then:
          - {op: set, of_x: m, attr: cell, value_x: "destination(m, fig(h), movement, reach)"}
          - op: if
            cond_x: "in_range(m['cell'], fig(h)['cell'], reach)"
            then:
              - {op: let, bind: target, value_x: "fig(h)"}
              - op: if
                cond_x: "len(monster_mod_deck) == 0"
                then: [{op: move, what_x: "list(monster_mod_discard)", from: monster_mod_discard, to: monster_mod_deck}, {op: shuffle, zone: monster_mod_deck}]
              - {op: draw, from: monster_mod_deck, to: monster_mod_discard}
              - {op: if, cond_x: "monster_mod_discard[-1] in ('x2', 'miss')", then: [{op: set, var: reshuffle_monster, value: true}]}
              - {op: set, of_x: target, attr: hp, value_x: "max(0, target['hp'] - damage(attack, monster_mod_discard[-1], target['shield']))"}
              - {op: emit, event: hero_hit}
              - op: if
                cond_x: "target['hp'] <= 0"
                then: [{op: move, what_x: target, from: figures, to: defeated}, {op: emit, event: hero_fallen}]

  finish_round:
    effect:
      - op: if
        cond_x: reshuffle_hero
        then: [{op: move, what_x: "list(hero_mod_discard)", from: hero_mod_discard, to: hero_mod_deck}, {op: shuffle, zone: hero_mod_deck}, {op: set, var: reshuffle_hero, value: false}]
      - op: if
        cond_x: reshuffle_monster
        then: [{op: move, what_x: "list(monster_mod_discard)", from: monster_mod_discard, to: monster_mod_deck}, {op: shuffle, zone: monster_mod_deck}, {op: set, var: reshuffle_monster, value: false}]
      - {op: add, var: round_no, amount: 1}

end:
  - {id: won, check: immediate, if: "all monsters defeated", if_x: "not monsters()", result: win}
  - {id: fallen, check: immediate, if: "both heroes fallen or exhausted", if_x: "not heroes()", result: loss}
  - {id: time_up, check: end_of_round, if: "after the last round", if_x: "round_no > MAX_ROUNDS", result: loss}
```