Triggers

What a trigger is

A trigger is an event dispatcher attached to a piece. When the piece fires an event (a button is pressed, a timer expires, a game state change occurs), the trigger evaluates its cases and runs the matching sequences.

Trigger structure

A trigger contains:

• Dispatch mode -- controls how many cases run
• Cases -- an ordered list of condition/sequence pairs
• Enabled -- a toggle that lets you disable a trigger without deleting it. Disabled triggers are skipped entirely.
• Ask Before Running (optional) -- when enabled, the trigger presents a confirmation dialog to the player before executing. The player can accept or reject the trigger. This is useful for reactive triggers where you want the player to have a chance to cancel an automatic action.

Dispatch modes

• First Match -- evaluates cases top to bottom and runs only the first case whose condition passes. This is the default.
• All Matching -- evaluates every case and runs all whose conditions pass.

Cases

Each case has:

• Sequence -- the sequence to run when this case matches
• Condition (optional) -- a condition that must be true for this case to match. Cases without a condition always match as a fallback.
• Label (optional) -- a human-readable name for the case
• Event (optional) -- the specific event this case responds to

Cases are evaluated in order, which matters for First Match mode.

Manual triggers

Manual triggers require player interaction to fire.

Buttons

A button fires a single event:

• press -- fires when a player clicks the button

Timers

A timer fires four events:

• expired -- fires when the timer reaches zero
• started -- fires when the timer is started
• paused -- fires when the timer is paused
• reset -- fires when the timer is stopped or reset to its full duration

Timer trigger cases are grouped by event in the editor, so you can attach different sequences to different timer lifecycle events.

Reactive triggers

Reactive triggers fire automatically when game state changes. Unlike manual triggers (buttons and timers) which require player interaction, reactive triggers respond to pieces moving between containers, dice being rolled, counters crossing thresholds, and other state changes.

Each entity type that supports reactive triggers is configured through the Trigger tab in its settings dialog. The trigger editor groups cases by event type, and creates one trigger per event type automatically.

Spaces

Spaces support two events that fire when pieces enter or leave the space.

• Piece Added (pieceAdded) -- fires when a piece lands on the space. Context: triggerPiece, triggerSpace, triggerFromSpace (optional -- only provided when the piece came from another space).
• Piece Removed (pieceRemoved) -- fires when a piece leaves the space. Context: triggerPiece, triggerSpace.

Filters: piece type filter, required tags, blocked tags.

Example: When a piece lands on a scoring space, trigger a scoring sequence.

Stacks

Stacks support five events covering tile movement, sleeve movement, and shuffling.

• Tile Added (tileAdded) -- fires when a tile enters the stack. Context: triggerPiece (the tile), triggerStack, triggerFromStack (optional -- only provided when the tile came from another stack).
• Tile Removed (tileRemoved) -- fires when a tile leaves the stack. Context: triggerPiece (the tile), triggerStack.
• Sleeve Added (sleeveAdded) -- fires when a sleeve enters the stack. Context: triggerPiece (the sleeve), triggerStack, triggerFromStack (optional -- only provided when the sleeve came from another stack).
• Sleeve Removed (sleeveRemoved) -- fires when a sleeve leaves the stack. Context: triggerPiece (the sleeve), triggerStack.
• Shuffled (shuffled) -- fires when the stack is shuffled. Context: triggerStack only. No filter options.

Filters (tile/sleeve events): piece type filter, required tags, blocked tags.

Example: When a card is added to the discard pile, trigger a scoring check.

Token Bowls

Token bowls support two events that fire when pieces enter or leave the bowl.

• Piece Added (bowlPieceAdded) -- fires when a piece is added to the bowl. Context: triggerPiece, triggerBowl.
• Piece Removed (bowlPieceRemoved) -- fires when a piece is removed from the bowl. Context: triggerPiece, triggerBowl.

Filters: piece type filter, required tags, blocked tags.

Example: When a token is returned to the supply bowl, trigger an end-of-round check.

Bags

Bags support two events that fire when pieces enter or leave the bag.

• Piece Added (bagPieceAdded) -- fires when a piece is added to the bag. Context: triggerPiece, triggerBag.
• Piece Removed (bagPieceRemoved) -- fires when a piece is drawn from the bag. Context: triggerPiece, triggerBag.

Filters: piece type filter, required tags, blocked tags.

Example: When a piece is drawn from a bag, trigger a reveal sequence.

Counters

Counters support one event that fires when the counter crosses a configured threshold.

• Counter Threshold (counterThresholdCrossed) -- fires when the counter value crosses a threshold boundary. Context: triggerPiece, triggerValue, triggerPreviousValue.

Filters: threshold value, threshold direction (above, below, or reaches -- where "reaches" fires when the counter hits the exact threshold value from either direction).

Dice

Dice support one event that fires after each roll.

• Die Rolled (dieRolled) -- fires when the die is rolled. Context: triggerPiece, triggerValue.

Filters: value filter (specific face values that should trigger the event).

Pieces (flip)

