DocsSetup & automation

Setup placements

A setup placement is one line of the opening arrangement: “put these components into this zone.” The list of placements is the snapshot of the table the moment the game starts — every deck stacked, every player’s starting pieces in front of them, the board seeded. After setup runs, taybl steps back and players move everything by hand.

Each placement names what to place and where it goes. What is either a single component or a whole group of cards (a deck — every card in the group). Where is a zone; for a tableau of interchangeable positions, target a grid zone and a bulk placement auto-spreads one component per cell.

How to edit in the Studio

Open your game → Layout tab. The Setup inspector groups placements into one card per kind (Land hexes ×19, Number tokens ×18) with a per-piece list inside each card. Positions read as human labels derived from the board (N · outer, Centre) — never raw cell ids. Hover a card, an inventory chip, or a row and the matching cells glow on the board; click any cell on the board to edit what starts there in a popover. Use + Add placement for a new line, and drag a placed component on the table to relocate it.

Fixed vs Random (board setup)

Each group card carries a Fixed | Random toggle. Fixed keeps your hand-placed layout every game. Random scatters that group’s pieces across their cells fresh each game — taybl auto-creates a Board setup option (Recommended / Random) on the pre-game screen and writes a gated scatter automation step for you. A Random group reveals its scatter rules checklist (e.g. never put 6 & 8 next to each other) and renders on the board with a dashed “?” over your layout, which stays visible as one example roll. The top-level Recommended/Random pair flips every group at once; mixing them reads as a Custom mix.

Shuffle / deal / set-property steps are not placements — those live in Settings → Setup automation (see setup automation).

Fields

Field	Type	What it does
`component`	id	The single component to place. Provide exactly one of `component` or `group`
`group`	id (.optional())	Place every card in this card group (a deck) instead of a single component
`zone`	id	Target zone. For a tableau, a grid zone spreads a bulk placement one-per-cell
`count`	number (.optional())	How many copies to place. Absent → all (for a `group`) or one
`faceUp`	boolean (.optional())	Place face up (`true`) or face down (`false`). Wins over the zone’s `faceOnEnter`; absent → the zone’s `faceOnEnter` decides, and with neither set components start face down. See Facing
`cell`	string (.optional())	A specific grid cell / node / edge id when the target is a grid zone. Meaningless with `group`
`seat`	number (.optional())	Target one specific seat’s copy of a `perSeat` zone (0-based). Mutually exclusive with `perSeat`
`perSeat`	boolean (.optional())	Apply once into every seated player’s copy of a `perSeat` zone (e.g. “each player starts with one worker”). Requires the target zone’s `scope: perSeat`
`whenPlayers`	`{ min?, max? }` (.optional())	Only apply this placement when the seated player count is within `[min, max]`. Absent → always. Lets setup scale with table size
`whenOption`	`{ option, equals }` (.optional())	Gate this placement on a chosen setup option. A gated placement is deferred until the players press Start Game and only applies when the option matches — its components stay unplaced until then

Facing

The faceUp rule is the same for every zone arrangement — stack, fan, grid, scatter, slot. It is applied to each placed copy individually; the arrangement only changes the geometry (a pile vs. a spread vs. cells), never the facing. The engine resolves each object’s face in this order:

An explicit faceUp on the placement wins.
Otherwise the target zone’s faceOnEnter decides: up / othersOnly → face up, down / owner → face down.
With neither set (or faceOnEnter: keep), the object stays face down — the creation default for anything flippable.

faceUp only means something on a component that has a face: cards always do; pieces and tokens only when they are flippable (a behaviors.flippable flag or back art). On anything else it is silently ignored. Note that facing is the object’s physical orientation — what an opponent actually sees is separately governed by the zone’s view (zone visibility), which redacts hidden faces before they reach other players.

Setup options & variants

A placement can belong to a variant — a beginner-vs-random board, a short- vs-long game. Pair it with a setup option via whenOption: the placement is held back at game start and only applied at Start Game, against the value the players picked. Model both sides of a choice as whenOption-gated (e.g. a beginner placement with fixed cells and a random placement onto the grid zone) so the opening arrangement places neither by default and the component pool stays intact for whichever variant wins. For a randomized board variant, prefer the Fixed/Random toggle above — it writes the whenOption-gated scatter step for you.

seat and perSeat are mutually exclusive — a placement targets either one specific seat or all of them. Both require the target zone to have scope: perSeat; a shared-scope zone is filled once, plain. See zone scope for the shared-vs-per-seat distinction.

Setup automation — shuffle, deal, and starting properties
Components overview — the things you place
Grids — placing into a specific cell, node, or edge, or spreading a tableau
Zone scope — when seat / perSeat apply