# The workshop

The [workshop](https://tabletwin.com/workshop/) is one page for building a game: the model, its view
and a tactic in an editor on the left; on the right, updated as you type, the checks, the rules as a
track, the table, the game to play and a simulator for many games. Your games and their images are
kept in your own browser. Nothing is uploaded.

New here? [The tutorial](https://tabletwin.com/docs/tutorial-build/) builds a game with the workshop in half an hour.

## A game in the workshop

A game in the workshop has four parts, with the tabs on the left:

| Tab | What | Docs |
|---|---|---|
| Model | The rules: one YAML model | [Reference](https://tabletwin.com/docs/reference/), [quick reference](https://tabletwin.com/docs/cheatsheet/) |
| View | Optional: how the table looks, including your own images | [Views](https://tabletwin.com/docs/views/) |
| Tactic | Optional: how a computer player plays this game | [Tactics](https://tabletwin.com/docs/tactics/) |
| Flow | The model's flow as a tree: tap a node to change its kind, id, label, what a step does and who acts, how a loop runs or the cases of a branch; add, move and remove nodes | [Reference: flow](https://tabletwin.com/docs/reference/#9-flow-and-flows) |
| Cards | The model's content (cards, tiles, heroes…) as tables: a row per item, a column per field | [Reference: content](https://tabletwin.com/docs/reference/) |
| Images | Your own images (and 3D models, fonts and music) for cards, card frames, backs, boards, cells, pieces and the game's music | [Views: images](https://tabletwin.com/docs/views/#images), [card frames](https://tabletwin.com/docs/views/#card-frames), [music](https://tabletwin.com/docs/views/#music) |
| Layout | The view's table as chips: drag zones, meters and boards into rows; the Table pane shows the result | [Views: table and player](https://tabletwin.com/docs/views/#table-and-player) |

Flow, Cards and Layout are other ways of editing the same text: a node changed in the Flow tab or
a cell typed in the Cards tab lands in the Model tab, a chip moved in the Layout tab in the View
tab (comments and the rest of the file stay).
Nested parts (effects, triggers, card colours) are edited in the text.

The first visit asks where to start: *Fifteen*, a small card game ready to be changed into your own
(a deck, hands, a turn loop and three ways to end), an empty model, or a copy of one of our games.
**New** shows the same choice later. Our games are ordered from first steps to showcase, each with
a line on what it teaches; "Edit a copy" on the [games page](https://tabletwin.com/games/) does the
same for one game. The copy is yours; the original stays as it is.

**Tour** walks through a game step by step: each step opens the right tab, marks the lines it is
about and says why they are written that way. *Fifteen*, *Seedbed*, *Yahtzee* and the showcase
*Ashmoor Delve* (a campaign with monster behaviour, hexes, line of sight and designed card faces)
have a tour; the button shows when the open game has one.

The editor checks YAML as you type, shows errors and warnings next to the line they are about, and
has search (Ctrl+F), undo per tab and folding. Ctrl+Enter checks at once; the work is saved in the
browser a moment after each change.

## Rules in words

A key ending in `_x` holds a rule the engine runs: `if_x: "total[current] == TARGET"`. Put the
cursor in one (or in a function's `x` and `let`, or a derived value) and a panel under the text:

- **reads it out** in your model's own names: *the total of current is TARGET (15)*. Variables,
  zones, constants and functions show as chips; hover one for its `note`.
- **shows what it is worth** at the moment the **Table** pane shows, and what each of its parts is
  worth: *✗ False · total[current] 0 · TARGET 15*. ‹ › steps through that game, so you can watch
  a condition come true. A part that needs a name only known while the rule runs (`me`, a
  function's parameters) says so.
- **builds conditions** (`if_x`, `pre_x`, `cond_x`, `when_x`, `until_x`, `active_x`, `filter_x`):
  **Build** turns the condition into rows, *something · how it compares · something else*, joined
  by *and* or *or*. The ＋ menu of a side puts in a variable (of the acting player, where there is
  one), how many things a zone holds, a constant, a function or a value; the text follows as you
  go. A side that is not an expression yet stays red and the text keeps its last good version.

While typing inside a rule, Ctrl+Space (or just typing) offers your model's names with what they
are: variables, zones, constants, functions, the engine's names, the built-in functions, fields
after `['` and methods after `.`.

The same reading appears wherever the site shows a rule without words of its own: in the player's
**Rule** details and on the **Rules** track. [Expressions](https://tabletwin.com/docs/expressions/) describes the language.

## The panes on the right

| Pane | Shows |
|---|---|
| Check | The same checks as the [validator](https://tabletwin.com/validate/): errors and warnings, how executable the model is and what is missing, 20 random test games and how they ended, the flow as a tree. Also whether the view fits the model (zones, variables and boards it names, images it needs) and whether the tactic fits (expressions, decision places it covers). Click a message to jump to its line |
| Rules | The flow of the model as a track: every step, loop and branch, as in the player |
| Table | One random game on the table, drawn with your view and images. Step through it with the slider, look at it as one player (hidden hands then show their backs), switch between 2D and 3D, and click a card or piece for its details. Changes to the view show at once |
| Play | The [player](https://tabletwin.com/play/) with this game: play a seat yourself, play everyone at one screen, or watch computer players, including your own tactic. "Restart with my latest changes" picks up your edits |
| Simulate | Many games at once (100 to 10,000) with the players you choose per seat: random, always the first option, your tactic, or a `policy_x` heuristic from the model's `agents`. Shows wins per player (or team wins) with 95% intervals, mean returns for score games, how games ended, and games that stopped with an error or did not end. **Compare** plays a second setup on the same games (the same seeds), so the difference between the setups is the effect of the players, not of luck. Histograms show the game length and (for score games) the score of player 1. **Experiment** varies one numeric constant of the model over a range and plays setup A for every value: a chart of the win rates and the game length against the value, the place to balance a rule (a `GATHER` of 1 in Seedbed makes 80% of the games a draw; 2 or 3 balance it) |

The status line above the editor sums it up (errors, executability, test games, view, tactic);
click it to go to the details.

## Sharing a game

Nothing about your games goes through Tabletwin's servers. You share them yourself, in one of two
ways:

**A link.** "Share link" puts the model, view and tactic, compressed, into the address after the
`#`. Browsers do not send that part to the server: the game is in the link itself. Whoever opens
the link gets their own copy in their own workshop, which they can change without affecting yours.
Images are *not* in the link, only their names; the workshop then lists them as missing. (Images
referenced by a web address, `https://…`, do come along, because they are loaded from that address.)
Very large models make long links that some apps cut off; send a package instead.

**A package.** "Download package" saves one `.zip` file with everything: the texts and the images.
Send it, put it in your own storage, or keep it as a backup. "Import" (or dropping the file on the
page) opens it as a new game with its images. A package is a plain zip:

| File | Content |
|---|---|
| `tabletwin.json` | `{format: tabletwin-package, version: 1, name}` |
| `model.yaml` | The model |
| `view.yaml` | The view, if any |
| `tactic.yaml` | The tactic, if any |
| `media/<name>` | The images, 3D models and fonts, under the names the view uses |

A zip you make yourself works too: the workshop takes `model.yaml` (or the first YAML file with a
`flow`), `view.yaml`, `tactic.yaml` and the files under `media/`, also when everything sits in one
folder inside the zip.

Importing a single YAML file makes a new game of it when it is a model; a view or a tactic goes
into the tabs of the open game (Ctrl+Z undoes that). Images go into the open game's Images tab.

## Your browser keeps your games

Games and images live in the browser's storage for this site (IndexedDB), on this device only.
Clearing the site's data removes them; a private window forgets them when it closes (the workshop
says so when it cannot store anything). Download a package to keep a game safe or to move it to
another device. The images you add are yours to use; they are never published by Tabletwin.

## Limits

- A tactic in the workshop cannot use `extends`: paste the rules of the tactic it extends into it.
- The Play pane keeps the game it started with until you press "Restart with my latest changes".
- Look-ahead players (`search:`) are not offered in the simulator; they are slow in a browser.
- Simulation runs on your device, in the background; 10,000 games of a large model can take a while
  (Stop ends it).