Variable actions

Four blocks that write flow variables. A variable is per-client, holds text, and is read back anywhere text is expanded, as {{var:name}}.

Names may use lowercase letters, digits and underscores, 1–40 characters.

Variables live for as long as the client runs. Stopping the client clears them; they are not saved between runs. round and round0 are reserved for loop counters and cannot be used as variable names.

Using a variable in any input

The four blocks below write values while the flow runs. A different kind of variable is the one you fill in per client (a password, a server name, a greeting), and that one is not an action at all. It is a value block you drop into a text input.

A text input holds a piece of literal text by default. Drag the variable block over it to replace the whole thing, or drop in a join to mix the two:

[chat] chat  join  "Hello "
                   variable player_name
                   ", its alive"

The variable block has three settings:

Setting	Effect
name	What the field is called on the client, and what you would otherwise type as {{name}}.
default	Leave it empty and the value is required. Fill it in and the client may leave it blank.
plain / secret	A secret value is entered once, encrypted, and never shown again, not on the client page and not in the logs.

Nothing changes about how a flow is stored: the block is just a nicer way to write the same {{name}} token, and typing the token by hand still works exactly as it did. Join another join into the last slot when you need more than three pieces.

Numbers too

Every number on every block is an input as well: a count, a delay, a radius, a coordinate. Each starts as a plain number you type, and a variable dropped on it takes its place:

[timing] wait  variable pause_ms   ms

Two things follow from a number being filled in per client:

• When you type the value on a client, it is checked against the block that uses it. wait takes a whole number from 1 to 600000, so a client cannot save soon (or 1.5) for a variable used there. If one variable feeds two blocks, the stricter limit applies and the message names the block that set it.
• A value can still turn out wrong later, if the flow is edited after the value was entered. The client then skips that one action, writes a console line naming the variable and what it expected, and carries on with the rest of the trigger.

A variable in a wait supplies milliseconds, whatever the unit dropdown says. The unit multiplies a number you type; it has nothing to multiply when the value arrives from the client, so the value is taken as it is.

The one thing only the block can express is secret. A bare {{name}} cannot say that a value is sensitive, which is why passwords had to be written as {{secret:name}} by hand before.

set_var

Stores a value in a variable, replacing whatever was there.

Field	Type	Required	Notes
name	variable name	yes	Lowercase, digits, underscores.
value	≤256 chars	yes	Expanded first, so it can be built from other variables.

Everything is text. The arithmetic block and the numeric conditions read that text as a number when they need to. A variable holds at most 256 characters: a longer value, which expanding other variables can produce, is cut to 256 and the console warns.

inc_var

Adds a fixed amount to a variable, treating its current value as a number. The counting primitive for quotas and retry loops.

Field	Type	Required	Notes
name	variable name	yes
by	−1000000…1000000	no	Default 1. Negative subtracts.

An unset variable counts as 0, so a counter does not need initialising first. A variable that holds text which is not a number also counts from 0, and the console warns.

math_var

Arithmetic whose operands are expanded, which is what separates it from the add block, which can only add a literal.

Field	Type	Required	Notes
name	variable name	yes	The variable read and written.
fn	add, sub, mul, div, mod, min, max, set, random	yes	See below.
value	≤64 chars	yes	Expanded.
value2	≤64 chars	no	Only used by random.

• add, sub, mul, div, mod, min, max: apply the function to the variable's current value and the operand.
• set: store the operand as a number, so 12.50 lands as 12.5.
• random: a whole number between the two operands, inclusive.

A non-numeric operand, an empty one (such as a variable that is not set), or a division by zero leaves the variable unchanged and writes a warning to the console. A silently wrong number is worse than a step that says it did nothing.

read_state

Writes one live fact about the client into a variable. Conditions could always test the client's state; this is how a flow reports it.

Field	Type	Required	Notes
name	variable name	yes	Where the value lands.
source	see the table below	yes	Which fact to read.
item	registry name	no	Only for item count: which item.
matchBy	name, display name, lore	no	Default name. How the item is matched.

Source	Value written
health	Current health, 0–20
food	Current hunger, 0–20
xp_level	XP level
x, y, z	One coordinate
position	All three coordinates as whole numbers separated by spaces, like 100 64 -200
dimension	Current dimension
held_item	Registry name of the held item
item_count	How many of the named item are carried
free_slots	Empty inventory slots
players_online	Player count on the server
mc_time	In-game hour of the day, 0–23
username	The client's own name
server_host	The server it is connected to, as address:port
ping	Round-trip latency in milliseconds