The automation library
An automation is one named job the table can do for you: shuffle a deck, deal seven cards to everyone, sweep three board cells into the discard. You write it once, give it a name, and then two places can run it:
- Setup runs a list of them at game start.
- A button on the felt runs a list of them when a player clicks it.
That is the whole idea. The automation you wrote to deal opening hands is the same one a “Next round” button replays — you do not write it twice, and the two can never drift apart.
How to edit in the Studio
Open your game → Layout → the Automations tab. Add one, pick what
it should do, and fill in the fields that action needs.
This tab is the only place an automation is written. A setup step and a table button each name one and show you what it does, but neither can change it — so there is never a question of which panel is editing what. Both offer an Edit in Automations shortcut that brings you here with the right one open.
Then point things at it. On a button, or on an automatic setup step, pick the automation you want from the dropdown — or press ＋ there to make a new one without leaving the panel. A button can name several and drag them into order; all of them run top to bottom as a single action, one line in the history and one undo to take the whole thing back. The same automation can appear twice in one button if the sequence calls for it — shuffle, deal, shuffle.
Naming one
Give an automation a label and that is what you will see in every picker:
“Refill the market”, “Deal opening hands”. It is a name and nothing more —
nothing refers to it, so you can rewrite it whenever you like and no button
or setup step notices.
Leaving it blank is fine. An unnamed automation shows what it does instead —
Shuffle · Draw Pile — which is often clearer than a name would be. Name the
ones whose purpose is not obvious from their parts.
Underneath, each automation also has a short key. That is the handle setup
and buttons actually store, and it never changes once minted. You mostly
will not see it; it is shown in the automation’s own panel so you can
recognise it in an exported file or when asking Pip about one.
One library, shared. If a setup step and a button name the same automation, they are the same thing — editing it from either place changes both. Each panel tells you when something else runs what you are editing.
Choosing what a job acts on
Some actions work on a whole zone: shuffling half a deck is not a thing. Others
need to pick out particular pieces, and those take a select block.
select narrows by any combination of:
| Field | Means |
|---|---|
zones | Only look in these zones. Leave it out and the whole table is searched |
cells | Only pieces standing on these board cells |
components | Only pieces of these kinds |
where | Only pieces whose component property matches, e.g. { property: "terrain", value: "wheat" } |
faceUp | Only face-up (true) or only face-down (false) pieces |
count | At most this many |
end | Which end count takes from — top (the default) or bottom |
Everything you set has to match at once. Two examples worth knowing, because they are the two shapes almost every real request turns out to be:
Clear three spaces of a board, leave the rest alone. Name the zone and the cells; nothing else on the board moves.
Move · from Board cells a1, a2, a3 · to Discard
Gather every worker, wherever it ended up. Name the component and no zone at all, so the search covers the whole table — hands, board, play area.
Move · every Worker Meeple · to Supply
A select that matches nothing is simply skipped. It is not an error, and the
rest of the button still runs.
What an automation can do
Working on whole zones:
do | Fields | What it does |
|---|---|---|
shuffle | zone; perSeat | Randomise a zone’s contents. perSeat shuffles each seat’s copy |
deal | from, to, count; perSeat, cell, cells | Move count pieces from one zone to another. cell says where they land in an open play area; cells which board cells |
draw | from, to; count, end | Take from the top (or end: "bottom") of a pile into another zone |
fill | to, from, count | Top a market row back up to count. Does nothing if it is already full, so it is safe to run again |
takeFromBag | from, to; count | Draw at random rather than off the top — for a bag of tiles |
pass | zone; direction, count | Rotate a per-seat zone’s contents around the table |
sort | zones | Group a zone’s contents by component |
Working on particular pieces (each takes a select):
do | Fields | What it does |
|---|---|---|
move | select, to; cell, cells, faceUp | Move the chosen pieces somewhere else — the workhorse |
flip | select | Turn the chosen pieces over |
reveal / hide | select | Force them face-up / face-down |
untap | select | Stand them back upright |
switchState | select; stateId | Turn two-sided pieces to their other side (or a named one) |
rollDice | select | Roll the chosen dice |
Working on the board and the score:
do | Fields | What it does |
|---|---|---|
scatter | zone, components; fromCells, cells, rules, skipWhere | Randomly redistribute pieces across a board’s cells |
placeWhere | component, zone, property, value; attach | Put a piece on whichever cell holds a matching piece |
setProperty | scope, property, value | Set a global or per-player value |
adjust | scope, property, delta | Add to one — “+1 point”, “everyone takes 3 coins” |
resetBoard | — | Put everything back where setup put it. See below |
“Reset board”
resetBoard returns every piece your setup placed to exactly where it started —
the right zone, the right cell, the right way up, the right owner. It does not
create new pieces, so you can run it as often as you like without the table
filling up with duplicates. Pieces that setup never placed, like a copy a player
made mid-game, are left where they are.
It replays placements only, not the rest of your setup — which is deliberate, because you compose the rest from the same library:
Button “Reset board” runs: Reset board → Shuffle deck → Deal hands
That last one is literally the automation your setup already uses.
Running an automation only in some games
An automation can carry the same whenOption gate a setup step does, so it runs
only when players picked a particular variant. The gate still applies when a
button runs it mid-game — so an “Advanced module” step stays switched off all
game in a basic game, without you building two buttons.
See setup automation for how the gates themselves work.
Tips
- Order matters. A button runs its list top to bottom. Collect the discards before you shuffle, and shuffle before you deal.
- Keep buttons short. Two or three automations reads as one clear move; ten is a control panel.
- One automation, many buttons. If two buttons both need “shuffle the deck”, they should name the same automation — then fixing it fixes both.