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 | 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 | 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 | 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 | From rulebook to model: a complete tutorial, the workflow, decision rules, patterns, pitfalls and checks. Start here. |
| Quick reference | 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 | The workflow and prompt for letting an AI agent write a model from a rulebook |
| Reference | Every key of a model file: state, actions, ops, flow, windows, triggers, content, end conditions |
| Expressions | The expression language of the _x fields: syntax, built-in functions, names in scope |
| Board geometry | Square and hex boards, the geometry functions and own functions |
| Tactics | Players as a separate layer: rules per decision place, look-ahead |
| Views | How the table looks in the player: view files |
| How the engine runs a model | Requests, chance, who sees what, windows, end conditions, executability, the validator's messages, limits |
| Diagram | How the diagram is drawn from a model, and the step markers |
| schema.json, 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-language-server: $schema=https://tabletwin.com/models/docs/schema.jsonand # 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 | Turn loop, repeat until something happens, push your luck, a die, a winner. The rulebook as comments |
| pig-tactic.yaml | A tactic: rules per decision place (for pig.yaml) |
| higher-lower.yaml | Shuffled deck, a hand per player, hidden information, secret choice, reveal, score |
| ambush.yaml | Priority window, fast actions with costs, the stack, cancelling |
| neighbours.yaml | A grid of cells, choosing a free cell, patterns as a table, whoever just moved wins |
| auction.yaml | A round that stops halfway, an own turn variable, returns larger than 1 |
| expedition.yaml | Campaign: scenarios, lasting state, reset, end conditions with a scope |
| 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 | Cards as instances with their own state, looking at a deck, putting cards on the bottom, shuffling, searching |
| triggers.yaml | Trigger timing, optional triggers, triggers on content |
| modifiers.yaml | Modifiers in layers, temporary modifiers, modifiers on content |
| spell-duel.yaml | Priority windows with lifo_stack, costs paid on play, counterspells |
| subset.yaml | Choosing a subset |
| coop-clock.yaml | A cooperative game |
| campaign.yaml | A small campaign |
Games:
| File | Shows |
|---|---|
| tictactoe.yaml | The smallest complete game on a grid |
| kuhn-poker.yaml | Hidden cards and betting |
| chess.yaml | A square board, move generation in own functions (ray, leap, neighbours), castling, en passant, promotion, mate, stalemate and draw rules |
| 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
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 and hex-skirmish-basic.yaml. Published views: chess.yaml, hex-skirmish.yaml and tictactoe.yaml. The commented metamodel lists every layer of a model in one file. All games and examples are listed on the games page.