Variables and HUD
Keep game state in variables shared by rules and scripts, show them in the HUD, and set a round’s duration and win condition in the game settings.
Variables are a game’s memory: counters, phases, switches, texts. They are read by rule conditions, changed by rule actions, shared with scripts, and can be shown in the HUD next to the score.
Declaring a variable
On the Rules step, Variables section, “+ Variable” adds an entry to doc.vars. Spaces in the name are replaced by underscores. At the start of every game, each variable goes back to its initial value.
namestringrequiredtype'number' | 'boolean' | 'text'requiredvaluenumber | boolean | stringrequiredscope'global' | 'player' | 'object'requiredScope
scope field is saved in the document, but the current single-player runtime keeps one value per name: every variable behaves as global."vars": [
{ "name": "found", "type": "number", "value": 0, "scope": "global" },
{ "name": "dusk", "type": "boolean", "value": false, "scope": "global" }
]Reading and changing
| From | Read | Write |
|---|---|---|
| Rules | Conditions | setVar, addVar |
| Scripts | sandbox.get(name) | sandbox.set(name, value) |
| Events | variable rule, script on('variable') | — |
Rules and scripts share the same variable table. An undeclared variable is created on its first write; without a declaration it just cannot be picked in the studio lists nor shown in the HUD. addVar converts a non-numeric value into a number (0 if unreadable).
Reacting to a change
When a setVar or addVar action actually changes the value, variable rules with that name are evaluated on the next frame. Scripts receive { name, value, previous } for every change, whether it comes from a rule, the game or a script. A write made by sandbox.set does not fire variable rules: react to it in the script.
// A script that reacts to a variable written by a rule
sandbox.on('variable', ({ name, value, previous }) => {
if (name !== 'kills') return
if (value === 5) sandbox.message('Halfway there', 2)
})Full reference: Scripting.
HUD
The HUD is the game overlay: score, time, health bar, the mode’s information lines (laps, waves, coins…), messages and prompts. Each mode provides its own lines; you can add your variables. At the top right, two buttons belong to the player and not to the game: mute, and fullscreen (Esc leaves it).
varsstring[]score, timer, health, lives, coins, messagebooleanDefault truetitlestringMessages and prompts
| Source | Duration |
|---|---|
message action (rule, trigger), sandbox.message | 2.5 s (adjustable from a script) |
hud action | 6 s |
| NPC, sign | 4 s |
Proximity prompt (label) | while the player is in range |
Game settings
The Rules step, Game section, writes doc.settings. Modes keep their base rules (laps, waves, lives); these settings layer on top. The table states plainly what the runtime reads today.
| Field | Effect | Status |
|---|---|---|
duration | Seconds, 0 = unlimited. When it runs out: a “Survived” win if win is survive, otherwise a “Time is up” loss. | active |
win: { type: 'score', value } | Win as soon as the score reaches the value, in every mode. | active |
win: { type: 'survive' } | With duration: lasting to the end wins. | active |
win: { type: 'flags', value } | Capture the flag: captures needed to win (3 by default). | active |
win: collectAll, finish, waves, custom | Describe the mode’s own condition, which applies anyway. | descriptive |
lose | Describes the loss (lives, time, base destroyed); the mode applies it. | descriptive |
players, teams | Groundwork for multiplayer, which does not exist yet. | Coming soon |
respawn, respawnSeconds | Saved, not read: each mode handles its own respawn. | Coming soon |
settings.duration and rules.timeLimit coexist: the latter, set right next to it in the Game section, always means a loss when it runs out, whatever win says."settings": {
"duration": 120,
"win": { "type": "survive" }
}