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