Triggers

A trigger is the hat a flow hangs from: the blocks snapped underneath it run when the trigger fires. A flow can hold many triggers, each with its own stack of actions.

Every example on this page is drawn the way the editor draws it: a green hat with the blocks that run beneath it. White boxes are the fields you fill in.

Three rules apply to every trigger here.

• One firing at a time. While a trigger's actions are still running, the same trigger ignores further events until it finishes. A chat trigger that takes eight seconds does not queue up eight seconds of backlog.
• Blocks must be snapped under the hat. A block left floating on the canvas is not saved. The editor warns you before you lose it.
• Some triggers hand values to the actions, written {{var:name}} in any text field. Each section below says which.

Sections are ordered exactly as the editor's Triggers palette lists them.

join

Runs once, each time the client finishes connecting to the server. The usual home for a login command or an announcement.

No fields.

Fires again on every reconnect, so anything here must be safe to repeat.

timer

Runs the blocks underneath repeatedly, on a fixed interval or on a random interval between two values.

Field	Type	Required	Notes
everyMs	1 second to 1 day	yes	The editor takes a number plus a unit.
everyMaxMs	1 second to 1 day	no	Turns the interval random: each wait is picked between everyMs and this value.

The every … to …, random block in the palette sets both values. Before each firing it picks a new wait anywhere between the two, so a timer of 3 to 7 minutes might wait 4, then 6, then 3. A higher end that is not above the lower one leaves the interval fixed.

The interval is the gap between firings, not a guaranteed rate: if the actions take longer than the interval, a tick that comes while they still run is dropped, not queued, and the timer fires again on the next tick after they finish.

schedule

Runs at a wall-clock time, optionally only on the days you tick. Use this instead of a timer for "every day at 20:00": a timer drifts, a schedule does not.

Field	Type	Required	Notes
at	HH:MM, 24-hour	yes	The time you type is your local time.
days	any of Sun to Sat	no	All seven ticked, or none, means every day.
offsetMinutes	−840…840	no	Filled in from your own clock by the editor.

The offset is a fixed number of minutes, not a timezone: daylight saving cannot silently move the schedule under you, but you do have to re-set it yourself when your own clock changes.

death

Runs when the client dies.

No fields.

Dying and coming back are two separate events, so pair this with respawn.

respawn

Runs each time the client respawns, after a death or a dimension change.

No fields.

health

Runs when health drops below a threshold. 20 is full hearts.

Field	Type	Required	Notes
below	1–20	yes	Fires when health falls under this value.

Fires once on the way down, when health goes from this value or more to less than it. It fires again only after health has been back at or above the value, so regeneration ticks while it stays low do not repeat it. below 8 does not fire at exactly 8.

food

Runs when hunger drops below a threshold. 20 is full.

Field	Type	Required	Notes
below	1–20	yes	Fires when food falls under this value.

Fires once when food drops under the value, and again only after food has been back at or above it.

damage

Runs whenever the client takes damage, from any source.

No fields.

Fires on every hit, so keep the stack short. A long one will still be running when the next hit lands, and that hit is ignored.

level_up

Runs when the client's XP level increases.

Field	Type	Required	Notes
level	1–1000	no	Fires only at or above this level. Blank fires on every level up.

Hands over {{var:level}}, the new level.

player_near

Runs when any player comes within the radius. Edge-triggered: it fires on entry, not continuously while someone stands there. If someone enters again while the actions are still running, the trigger runs once more when they finish, as long as that player is still in range.

Field	Type	Required	Notes
radius	1–64	yes	Blocks.

mob_near

Runs when a hostile mob enters the radius. Edge-triggered, like player_near.

Field	Type	Required	Notes
radius	1–64	yes	Blocks.

player_join

Runs when a player joins the server.

Field	Type	Required	Notes
player	player name	no	Blank fires for anyone.

Hands over {{var:player}}.

player_leave

Runs when a player leaves the server.

Field	Type	Required	Notes
player	player name	no	Blank fires for anyone.

Hands over {{var:player}}.

low_on_item

Fires once when the carried count of an item drops below a threshold, and re-arms when the count recovers. For restocking blocks, food or ammunition.

Field	Type	Required	Notes
item	registry name	yes	For example cooked_beef.
below	1–2304	yes	Fires when the carried count falls under this.

Edge-triggered, so it will not fire again while the count stays low. It waits for a recovery first.

inventory_full

Fires once when no empty inventory slot is left, and re-arms when a slot frees.

No fields.

item_collected

Runs when the client picks an item up off the ground.

Field	Type	Required	Notes
item	registry name	no	Blank fires for any item.

Hands over {{var:item}} and {{var:count}}.

night

Fires once when the in-game day turns to night.

No fields.

In the editor this is one option on the world-state block, which also emits day, rain and weather_clear.

day

Fires once when the in-game night turns to day.

No fields.

rain

Fires once when it starts raining.

No fields.

weather_clear

Fires once when the rain stops. The counterpart to rain.

No fields.

goal_reached

Fires when a go-to or a follow finishes its path. This is how a flow walks somewhere and then acts, instead of guessing with a wait.