Any piece with two faces supports a flip event.

• Piece Flipped (pieceFlipped) -- fires when the piece is flipped. Context: triggerPiece, triggerValue.

Filters: flip direction (face up, face down, or any).

Session

Session-level triggers fire based on session lifecycle events.

• Set Up Game (gameSetUp) -- fires once, when a player at the table presses Set Up Game in the Action Dock. Put anything that involves the players here: dealing hands, handing out starting pieces, and steps that depend on how many players are seated (use the Seated Players condition in an Only If). The actor is the player who pressed it. The button appears only in a play session, never while you edit a table configuration; to try a setup while editing, press Test Fire on the trigger in the Session Triggers section, or start a play session with Play. Reset Table makes it available again, and undoing the setup does too. Undoing it takes back only what the setup did: players who sat down after it was pressed keep their seats.
• Session Start (sessionStarted) -- fires the moment a new session is created, when the only person at the table is whoever made it. Use it for things that do not involve the players, like shuffling a deck or starting a timer. A sequence that deals to players or checks how many are seated would run against a table of one here, so the trigger editor warns you and points you to Set Up Game.

Both have no context keys beyond actor and no filter options. You add them in the Session Triggers section of the sequences editor.

Test Fire

Test Fire runs a trigger's sequences as if its event had just happened, so you can try them without moving pieces around. Only the trigger you test runs, not others listening for the same event. If the trigger has Ask Before Running on, it asks first, as it would in play. The run shows in the Sequence Debugger like any other.

A test has no real piece behind it. For a space, stack, token bowl or bag event, the sequences get the space, stack, bowl or bag (triggerSpace, triggerStack, triggerBowl or triggerBag) but no triggerPiece, unless the trigger watches one particular piece, and the piece type and tag filters are not checked. A step that uses triggerPiece stops with a message saying it is missing. A trigger set off in play, then accepted after Ask Before Running, gets the real piece, roll or values that set it off.

A die, flip or counter trigger needs to know which piece it watches before it can be test fired, and a space event needs its space. If that is not set, Test Fire says so instead of running, and it says so for a trigger that is turned off. Whenever a test fire is refused, the reason shows on screen.

Context

When a trigger dispatches a sequence, it provides context that steps can use.

Base context

All triggers provide:

• source -- the piece that owns the trigger
• actor -- the seat index of the player who caused the event

Reactive trigger context

Reactive triggers provide additional context keys specific to the event type. These keys let sequence steps reference the pieces and containers involved in the event.

Conditions

Trigger cases can use conditions to create switch-case-style dispatch. Conditions inspect game state (counter values, die faces, piece positions, tags) and support logical composition with AND, OR, and NOT operators. See Sequences for more on how conditions work throughout the system.

Filter options

Several reactive trigger event types share a common set of piece filters. These filters narrow which pieces cause the trigger to fire:

• Piece Type Filter -- restricts to specific piece types (tile, token, die, counter, stack)
• Required Tags -- the piece must have ALL listed tags for the trigger to fire
• Blocked Tags -- the piece must NOT have any listed tags for the trigger to fire

These filters are available on space, stack (tile/sleeve events), token bowl, and bag events.

When one action moves several pieces at once, such as dropping a group selection into a space, the trigger fires once for each piece that passes its filters, whatever order the pieces arrive in. It fires at most once per piece per action.

All the automation that one action sets off runs together with that action, and the action and its automation share one allowance of work. The action's own work counts first, so an action that moves many pieces at once leaves less room for its triggers.

• When the allowance is used up, no further step or run starts: what already ran stays, the action itself still goes through, and the Sequence Debugger shows the stopped run with the reason. For example, dropping ten cards into a space whose trigger shuffles a 100-card deck for each card shuffles the deck once and stops the other runs. A drop large enough to use up the allowance by itself runs none of its triggers, and the Debugger says so.
• A single step that would do far more work than one action can (for example, shuffling a deck of several hundred cards) is stopped as soon as it reaches the limit. If it had not changed anything yet, the action still goes through and the Debugger names the step. If it had already started changing the table, it cannot be stopped part way, so the whole action is refused with a message naming the step, and nothing changes.

Give the trigger a filter so it fires for fewer pieces, or move heavy steps to a button, where they run on their own.

Runs someone asked for (Run Sequence, a button or timer, an answered prompt, Set Up Game, Session Start, a trigger you accept after Ask Before Running, and Test Fire) have no action of their own before them, so they can use the whole allowance, and no "stop before starting" line applies. A single step in one of them that would do more work than one action can is still stopped with a message naming the step, the same way: for example, a Select by Filter step with no space or hand named on a very crowded table. Name a space or a hand in the filter, or split the work into smaller steps. If a prompt's timeout resumes a run and a step is stopped this way, nothing that step did is kept, and the Sequence Debugger says why.

A table holds at most 500 sequences and 2,000 triggers. Creating, duplicating or restoring past that, starting or saving a table from one past it, and importing a game archive with a table past it are refused with a message that says so.