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