Setup steps
A game’s setup steps are one ordered, reorderable list describing everything
that happens before the first turn — the choices players make and the steps the
table runs automatically. It is the authored source of truth: when you edit
setup in the Studio you are editing setupSteps, and taybl derives today’s
engine-facing fields (setupOptions, setup.automation, and the first phase’s
selections) from it automatically. The sandbox keeps reading those derived
fields, so nothing about play changes — setupSteps is purely the authoring
layer on top.
Every step is exactly one of five types:
| Type | One-liner | Maps to |
|---|---|---|
| variant | A switch flipped for the whole table | a setup option + its gated automation |
| identity | Each player claims one unique thing | a per-seat component selection (+ grant) |
| pool | The table picks N of a set together | a shared selection |
| draft | Each player culls a privately-dealt hand | a per-seat selection from a dealt pool |
| auto | No player input; runs silently at start | one setup.automation entry |
Variant
A variant is a toggle or one-of-N choice the whole table shares — beginner
mode, difficulty, an edition, a board map. Set its kind (toggle or choice),
its default, and (for a choice) the list of choices. Crucially, a variant
carries the automation it turns on in runs[] — each entry keeps its own
whenOption gate so the On/Off (or per-choice) flow survives a round-trip.
Editing "Beginner mode → uses a fixed layout, skips a shuffle" happens in one
place, instead of the old inverted model of authoring an automation step then
gating it on an option by name.
Identity, pool & draft (selection-shaped)
These three share the same selection shape — scope, targets, a from pool of
ids, and a count of { min, max }:
- identity —
scope: 'perSeat',targets: 'component'. Each player claims one unique thing (a color, a role, a faction). It cangrantthe picked piece (and its property-matched siblings) to that player — see grants. - pool —
scope: 'shared'. The table picks N from a larger set together (Dominion’s 10 of 25). Offer a "randomize for us" button withrandomize. A component-targeted pool can also carrydistributeTo: at game start the table dealscountEachcopies of each picked component type into one of the listed destination zones (toZones), one pick per zone — Dominion’s 10 supply piles. - draft —
scope: 'perSeat'from a freshly dealt hand. Each player keeps a few (Ticket to Ride’s keep 2 of 3).
Two more player-affordance fields apply: assign (how a per-seat pick is
resolved — free pick, random, deal, or draft) and exclusive (no two players
may share the same pick). Because a selection phase hides every non-target zone,
list any destination zone (the hand picks land in) in alsoShow to keep it on
screen while picking.
Auto
An auto step is silent automation — players never act on it. It wraps exactly
one operation in run: a shuffle, a deal, or a setProperty. These run at
game start and surface to players only as a quiet "setting up…" line.
Fields
| Field | Applies to | What it does |
|---|---|---|
type | all | variant | identity | pool | draft | auto |
kind | variant | toggle (boolean) or choice (one of choices) |
default | variant | initial value — a boolean for a toggle, a choice id for a choice |
choices | variant | the selectable values (required for a choice) |
runs | variant | the gated automation this variant turns on |
scope | selection | shared (the table picks together) or perSeat (each player picks) |
targets | selection | zone outlines or component faces become clickable |
from | selection | the pool of ids to pick from |
count | selection | how many to pick — { min, max } |
grant | selection | identity assignment for component picks — see grants |
assign | selection | how a per-seat pick is resolved — pick | random | deal | draft |
exclusive | selection | no two players may share a pick |
optional | selection | when true, players may skip — unfilled picks are auto-assigned randomly on game start |
randomize | pool | offer a "randomize for us" button |
distributeTo | pool | deal each picked component type into a supply zone — { toZones, countEach, faceUp? } |
alsoShow | selection | extra zones kept visible during this step’s phase |
deal | draft | the deal automation that produces this draft’s privately-dealt hand |
run | auto | the single silent automation (shuffle / deal / setProperty) |
Related
- Setup automation — the silent
shuffle/deal/setPropertyops an auto or variant step emits - Selections — the derived per-phase pick interaction an identity/pool/draft step expands to
- Grants — assigning a picked component to a player