No fields.

goto_failed

Fires when a path cannot be found, or pathfinding times out.

No fields. Hands over {{var:reason}}.

kicked

Runs when the server kicks the client.

No fields.

The client's own auto-reconnect already handles getting back on. Use this to be told about it, or to change something before the next attempt.

before_stop

The last chance to act before a commanded stop: empty the inventory into a chest, log out cleanly, send a notification.

No fields.

Two limits matter. It runs on a five-second budget (a stop must never hang waiting for a flow), and it does not fire for a kick or a dropped connection, only for a deliberate stop.

flow_error

Runs when any other trigger's actions fail. One central place to be alerted, instead of wrapping every trigger in a try.

No fields. Hands over {{var:error}} (the message) and {{var:reason}} (the event that failed).

It never fires for its own failures, since that would loop.

chat

Runs when a chat line arrives and matches an optional pattern.

Field	Type	Required	Notes
filter	regular expression, ≤200 chars	no	Blank matches every line.
from	up to 64 player names	no	Fire only for lines sent by these players. Blank = anyone.

Hands over {{var:player}} (the sender, empty when none was found), {{var:message}}, plus {{var:m1}} … {{var:m9}} for the pattern's capture groups.

When the line has a sender, the filter sees only the message after the name: for <Alice> !home base it tests !home base, which is also what {{var:message}} holds, so ^ anchors at the start of what Alice typed. A line with no sender, like a server broadcast, is tested whole. Matching is case-sensitive, so write [Hh]ome where the case can vary.

from matches the sender, read out of the rendered line's <name> or [rank] name: prefix. Private messages count too: in [Steve -> me] hi and Steve whispers to you: hi the sender is Steve and the message is hi, while the messages the client sends itself ([me -> Steve] hi) have no sender. A line that merely mentions a listed name is not a match. Because the sender is read from the rendered text, this works on custom-plugin chat formats that mineflayer cannot parse, which is why, on a plugin server, the chat trigger with a player list is the combination that works, and whisper often is not.

whisper

Runs on a vanilla private message.

Field	Type	Required	Notes
filter	regular expression, ≤200 chars	no	Blank matches any whisper.
from	up to 64 player names	no	Restrict senders. Blank = anyone.

Hands over {{var:player}} (the sender), {{var:message}} and the capture groups.

Only vanilla whispers reach this. On servers whose plugins render private messages as ordinary chat lines, use the chat trigger instead.

actionbar

Runs on text the server pushes to the action bar, the line above the hotbar. Plugin servers commonly put balances, timers and queue positions there.

Field	Type	Required	Notes
filter	regular expression, ≤200 chars	no	Blank matches any action-bar text.

Hands over {{var:message}} and {{var:m1}} … {{var:m9}}.

In the editor this is one option on the HUD-text block, which also emits title, bossbar and scoreboard.

title

Runs on a title or subtitle the server sends.

Field	Type	Required	Notes
filter	regular expression, ≤200 chars	no	Blank matches any title.

Hands over {{var:message}} and the capture groups.

bossbar

Runs on boss-bar text, often a countdown or an event announcement.

Field	Type	Required	Notes
filter	regular expression, ≤200 chars	no	Blank matches any boss bar.

Hands over {{var:message}} and the capture groups.

scoreboard

Runs when a scoreboard line changes.

Field	Type	Required	Notes
filter	regular expression, ≤200 chars	no	Blank matches any scoreboard text.

Hands over {{var:message}} and the capture groups.

menu_open

Runs when a server GUI or menu opens: a shop, a kit picker, a warp list.

No fields.

window_closed

Runs when a server GUI closes. The counterpart to menu_open, so a shop flow can tell the menu went away instead of guessing with a wait.

No fields.

signal

Runs when another client of the account sends a signal on this channel.

Field	Type	Required	Notes
channel	lowercase name, [a-z0-9_]{1,40}	yes	Fire only for this channel.
from	array of client names, max 50	no	Only from these senders. Leave out for any of the account's clients.

The firing gets {{signal_from}} (the sender's client name), {{signal_message}} (empty, without a warning, when the signal carried no message), {{signal_x}}, {{signal_y}}, {{signal_z}} (where the sender stood when it sent, whole numbers) and {{signal_dimension}}. So "come here" is this trigger with a goto to those coordinates.

Signals come from the signal action, and only from clients of the same account. A client that starts after a signal was sent never sees it. Like any trigger it ignores a new signal while its own firing is still running. In Try it you can fire it by hand with the fields filled in.

task

Runs only when something outside the game asks for it: Run now on clients or the flow's webhook URL. Nothing in the game fires it.

No fields.

The event is named task for historical reasons: it predates Run now on clients, and stored flows use it.

Any other trigger can be started by hand too, on one client, with Run a flow on the client's page or Run on server in the editor. See Run any trigger now.

routine

A named stack of blocks that other blocks call with run routine. It never fires on its own; it is how you write a sequence once and reuse it.

Field	Type	Required	Notes
name	lowercase name, ≤40 chars	yes	What the run-routine block refers to.