Setup automation
Setup automation is the handful of steps taybl performs once, at game start, right after the placements lay everything out: shuffle the draw pile, deal opening hands, set each player’s starting score. It is pre-game bookkeeping, not a rules engine — once these steps finish, automation never runs again and players resolve everything by hand.
Steps run top to bottom in order, so deal after you shuffle. Each step is one
of four actions, chosen by its do field.
How to edit in the Studio
Open your game → Settings → Setup automation sub-tab. Under Automation, Add automation step and pick an action: Shuffle a zone, Deal cards, or Set a property. Under Starting properties, the Per-player properties and Global properties editors set initial key/value state. (Spatial what goes where placement lives on the Layout tab instead — see setup placements.)
Steps
do | Fields | What it does |
|---|---|---|
shuffle | zone; perSeat (.optional()) | Randomise a zone’s contents (a grid zone re-shuffles card↔cell). perSeat shuffles each seat’s copy |
deal | from, to, count; perSeat (.optional()) | Move count components from from into to. perSeat deals count into each seat’s copy |
setProperty | scope: 'global' | 'player', key, value | Set a starting property globally or on each player |
scatter | zone, components; cells, rules (.optional()) | Randomly redistribute a pool of pieces across a grid zone’s cells |
Every step also accepts two optional guards: whenPlayers: { min?, max? } runs
the step only when the seated count is in range, and whenOption: { option, equals }
runs it only when a setup option (below) holds a given value.
Scatter (randomized board setup)
A scatter step takes every object of the listed components already placed
in zone (a grid zone) and shuffles which cell each one occupies — the
hand-authored placements stay as the recommended
layout, and the scatter re-rolls it at game start. Omit cells and the pieces
permute among the cells they already occupy (Catan’s 18 number tokens swap
around their 18 land hexes; coast harbors stay on the coast). Pass an explicit
cells list to widen the candidate set.
You normally never author this by hand: in the Layout tab’s setup editor, flip
a placement group from Fixed to Random and taybl writes the scatter
step for you, gated on an auto-created Board setup option
(whenOption: { option: 'board_setup', equals: 'random' }) so players choose
Recommended or Random on the pre-game screen.
Not to be confused with a zone’s
arrangement: 'scatter', which is a loose visual pile. Thescatterautomation step is a one-time randomized redistribution across grid cells.
Scatter rules
The optional rules array constrains the shuffle. taybl honors the rules as
best it can (it re-rolls up to 100 times and keeps the best layout, so an
over-constrained board still starts — it never errors):
rule | Fields | What it enforces |
|---|---|---|
noAdjacent | property, values | No two pieces whose properties[property] is in values sit on touching cells (Catan’s “never put 6 & 8 next to each other”) |
maxRunLength | property, max | No connected cluster of more than max cells sharing the same properties[property] value (“no 3 of a resource touching”) |
evenSpacing | — | Spread the scattered pieces as far apart as the roll allows |
Adjacency uses the grid’s real neighbor relation — square cells touch
orthogonally, hex cells touch their six neighbors, and grid.connections
between cells count too.
Starting properties
On the setup block, playerProperties and
globalProperties are plain key/value records of initial state — a starting
score of 0, a firstPlayer flag, a difficulty level. playerProperties seed
every player; globalProperties seed the table once. A setProperty step can
overwrite or compute these at start time.
Setup options
A setup option is a choice players make on the pre-game screen before
anything runs — a “beginner mode” toggle, a board-variant pick. Options with no
on-table target belong here; on-table picks (which 10 kingdom piles, which board
half) use a selection instead. Automation steps react to the
chosen value through whenOption.
| Field | Type | What it does |
|---|---|---|
id | id | The option’s id; referenced by a step’s whenOption.option |
name | string | Label shown on the setup screen |
description | string (.optional()) | Helper text under the option |
kind | 'toggle' | 'choice' | A toggle is a boolean; a choice picks one of choices by id |
default | boolean | string | Initial value: a boolean for toggle, a choices[].id for choice |
choices | { id, name }[] (.optional()) | Required for kind: 'choice'; the selectable values |
Related
- Setup placements — what is on the table to begin with
- Selections — on-table picks (vs. setup options with no target)
- Decks — the draw piles you shuffle and deal from