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.

• Session Started (sessionStarted) -- fires when a new session begins. No context keys, no filter options.

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.