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, cell, cells (.optional()) | Move count components from from into to. perSeat deals count into each seat’s copy; cell says WHERE they land in an open play area, cells which board cells they land on |
setProperty | scope: 'global' | 'player', key, value | Set a starting property globally or on each player |
scatter | zone, components; fromCells, cells, rules, skipWhere (.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. equals takes one
value or a list of them (any of which matches), and whenOption itself can be a
list of gates that must all hold — so a shuffle wanted by four of five game modes
is one step gated on all four, not four near-identical steps you then have to
keep in step by hand. In the step inspector that is the Runs when row of chips:
tick every value the step should run for, one row per declared option.
Where a deal lands
Most zones arrange their own contents — a hand fans, a pile stacks — so a deal
into one has nothing to decide. An open play area is
different: things there sit at whatever point they were put down, so a deal has
to say where. That is what cell is for.
Write it as freepoint_X_Y — whole millimetres from the CENTRE of the
destination zone, +X right and +Y down. freepoint_0_0 is the middle;
freepoint_-120_45 is 120 mm left of centre and 45 mm down. In the editor you
never type that: pick the deal step and fill in Across and Down, or just
drag one of the dealt cards on the table to where it should start.
Leave cell out and the table picks a clear spot for you, the same way it does
for a placement with no position — successive deals
into one area land side by side rather than on top of each other.
The whole batch lands on ONE point. A deal is a single step drawing off a pile,
so it has no per-card position — count: 3 puts three cards on the same spot,
and dragging any one of them moves the deal, not that card. To fan them out, give
the zone landing rules: the first card takes row 1, the
second row 2, and their offsets spread the pile.
cell is open-play only. On a hand or a pile it is rejected — those arrange
their own contents, so there is no point to name. A board is rejected too, but
only because it has a better field: cells.
Dealing onto a board
A board is the one destination where a deal really does have a per-card position, so it behaves the opposite way round: it spreads instead of piling. Deal 12 queens into a 4×3 grid zone and you get one queen per cell, filling empty cells before it reuses a taken one — the same rule a placement with no position follows.
That is the default and it needs no authoring. Fill in Where it lands on the deal step only when the cards have to land on particular cells: name them in deal order and card 1 takes the first, card 2 the second, and so on.
Name fewer cells than there are cards and the list wraps round. Three cards over
two cells puts a second card on the first cell, and that second card arrives as
that cell’s NEXT landing — so the cell’s landing rules spread
the pile exactly as they would for a second drop. One cell named and count: 4
is therefore a legitimate way to build a face-down pile on a single square.
A board has to have cells to name for any of this: an open lattice mints its positions where pieces land and has no fixed set, so a deal into one still leaves the cards for a player to place by hand.
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.
There are three ways in, and they all write the same step. The guided one: in
the Layout tab’s setup editor, flip a placement group from Fixed to
Randomize and taybl writes the scatter 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. The fast
one: tick the Random column on Sheet mode’s
Placements tab — it acts on the whole placement card the row belongs to, so
you can fill it down a board in one gesture. The precise one: the Sheet’s
Automation tab, where the pool, the cells, the rules and the skip
constraint are each a column.
skipWhere: { property, value } is the hard constraint the other two do not
reach: it keeps the pieces off any candidate cell whose occupant already
carries that property value — no number token on the desert.
Which pieces move: fromCells
components names component kinds, and one kind is usually placed many
times — four ore hexes are four pieces of a single component. Naming it takes
all four. fromCells narrows the pool to the pieces standing on the cells you
list, which is the only way to shuffle some placements of a component and
leave the rest exactly where you put them.
Keep the two straight: fromCells is who moves, cells is where they may
land. Give fromCells alone and they permute among their own cells, which
is almost always what you want. Omit it and every copy joins the shuffle,
which is what a scatter has always meant and what the Fixed / Randomize
toggle writes.
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.
A zone can carry the same whenOption gate, and it is the one thing here
that never “runs”: rather than firing once at game start, it says the zone is
different for that variation — a discard pile that rests face-up all game long.
See zones that change with the variant.
The pre-game screen shows for any game with something to ask — a solo table, a fixed-player-count game, and a live session alike — so an option you author is always put to the players, and the steps gated to it run the moment someone presses Start game.
| 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 |
Editing them in bulk
The Automation tab in Sheet mode is one row per
silent step, with the action and its fields as columns. It edits the authored
auto steps rather than this derived list, which is what makes an edit there
survive Save.
A scatter is authored there field by field: Pool is the components that
get shuffled, From cells narrows that to the pieces on particular cells,
Cells the positions they may land on (leave it blank for the usual case —
they permute among the cells they already sit on), Rules the constraints,
and Skip where / Skip value the cells to stay off.
Rules are typed as noAdjacent:value=6|8; maxRunLength:terrain=2; evenSpacing
— the same three forms the Setup-mode checklist offers, spelled out so they
survive an Excel round-trip.
A scatter written by the Fixed/Randomize toggle lives inside the Board setup variant rather than as a step of its own. Those show up here too, one row per run, named after the variant that switches them on. You can edit what they randomise; their title and their condition belong to the variant, so those cells are closed.
Related
- Sheet mode — the Automation tab, one row per silent step
- 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
- Zones that change with the variant — a
whenOptiongate that changes a zone instead of running a step