Variables are mutable string values stored per-menu-instance. They act as local state, accessible as %var.<name>% placeholders anywhere in the menu.
Declaration
Declare variables in the variables: map with their initial values:
variables:
page: "0"
mode: "buy"
selected: "none"
Values are plain strings but may contain expressions (see below).
Reading Variables
Use %var.<name>% in any field that supports placeholder substitution:
title: "<bold>Shop — %var.mode%"
name: "<yellow>Page %var.page%"
Updating Variables
Use the set-variable action:
actions:
LEFT:
- "[set-variable] page 0"
After the variable is updated, affected slots are automatically re-rendered.
Expression Syntax
Variable values support simple arithmetic and ternary expressions. The expression is evaluated at the time set-variable runs.
Arithmetic
Standard operators: +, -, *, /
Operands may be literals or %placeholder% references that resolve to numbers.
- "[set-variable] count %var.count%+1"
- "[set-variable] score %param.base%*%var.multiplier%"
Ternary
<condition> ? <true-value> : <false-value>
The condition is evaluated as a comparison (same operators as the compare requirement).
- "[set-variable] mode %var.mode% == buy ? sell : buy"
- "[set-variable] page %var.page% > 0 ? %var.page%-1 : 0"
Example: Tab Navigation
variables:
tab: "weapons"
items:
weapons-tab:
slot: 1
item-stack:
material: DIAMOND_SWORD
name: "<yellow>Weapons"
actions:
LEFT:
- "[set-variable] tab weapons"
- "[refresh]"
armor-tab:
slot: 2
item-stack:
material: DIAMOND_CHESTPLATE
name: "<yellow>Armor"
actions:
LEFT:
- "[set-variable] tab armor"
- "[refresh]"
content-item:
slot: 22
item-stack:
material: STONE
name: "Tab: %var.tab%"
Example: Counter with Bounds
variables:
qty: "1"
items:
plus:
slot: 6
item-stack:
material: LIME_DYE
name: "<green>+"
actions:
LEFT:
- "[set-variable] qty %var.qty% < 64 ? %var.qty%+1 : 64"
- "[refresh-slot] 4"
minus:
slot: 2
item-stack:
material: RED_DYE
name: "<red>-"
actions:
LEFT:
- "[set-variable] qty %var.qty% > 1 ? %var.qty%-1 : 1"
- "[refresh-slot] 4"
display:
slot: 4
item-stack:
material: PAPER
name: "Quantity: <white>%var.qty%"
23 April 2026