Map Editor Documentation

Trigger reference

Every trigger event, expression and action: its JSON kind, editor sentence, fields and a minimal valid example.

Page 10 of 22

This page lists every node in the trigger language. It is generated from the same catalog the validator uses, so it cannot fall out of step with the game. The JSON Schema for whole scripts is at /schemas/v1/trigger-script.json.

Every node is a JSON object with a k naming its kind. Unknown properties are errors. Wherever a field takes an expression, you can write a bare number, string or boolean instead: 5 means {"k":"int","v":5}, 1.5 means {"k":"real","v":1.5}, "hi" means {"k":"str","v":"hi"}. A string is always text; to read a variable, use {"k":"var","name":"score"}. Wherever a field takes text, a bare string is shorthand for a one-part template.

Every example below passes validateTriggerScript when placed into this script (events go in events, expressions in conditions, actions in actions):

{
  "version": 1,
  "vars": [
    {
      "name": "score",
      "type": "int"
    },
    {
      "name": "squad",
      "type": "unitGroup"
    },
    {
      "name": "code",
      "type": "string"
    }
  ],
  "regions": [
    {
      "id": "arena",
      "x": 0,
      "y": 0,
      "w": 8,
      "h": 8
    }
  ],
  "functions": [
    {
      "name": "double",
      "params": [
        {
          "name": "n",
          "type": "int"
        }
      ],
      "returns": "int",
      "actions": [
        {
          "k": "return",
          "value": {
            "k": "mul",
            "a": {
              "k": "var",
              "name": "n"
            },
            "b": {
              "k": "int",
              "v": 2
            }
          }
        }
      ]
    }
  ],
  "hashtables": [
    {
      "name": "scores",
      "valueType": "int"
    }
  ],
  "triggers": [
    {
      "id": "main",
      "events": [
        {
          "k": "mapInit"
        }
      ],
      "actions": []
    }
  ]
}

Events

What makes a trigger fire. A trigger fires when any one of its events happens.

Map events

mapInit

Map initialisation. Fires once on the first tick, after every global initialiser.

Editor: the map starts

No fields.

{"k":"mapInit"}

Time events

periodic

Every N ticks. Fires when (tick − offset) is a multiple of everyTicks, from tick offsetTicks on.

Editor: every ‹Interval (ticks)› ticks, phase-shifted by ‹Phase offset›

FieldTypeRequiredDescription
everyTicksint (≥ 1)yesPeriod in ticks (20 = 1 second).
offsetTicksintnoPhase offset in ticks.
{"k":"periodic","everyTicks":1}

atTick

At tick. Fires once on an exact tick.

Editor: at tick ‹Tick›

FieldTypeRequiredDescription
tickint (≥ 0)yesTick number.
{"k":"atTick","tick":1}

timerExpires

Timer expires. Fires when a named timer reaches zero.

Editor: timer ‹Timer› expires

FieldTypeRequiredDescription
timertimerIdyesTimer name.
{"k":"timerExpires","timer":"wave_timer"}

Region events

unitEntersRegion

Unit enters region. Fires for each unit whose tile moved into the region this tick. Units that start inside do not count.

Editor: a unit enters ‹Region› matching ‹Filter›

FieldTypeRequiredDescription
regionregionIdyesRegion id.
filterfilternoOptional unit filter; every set field is ANDed. aliveOnly defaults to true.
{"k":"unitEntersRegion","region":"arena"}

unitLeavesRegion

Unit leaves region. Fires for each unit that left the region this tick — including by dying or being removed (matched against its last snapshot).

Editor: a unit leaves ‹Region› matching ‹Filter›

FieldTypeRequiredDescription
regionregionIdyesRegion id.
filterfilternoOptional unit filter; every set field is ANDed. aliveOnly defaults to true.
{"k":"unitLeavesRegion","region":"arena"}

Unit events

unitDies

Unit dies. Fires when a unit or building dies. The filter is matched against the unit as it was at death (aliveOnly is ignored); event unit = the dead unit, other unit = killer.

Editor: a unit dies matching ‹Filter›

FieldTypeRequiredDescription
filterfilternoOptional unit filter; every set field is ANDed. aliveOnly defaults to true.
{"k":"unitDies"}

unitTrained

Unit trained. Fires when production completes a unit.

Editor: a unit finishes training matching ‹Filter›

FieldTypeRequiredDescription
filterfilternoOptional unit filter; every set field is ANDed. aliveOnly defaults to true.
{"k":"unitTrained"}

buildingComplete

Building completes. Fires when construction finishes.

Editor: a building completes matching ‹Filter›

FieldTypeRequiredDescription
filterfilternoOptional unit filter; every set field is ANDed. aliveOnly defaults to true.
{"k":"buildingComplete"}

unitAttacked

Unit attacked. Fires when a unit takes an attack; event value = damage, other unit = attacker.

Editor: a unit is attacked matching ‹Filter›

FieldTypeRequiredDescription
filterfilternoOptional unit filter; every set field is ANDed. aliveOnly defaults to true.
{"k":"unitAttacked"}

heroLevels

Hero levels up. Fires when a hero gains a level; event value = new level.

Editor: a hero gains a level matching ‹Filter›

FieldTypeRequiredDescription
filterfilternoOptional unit filter; every set field is ANDed. aliveOnly defaults to true.
{"k":"heroLevels"}

Item events

itemPickedUp

Item picked up. Fires when a hero picks up an item.

Editor: an item is picked up — ‹Item›

FieldTypeRequiredDescription
itemIditemIdnoOnly this item id; absent = any.
{"k":"itemPickedUp"}

Player events

playerEliminated

Player eliminated. Fires when a seat is eliminated.

Editor: a player is eliminated — ‹Player›

FieldTypeRequiredDescription
playerplayerNumnoOnly this seat; absent = any.
{"k":"playerEliminated"}

upgradeComplete

Upgrade completes. Fires when research completes; event text = upgrade id.

Editor: an upgrade completes — ‹Upgrade›

FieldTypeRequiredDescription
upgradeIdupgradeIdnoOnly this upgrade; absent = any.
{"k":"upgradeComplete"}

playerChats

Player chats. Fires when a player sends a chat line; event text = the line.

Editor: player ‹Player› sends chat matching "‹Pattern›" (‹Match mode›)

FieldTypeRequiredDescription
patternstringnoText to match; absent = any message.
matchMode'exact' | 'prefix' | 'contains'noHow pattern matches (default exact).
playerplayerNumnoOnly this seat.
{"k":"playerChats","pattern":"-reset","matchMode":"prefix"}

playerKeyPress

Player presses key. Fires when a player presses or releases a key (through lockstep); event text = key, value = 1 down / 0 up.

Editor: player ‹Player› presses ‹Key› (‹Key state›)

FieldTypeRequiredDescription
keykeyNamenoKey name, e.g. 'w', 'Space', 'ArrowUp'.
state'down' | 'up'nodown or up (absent = both).
playerplayerNumnoOnly this seat.
{"k":"playerKeyPress","key":"Space","state":"down"}

Variable events

variableChanges

Variable changes. Fires (in the cascade phase) when a GLOBAL variable is written with a different value.

Editor: variable ‹Variable› changes

FieldTypeRequiredDescription
namevarNameyesGlobal variable name.
{"k":"variableChanges","name":"score"}

UI events

dialogButton

Dialog button clicked. Fires when a player clicks a trigger dialog button (arrives through lockstep); event value = button index.

Editor: a dialog button is clicked on ‹Dialog›, button ‹Button index›

FieldTypeRequiredDescription
dialogIddialogIdnoOnly this dialog.
buttonIndexint (≥ 0)noOnly this 0-based button.
{"k":"dialogButton"}

Combat events

projectileHits

Projectile hits. Fires when a projectile strikes its target or a bomb detonates. Event unit = target, other unit = shooter, value = damage.

Editor: a projectile hits matching ‹Tag›

FieldTypeRequiredDescription
tagstringnoMatch the shooter's authored tag, the spell id, the shooter's unit type or the projectile type.
{"k":"projectileHits"}

Custom events

custom

Custom event. Fires when raiseEvent raises this name (same tick, capped cascade).

Editor: custom event ‹Event name› is raised

FieldTypeRequiredDescription
nameeventNameyesEvent name.
{"k":"custom","name":"boss_down"}

Cutscene events

cutsceneFinished

Cutscene finished. Fires when a cutscene ends. Event value: 0 played out, 1 skipped by every human viewer, 2 replaced by another scene, 3 stopped by a trigger.

Editor: cutscene ‹Scene› finishes

FieldTypeRequiredDescription
sceneIdsceneIdnoOnly this scene.
{"k":"cutsceneFinished"}

Conditions and expressions

Values. A trigger condition is any expression; the trigger runs only when all of its conditions are true.

Literal expressions

int

Integer — returns int. An integer literal. Non-integers are truncated.

Editor: ‹Value›

FieldTypeRequiredDescription
vnumberyesThe value.
{"k":"int","v":1}

real

Real number — returns real. A real-number literal.

Editor: ‹Value›

FieldTypeRequiredDescription
vnumberyesThe value.
{"k":"real","v":1}

bool

Boolean — returns bool. true or false.

Editor: ‹Value›

FieldTypeRequiredDescription
vboolyesThe value.
{"k":"bool","v":true}

str

Text — returns string. A string literal.

Editor: "‹Value›"

FieldTypeRequiredDescription
vstringyesThe value.
{"k":"str","v":"text"}

Geometry expressions

point

Point — returns point. A tile coordinate built from two numbers.

Editor: (‹Tile X›, ‹Tile Y›)

FieldTypeRequiredDescription
xexpr (number)yesTile X.
yexpr (number)yesTile Y.
{"k":"point","x":1,"y":1}

distance

Distance — returns real. Euclidean tile distance; either side may be a unit or a point.

Editor: distance from ‹From› to ‹To›

FieldTypeRequiredDescription
aexpr (any)yesLeft operand.
bexpr (any)yesRight operand.
{"k":"distance","a":1,"b":1}

pointX

Point X — returns number. X of a point.

Editor: X of ‹Point›

FieldTypeRequiredDescription
pexpr (point)yesThe point.
{"k":"pointX","p":{"k":"regionCenter","region":"arena"}}

pointY

Point Y — returns number. Y of a point.

Editor: Y of ‹Point›

FieldTypeRequiredDescription
pexpr (point)yesThe point.
{"k":"pointY","p":{"k":"regionCenter","region":"arena"}}

regionCenter

Region centre — returns point. Integer centre tile of a region.

Editor: centre of ‹Region›

FieldTypeRequiredDescription
regionregionIdyesRegion id.
{"k":"regionCenter","region":"arena"}

randomPointInRegion

Random point in region — returns point. Random tile inside the region (always two PRNG draws).

Editor: a random point in ‹Region›

FieldTypeRequiredDescription
regionregionIdyesRegion id.
{"k":"randomPointInRegion","region":"arena"}

pointInRegion

Point in region — returns bool. True when the point (or unit) lies inside the region.

Editor: ‹Point› is inside ‹Region›

FieldTypeRequiredDescription
pexpr (point)yesPoint or unit.
regionregionIdyesRegion id.
{"k":"pointInRegion","p":{"k":"regionCenter","region":"arena"},"region":"arena"}

offsetPoint

Offset point — returns point. A point moved by (dx, dy) tiles.

Editor: ‹Point› offset by (‹Tiles X›, ‹Tiles Y›)

FieldTypeRequiredDescription
pexpr (point)yesPoint or unit.
dxexpr (number)yesTiles X.
dyexpr (number)yesTiles Y.
{"k":"offsetPoint","p":{"k":"regionCenter","region":"arena"},"dx":1,"dy":1}

Unit expressions

nullUnit

No unit — returns unit. Entity id 0. Every property of it reads as a zero value.

Editor: no unit

No fields.

{"k":"nullUnit"}

unitProp

Unit property — returns any. Read a property of a unit. A unit that died THIS tick answers from its death snapshot; otherwise a missing unit gives the zero value.

Editor: ‹Property› of ‹Unit›

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
prop'hp' | 'maxHp' | 'hpPercent' | 'mana' | 'maxMana' | 'x' | 'y' | 'level' | 'xp' | 'kills' | 'owner' | 'alive' | 'isHero' | 'isBuilding' | 'isFlying' | 'typeId'yesProperty to read.
{"k":"unitProp","unit":{"k":"eventUnit"},"prop":"hp"}

unitPoint

Unit position — returns point. Tile position of a unit.

Editor: position of ‹Unit›

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
{"k":"unitPoint","unit":{"k":"eventUnit"}}

entityByAid

Unit by authored id — returns unit. The placed entity carrying this authored id, or no unit.

Editor: the unit with authored id ‹Authored id›

FieldTypeRequiredDescription
aidaidyesAuthored id from the entity inspector.
{"k":"entityByAid","aid":"north_gate"}

Variable expressions

var

Variable — returns any. Read a variable: a trigger/function local, a function parameter, a loop variable or a global (resolved in that order).

Editor: ‹Variable›[‹Index›]

FieldTypeRequiredDescription
namevarNameyesVariable name.
indexexpr (int)noElement index for an array variable. Out-of-range reads yield the zero value.
{"k":"var","name":"score"}

Arithmetic expressions

add

A + B — returns number. Sum. If either side is a string the two are concatenated.

Editor: ‹A› + ‹B›

FieldTypeRequiredDescription
aexpr (any)yesLeft operand.
bexpr (any)yesRight operand.
{"k":"add","a":1,"b":1}

sub

A − B — returns number. Difference.

Editor: ‹A› − ‹B›

FieldTypeRequiredDescription
aexpr (number)yesLeft operand.
bexpr (number)yesRight operand.
{"k":"sub","a":1,"b":1}

mul

A × B — returns number. Product.

Editor: ‹A› × ‹B›

FieldTypeRequiredDescription
aexpr (number)yesLeft operand.
bexpr (number)yesRight operand.
{"k":"mul","a":1,"b":1}

div

A ÷ B — returns number. Quotient. Division by zero yields 0 — never Infinity or NaN.

Editor: ‹A› ÷ ‹B›

FieldTypeRequiredDescription
aexpr (number)yesLeft operand.
bexpr (number)yesRight operand.
{"k":"div","a":1,"b":1}

mod

A mod B — returns number. Remainder (sign of A). Modulo by zero yields 0.

Editor: ‹A› mod ‹B›

FieldTypeRequiredDescription
aexpr (number)yesLeft operand.
bexpr (number)yesRight operand.
{"k":"mod","a":1,"b":1}

neg

Negate — returns number. Arithmetic negation.

Editor: −‹A›

FieldTypeRequiredDescription
aexpr (number)yesLeft operand.
{"k":"neg","a":1}

abs

Absolute value — returns number. Absolute value.

Editor: |‹A›|

FieldTypeRequiredDescription
aexpr (number)yesLeft operand.
{"k":"abs","a":1}

min

Minimum — returns number. The smaller of A and B.

Editor: min(‹A›, ‹B›)

FieldTypeRequiredDescription
aexpr (number)yesLeft operand.
bexpr (number)yesRight operand.
{"k":"min","a":1,"b":1}

max

Maximum — returns number. The larger of A and B.

Editor: max(‹A›, ‹B›)

FieldTypeRequiredDescription
aexpr (number)yesLeft operand.
bexpr (number)yesRight operand.
{"k":"max","a":1,"b":1}

clamp

Clamp — returns number. A limited to [lo, hi]; reversed bounds are swapped.

Editor: clamp(‹A›, ‹Minimum›, ‹Maximum›)

FieldTypeRequiredDescription
aexpr (number)yesValue to clamp.
loexpr (number)yesLower bound.
hiexpr (number)yesUpper bound.
{"k":"clamp","a":{"k":"var","name":"score"},"lo":0,"hi":100}

trunc

Truncate — returns int. Real to integer toward zero (Math.trunc) — the one real→int rule in the language.

Editor: trunc(‹A›)

FieldTypeRequiredDescription
aexpr (real)yesLeft operand.
{"k":"trunc","a":1.5}

Comparison expressions

eq

A = B — returns bool. Equality. Strings compare by code unit; groups element-wise; points by x then y.

Editor: ‹A› = ‹B›

FieldTypeRequiredDescription
aexpr (any)yesLeft operand.
bexpr (any)yesRight operand.
{"k":"eq","a":1,"b":1}

ne

A ≠ B — returns bool. Inequality.

Editor: ‹A› ≠ ‹B›

FieldTypeRequiredDescription
aexpr (any)yesLeft operand.
bexpr (any)yesRight operand.
{"k":"ne","a":1,"b":1}

lt

A < B — returns bool. Less than.

Editor: ‹A› < ‹B›

FieldTypeRequiredDescription
aexpr (any)yesLeft operand.
bexpr (any)yesRight operand.
{"k":"lt","a":1,"b":1}

le

A ≤ B — returns bool. Less than or equal.

Editor: ‹A› ≤ ‹B›

FieldTypeRequiredDescription
aexpr (any)yesLeft operand.
bexpr (any)yesRight operand.
{"k":"le","a":1,"b":1}

gt

A > B — returns bool. Greater than.

Editor: ‹A› > ‹B›

FieldTypeRequiredDescription
aexpr (any)yesLeft operand.
bexpr (any)yesRight operand.
{"k":"gt","a":1,"b":1}

ge

A ≥ B — returns bool. Greater than or equal.

Editor: ‹A› ≥ ‹B›

FieldTypeRequiredDescription
aexpr (any)yesLeft operand.
bexpr (any)yesRight operand.
{"k":"ge","a":1,"b":1}

Logic expressions

and

A and B — returns bool. Logical AND. Short-circuits: B is not evaluated when A is false.

Editor: ‹A› and ‹B›

FieldTypeRequiredDescription
aexpr (bool)yesLeft operand.
bexpr (bool)yesRight operand.
{"k":"and","a":true,"b":true}

or

A or B — returns bool. Logical OR. Short-circuits: B is not evaluated when A is true.

Editor: ‹A› or ‹B›

FieldTypeRequiredDescription
aexpr (bool)yesLeft operand.
bexpr (bool)yesRight operand.
{"k":"or","a":true,"b":true}

not

Not A — returns bool. Logical negation.

Editor: not ‹A›

FieldTypeRequiredDescription
aexpr (bool)yesLeft operand.
{"k":"not","a":true}

Time expressions

tick

Game tick — returns int. The current simulation tick (20 per second) — the only clock in the language.

Editor: the game tick

No fields.

{"k":"tick"}

rand

Random integer — returns int. Inclusive random integer from the synchronised game PRNG. Always consumes exactly one draw.

Editor: random ‹Minimum› to ‹Maximum›

FieldTypeRequiredDescription
minexpr (int)yesLower bound (inclusive).
maxexpr (int)yesUpper bound (inclusive).
{"k":"rand","min":1,"max":6}

timerRemaining

Timer ticks left — returns int. Ticks until the timer expires (0 if not running).

Editor: ticks left on ‹Timer›

FieldTypeRequiredDescription
timertimerIdyesTimer name.
{"k":"timerRemaining","timer":"wave_timer"}

timerRunning

Timer is running — returns bool. True while the timer runs and is not paused.

Editor: ‹Timer› is running

FieldTypeRequiredDescription
timertimerIdyesTimer name.
{"k":"timerRunning","timer":"wave_timer"}

Player expressions

playerResource

Player's resource — returns int. Current stock of one resource.

Editor: ‹Player›'s ‹Resource›

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
resource'gold' | 'lumber' | 'stone' | 'oil'yesResource kind.
{"k":"playerResource","player":0,"resource":"gold"}

playerPop

Player's population — returns int. Population in use.

Editor: ‹Player›'s population

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
{"k":"playerPop","player":0}

playerMaxPop

Player's population cap — returns int. Population cap.

Editor: ‹Player›'s population cap

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
{"k":"playerMaxPop","player":0}

playerAlive

Player is alive — returns bool. True while the seat has not been eliminated or defeated.

Editor: ‹Player› is still alive

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
{"k":"playerAlive","player":0}

playerTeam

Player's team — returns int. Team id of the seat, or -1.

Editor: ‹Player›'s team

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
{"k":"playerTeam","player":0}

playerHasUpgrade

Player has upgrade — returns bool. True once the seat has completed the research.

Editor: ‹Player› has researched ‹Upgrade›

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
upgradeIdupgradeIdyesUpgrade id.
{"k":"playerHasUpgrade","player":0,"upgradeId":"dwarf_forged_weapons_1"}

isAllied

Players are allied — returns bool. True when seats A and B are on the same team.

Editor: ‹A› is allied with ‹B›

FieldTypeRequiredDescription
aexpr (player)yesLeft operand.
bexpr (player)yesRight operand.
{"k":"isAllied","a":0,"b":0}

isEnemy

Players are enemies — returns bool. True when seats A and B are not allied.

Editor: ‹A› is an enemy of ‹B›

FieldTypeRequiredDescription
aexpr (player)yesLeft operand.
bexpr (player)yesRight operand.
{"k":"isEnemy","a":0,"b":0}

Group expressions

unitsInRegion

Units in region — returns unitGroup. Sorted group of units whose tile is inside the region.

Editor: units in ‹Region› matching ‹Filter›

FieldTypeRequiredDescription
regionregionIdyesRegion id.
filterfilternoOptional unit filter; every set field is ANDed. aliveOnly defaults to true.
{"k":"unitsInRegion","region":"arena"}

unitsWithTag

Units with tag — returns unitGroup. Sorted group of placed entities sharing an authored tag.

Editor: units tagged ‹Tag› matching ‹Filter›

FieldTypeRequiredDescription
tagtagyesAuthored tag.
filterfilternoOptional unit filter; every set field is ANDed. aliveOnly defaults to true.
{"k":"unitsWithTag","tag":"wave"}

unitsOfPlayer

Units of player — returns unitGroup. Sorted group of units owned by the seat.

Editor: units owned by ‹Player› matching ‹Filter›

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
filterfilternoOptional unit filter; every set field is ANDed. aliveOnly defaults to true.
{"k":"unitsOfPlayer","player":0}

unitsOfType

Units of type — returns unitGroup. Sorted group of units or buildings of one type id.

Editor: units of type ‹Unit type› matching ‹Filter›

FieldTypeRequiredDescription
unitTypeIdunitTypeIdyesUnit or building type id.
filterfilternoOptional unit filter; every set field is ANDed. aliveOnly defaults to true.
{"k":"unitsOfType","unitTypeId":"dwarf_ironguard"}

groupCount

Group size — returns int. Number of units in a group.

Editor: number of units in ‹Unit group›

FieldTypeRequiredDescription
groupexpr (unitGroup)yesThe group.
{"k":"groupCount","group":{"k":"unitsInRegion","region":"arena"}}

groupAt

Unit at index — returns unit. 0-based element of the sorted group; out of range gives no unit.

Editor: unit ‹Index› of ‹Unit group›

FieldTypeRequiredDescription
groupexpr (unitGroup)yesThe group.
indexexpr (int)yes0-based index.
{"k":"groupAt","group":{"k":"unitsInRegion","region":"arena"},"index":1}

groupRandom

Random unit of group — returns unit. A random member (one PRNG draw, even for an empty group).

Editor: a random unit in ‹Unit group›

FieldTypeRequiredDescription
groupexpr (unitGroup)yesThe group.
{"k":"groupRandom","group":{"k":"unitsInRegion","region":"arena"}}

groupUnion

Group union — returns unitGroup. Members of A or B.

Editor: ‹A› together with ‹B›

FieldTypeRequiredDescription
aexpr (unitGroup)yesLeft operand.
bexpr (unitGroup)yesRight operand.
{"k":"groupUnion","a":{"k":"unitsInRegion","region":"arena"},"b":{"k":"unitsInRegion","region":"arena"}}

groupDiff

Group difference — returns unitGroup. Members of A not in B.

Editor: ‹A› except ‹B›

FieldTypeRequiredDescription
aexpr (unitGroup)yesLeft operand.
bexpr (unitGroup)yesRight operand.
{"k":"groupDiff","a":{"k":"unitsInRegion","region":"arena"},"b":{"k":"unitsInRegion","region":"arena"}}

groupHas

Group contains — returns bool. True when the unit is in the group.

Editor: ‹Unit group› contains ‹Unit›

FieldTypeRequiredDescription
groupexpr (unitGroup)yesThe group.
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
{"k":"groupHas","group":{"k":"unitsInRegion","region":"arena"},"unit":{"k":"eventUnit"}}

groupEmpty

Empty group — returns unitGroup. A group with no units.

Editor: an empty group

No fields.

{"k":"groupEmpty"}

Event expressions

eventUnit

Triggering unit — returns unit. The unit the event is about (entered, died, trained, was attacked…). No unit when the event has none.

Editor: the triggering unit

No fields.

{"k":"eventUnit"}

eventOtherUnit

Other unit — returns unit. The killer for unitDies, the attacker for unitAttacked, the shooter for projectileHits.

Editor: the other unit

No fields.

{"k":"eventOtherUnit"}

eventPlayer

Triggering player — returns player. The seat the event is about, or -1.

Editor: the triggering player

No fields.

{"k":"eventPlayer"}

eventValue

Event value — returns number. Numeric payload: dialog button index, hero level, damage, raised value.

Editor: the event value

No fields.

{"k":"eventValue"}

eventString

Event text — returns string. String payload: upgrade id, item id, chat text, custom event name.

Editor: the event text

No fields.

{"k":"eventString"}

UI expressions

counter

Counter value — returns number. Current value of an on-screen counter.

Editor: counter ‹Counter›

FieldTypeRequiredDescription
idcounterIdyesCounter id.
{"k":"counter","id":"lives"}

Trigger expressions

triggerFireCount

Trigger fire count — returns int. How many times a trigger has fired.

Editor: times ‹Trigger› has fired

FieldTypeRequiredDescription
triggerIdtriggerIdyesTrigger id.
{"k":"triggerFireCount","triggerId":"main"}

Text expressions

concat

Concatenate — returns string. A joined with B as strings.

Editor: ‹A› joined with ‹B›

FieldTypeRequiredDescription
aexpr (string)yesLeft operand.
bexpr (string)yesRight operand.
{"k":"concat","a":"text","b":"text"}

toStr

To text — returns string. Value as text. Non-integers print with decimals places (default 2).

Editor: ‹Value› as text to ‹Decimal places› dp

FieldTypeRequiredDescription
aexpr (any)yesLeft operand.
decimalsint (≥ 0, ≤ 6)noFixed decimal places, 0..6.
{"k":"toStr","a":1}

subStr

Substring — returns string. 0-based slice; out-of-range start gives empty text.

Editor: substring of ‹String› from ‹Start index› length ‹Length›

FieldTypeRequiredDescription
textexpr (string)yesSource text.
startexpr (int)yesStart index.
lengthexpr (int)noMaximum length; absent = to the end.
{"k":"subStr","text":"Hello world","start":0,"length":5}

strLen

Text length — returns int. Length in UTF-16 code units.

Editor: length of ‹String›

FieldTypeRequiredDescription
textexpr (string)yesThe text.
{"k":"strLen","text":"text"}

hashString

Hash text — returns int. Deterministic 32-bit FNV-1a hash.

Editor: hash of ‹String›

FieldTypeRequiredDescription
textexpr (string)yesThe text.
{"k":"hashString","text":"text"}

Physics expressions

unitVelocity

Unit velocity — returns real. Kinematic velocity component or speed (tiles/tick); 0 without kinematics.

Editor: ‹Axis› velocity of ‹Unit›

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
axis'x' | 'y' | 'speed'yesComponent to read.
{"k":"unitVelocity","unit":{"k":"eventUnit"},"axis":"x"}

Save codes expressions

verifySaveCode

Read save code — returns any. Validate a save code for this map. With field, returns that field (or 0); without, returns 1 for a valid code and 0 otherwise.

Editor: save code ‹Code› field ‹Field› (valid?)

FieldTypeRequiredDescription
codeexpr (string)yesThe code text.
fieldstringnoField to extract; playerId returns the issuing seat.
{"k":"verifySaveCode","code":{"k":"var","name":"code"}}

Function expressions

call

Call function — returns any. Call a user-defined function that declares a return type and yield its return value. Arguments are evaluated left to right and coerced to the parameter types. Recursion past the depth cap yields the zero value.

Editor: ‹Function›(‹Arguments›)

FieldTypeRequiredDescription
fnfunctionNameyesFunction name.
argsexprListnoArguments, one per parameter, in order.
{"k":"call","fn":"double","args":[2]}

Hashtable expressions

hashtableGet

Hashtable value — returns any. Value stored under (key1, key2), or the zero value of the table type. Keys are integers or strings.

Editor: ‹Hashtable›[‹Parent key›][‹Child key›]

FieldTypeRequiredDescription
tablehashtableNameyesHashtable name.
key1expr (any)yesParent key (int or string).
key2expr (any)yesChild key (int or string).
{"k":"hashtableGet","table":"scores","key1":1,"key2":1}

hashtableHas

Hashtable has key — returns bool. True when a value is stored under (key1, key2).

Editor: ‹Hashtable› has [‹Parent key›][‹Child key›]

FieldTypeRequiredDescription
tablehashtableNameyesHashtable name.
key1expr (any)yesParent key.
key2expr (any)yesChild key.
{"k":"hashtableHas","table":"scores","key1":1,"key2":1}

hashtableCount

Hashtable size — returns int. Number of entries in the table, or under one parent key when key1 is set.

Editor: number of entries in ‹Hashtable› under ‹Parent key›

FieldTypeRequiredDescription
tablehashtableNameyesHashtable name.
key1expr (any)noParent key to count children of.
{"k":"hashtableCount","table":"scores"}

Actions

What a trigger does, run top to bottom.

Control flow actions

if

If / then / else. Run then when cond is true, else else.

Editor: if ‹Condition›

FieldTypeRequiredDescription
condexpr (bool)yesCondition.
thenactionsyesActions when true.
elseactionsnoActions when false.
{"k":"if","cond":true,"then":[]}

while

While. Repeat the body while cond holds, at most maxIterations (hard cap 10000) times per run.

Editor: while ‹Condition›

FieldTypeRequiredDescription
condexpr (bool)yesLoop condition, checked before each iteration.
bodyactionsyesLoop body.
maxIterationsint (≥ 1, ≤ 10000)noIteration cap (≤ 10000).
{"k":"while","cond":true,"body":[]}

forEachUnit

For each unit. Run the body once per unit of a group (snapshotted and sorted before the first iteration).

Editor: for each unit ‹Loop variable› in ‹Unit group›

FieldTypeRequiredDescription
groupexpr (unitGroup)yesGroup to iterate.
varNameloopVaryesLoop variable receiving each unit id; an undeclared name becomes a local.
bodyactionsyesLoop body.
{"k":"forEachUnit","group":{"k":"unitsInRegion","region":"arena"},"varName":"u","body":[]}

forEachInt

For each integer. Run the body for each integer from..to inclusive (at most 10000).

Editor: for ‹Loop variable› from ‹From› to ‹To›

FieldTypeRequiredDescription
varNameloopVaryesLoop variable; an undeclared name becomes a local.
fromexpr (int)yesFirst value.
toexpr (int)yesLast value (inclusive).
bodyactionsyesLoop body.
{"k":"forEachInt","varName":"i","from":1,"to":1,"body":[]}

wait

Wait. Suspend this trigger for N ticks (min 1) and resume at the next action. Locals and loop state survive, including across save/load. Not allowed inside functions.

Editor: wait ‹Ticks› ticks

FieldTypeRequiredDescription
ticksexpr (int)yesTicks to wait.
{"k":"wait","ticks":1}

raiseEvent

Raise custom event. Fire the custom event of this name later in the same tick.

Editor: raise custom event ‹Event name› with value ‹Value› and text ‹Text›

FieldTypeRequiredDescription
nameeventNameyesEvent name.
valueexpr (number)noEvent value payload.
textexpr (string)noEvent text payload (default: the name).
{"k":"raiseEvent","name":"boss_down"}

comment

Comment. Does nothing; documents the script.

Editor: // ‹Comment›

FieldTypeRequiredDescription
textstringyesComment text.
{"k":"comment","text":"text"}

Variable actions

setVar

Set variable. Write a variable (local, parameter, loop or global). Writing a global with a new value raises variableChanges.

Editor: set ‹Variable›[‹Index›] to ‹Value›

FieldTypeRequiredDescription
namevarNameyesVariable name.
indexexpr (int)noElement index for an array.
valueexpr (any)yesNew value (coerced to the variable type).
{"k":"setVar","name":"score","value":1}

addVar

Add to variable. Add a number to a numeric variable.

Editor: add ‹Amount› to ‹Variable›[‹Index›]

FieldTypeRequiredDescription
namevarNameyesVariable name.
indexexpr (int)noElement index for an array.
deltaexpr (number)yesAmount to add.
{"k":"addVar","name":"score","delta":1}

Trigger actions

enableTrigger

Enable/disable trigger. Turn a trigger on or off.

Editor: set trigger ‹Trigger› enabled to ‹Enabled›

FieldTypeRequiredDescription
triggerIdtriggerIdyesTrigger id.
onboolyesEnabled.
{"k":"enableTrigger","triggerId":"main","on":true}

runTrigger

Run trigger. Run another trigger's actions inline in this event context.

Editor: run trigger ‹Trigger› (checking its conditions: ‹Check conditions›)

FieldTypeRequiredDescription
triggerIdtriggerIdyesTrigger id.
checkConditionsboolnoEvaluate its conditions first (and count it as fired).
{"k":"runTrigger","triggerId":"main"}

stopTrigger

Stop trigger. Abandon the rest of this trigger. Not allowed inside functions (use return).

Editor: stop running this trigger

No fields.

{"k":"stopTrigger"}

Function actions

callFunction

Call function. Call a user-defined function as a statement, optionally storing its return value.

Editor: call ‹Function›(‹Arguments›) and store the result in ‹Store result in›[‹Index›]

FieldTypeRequiredDescription
fnfunctionNameyesFunction name.
argsexprListnoArguments, one per parameter, in order.
intoVarvarNamenoVariable receiving the return value (function must declare returns).
intoIndexexpr (int)noElement index when intoVar is an array.
{"k":"callFunction","fn":"double","args":[2]}

return

Return. Leave the current function, yielding value. At trigger level (no value allowed) it stops the trigger.

Editor: return ‹Value›

FieldTypeRequiredDescription
valueexpr (any)noReturn value (functions with a return type).
{"k":"return"}

Hashtable actions

hashtableSet

Hashtable set. Store a value under (key1, key2). New keys past the table cap are dropped.

Editor: set ‹Hashtable›[‹Parent key›][‹Child key›] to ‹Value›

FieldTypeRequiredDescription
tablehashtableNameyesHashtable name.
key1expr (any)yesParent key (int or string).
key2expr (any)yesChild key (int or string).
valueexpr (any)yesValue (coerced to the table type).
{"k":"hashtableSet","table":"scores","key1":1,"key2":1,"value":1}

hashtableRemove

Hashtable remove. Remove the value under (key1, key2).

Editor: remove ‹Hashtable›[‹Parent key›][‹Child key›]

FieldTypeRequiredDescription
tablehashtableNameyesHashtable name.
key1expr (any)yesParent key.
key2expr (any)yesChild key.
{"k":"hashtableRemove","table":"scores","key1":1,"key2":1}

hashtableClear

Hashtable clear. Remove every entry, or only those under key1.

Editor: clear ‹Hashtable› under ‹Parent key›

FieldTypeRequiredDescription
tablehashtableNameyesHashtable name.
key1expr (any)noParent key to flush; absent = whole table.
{"k":"hashtableClear","table":"scores"}

Units actions

createUnits

Create units. Spawn N units (max 500) for a player at a point.

Editor: create ‹Count› × ‹Unit type› for ‹Player› at ‹At point› facing ‹Facing (degrees)›° and store them in ‹Store in›

FieldTypeRequiredDescription
unitTypeIdunitTypeIdyesUnit type id (base game or a defOverrides clone).
countexpr (int)yesHow many.
playerexpr (player)yesSeat id (0-based) of the player.
atexpr (point)yesSpawn tile.
facingexpr (int)noFacing in degrees.
intoVarvarNamenounitGroup variable receiving the created ids.
{"k":"createUnits","unitTypeId":"dwarf_ironguard","count":1,"player":0,"at":{"k":"regionCenter","region":"arena"}}

removeUnit

Remove unit. Remove a unit outright — no death, corpse or bounty.

Editor: remove ‹Unit› from the game

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
{"k":"removeUnit","unit":{"k":"eventUnit"}}

killUnit

Kill unit. Kill a unit through the normal death path.

Editor: kill ‹Unit›

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
{"k":"killUnit","unit":{"k":"eventUnit"}}

setUnitHp

Set unit HP. Set HP (clamped to 0..max).

Editor: set HP of ‹Unit› to ‹Value› (as a percentage: ‹Value is a percentage›)

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
valueexpr (number)yesHP or percentage.
percentboolnoTreat value as a percentage of max HP.
{"k":"setUnitHp","unit":{"k":"eventUnit"},"value":1}

setUnitMana

Set unit mana. Set mana (clamped).

Editor: set mana of ‹Unit› to ‹Value›

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
valueexpr (number)yesMana.
{"k":"setUnitMana","unit":{"k":"eventUnit"},"value":1}

setUnitOwner

Change owner. Give a unit to another seat.

Editor: give ‹Unit› to ‹Player›

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
playerexpr (player)yesSeat id (0-based) of the player.
{"k":"setUnitOwner","unit":{"k":"eventUnit"},"player":0}

setUnitInvulnerable

Set invulnerable. Toggle invulnerability.

Editor: set ‹Unit› invulnerable to ‹Invulnerable›

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
onboolyesInvulnerable.
{"k":"setUnitInvulnerable","unit":{"k":"eventUnit"},"on":true}

moveUnit

Move unit instantly. Teleport a unit to a tile.

Editor: move ‹Unit› to ‹To point›

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
toexpr (point)yesDestination tile.
{"k":"moveUnit","unit":{"k":"eventUnit"},"to":{"k":"regionCenter","region":"arena"}}

Group actions

addUnitToGroup

Add unit to group. Add a unit to a unitGroup variable.

Editor: add ‹Unit› to ‹Group variable›

FieldTypeRequiredDescription
varNamevarNameyesunitGroup variable.
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
{"k":"addUnitToGroup","varName":"squad","unit":{"k":"eventUnit"}}

removeUnitFromGroup

Remove unit from group. Remove a unit from a unitGroup variable.

Editor: remove ‹Unit› from ‹Group variable›

FieldTypeRequiredDescription
varNamevarNameyesunitGroup variable.
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
{"k":"removeUnitFromGroup","varName":"squad","unit":{"k":"eventUnit"}}

clearGroup

Clear group. Empty a unitGroup variable.

Editor: clear ‹Group variable›

FieldTypeRequiredDescription
varNamevarNameyesunitGroup variable.
{"k":"clearGroup","varName":"squad"}

Orders actions

order

Order units. Issue an order to a group, applied inside the tick (never through lockstep).

Editor: order ‹Units› to ‹Order› at ‹Target point› targeting ‹Target unit› (queued: ‹Queue behind current order›)

FieldTypeRequiredDescription
unitsexpr (unitGroup)yesUnits to order (a single unit also works).
order'move' | 'attack_move' | 'attack' | 'stop' | 'hold' | 'patrol' | 'follow'yesOrder kind.
toexpr (point)noTarget tile for move / attack_move / patrol.
targetexpr (unit)noTarget unit for attack / follow.
queueboolnoQueue after current orders.
{"k":"order","units":{"k":"unitsInRegion","region":"arena"},"order":"attack_move","to":{"k":"regionCenter","region":"arena"}}

Economy actions

setResource

Set resource. Set a player's resource stock (rounded, ≥ 0).

Editor: set ‹Player›'s ‹Resource› to ‹Value›

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
resource'gold' | 'lumber' | 'stone' | 'oil'yesResource kind.
valueexpr (int)yesNew amount.
{"k":"setResource","player":0,"resource":"gold","value":1}

addResource

Add resource. Add to a player's resource stock (rounded, ≥ 0).

Editor: give ‹Player› ‹Amount› ‹Resource›

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
resource'gold' | 'lumber' | 'stone' | 'oil'yesResource kind.
deltaexpr (int)yesAmount to add (negative subtracts).
{"k":"addResource","player":0,"resource":"gold","delta":1}

setAlliance

Set alliance. Ally B to A's team, or put B back on its own team.

Editor: set ‹A› and ‹B› allied to ‹Allied›

FieldTypeRequiredDescription
aexpr (player)yesLeft operand.
bexpr (player)yesRight operand.
alliedboolyesAllied.
{"k":"setAlliance","a":0,"b":0,"allied":true}

setBuildableRegion

Restrict building. Limit where a seat may build: a list of regions, [] for nowhere, or null to restore the default.

Editor: restrict building for ‹Player› to ‹Regions›

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
regionsregionId[] | nullyesRegion ids, or null.
{"k":"setBuildableRegion","player":0,"regions":["arena"]}

Outcome actions

victory

Victory. Declare a seat victorious.

Editor: declare victory for ‹Player›

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
{"k":"victory","player":0}

defeat

Defeat. Declare a seat defeated.

Editor: declare defeat for ‹Player›

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
{"k":"defeat","player":0}

Timers actions

startTimer

Start timer. Start (or restart) a named timer.

Editor: start timer ‹Timer› for ‹Ticks› ticks (repeating: ‹Repeating›)

FieldTypeRequiredDescription
timertimerIdyesTimer name.
ticksexpr (int)yesDuration in ticks (≥ 1).
periodicboolnoRestart on expiry.
{"k":"startTimer","timer":"wave_timer","ticks":1}

pauseTimer

Pause timer. Pause a timer.

Editor: pause timer ‹Timer›

FieldTypeRequiredDescription
timertimerIdyesTimer name.
{"k":"pauseTimer","timer":"wave_timer"}

resumeTimer

Resume timer. Resume a paused timer.

Editor: resume timer ‹Timer›

FieldTypeRequiredDescription
timertimerIdyesTimer name.
{"k":"resumeTimer","timer":"wave_timer"}

stopTimer

Stop timer. Stop and delete a timer.

Editor: stop timer ‹Timer›

FieldTypeRequiredDescription
timertimerIdyesTimer name.
{"k":"stopTimer","timer":"wave_timer"}

UI actions

showText

Show text. Show a text banner, resolved in the sim.

Editor: show ‹Text› to ‹Shown to› for ‹Duration (ticks)› ticks

FieldTypeRequiredDescription
playersnumber[] | nullyesSeats that see this, or null for everyone.
texttextyesText template (a bare string is accepted).
durationTicksint (≥ 1)noDisplay time in ticks (default 100).
{"k":"showText","players":null,"text":"Hello"}

clearText

Clear text. Clear banners for these seats (null = all).

Editor: clear on-screen text for ‹Shown to›

FieldTypeRequiredDescription
playersnumber[] | nullyesSeats that see this, or null for everyone.
{"k":"clearText","players":null}

setCounter

Set counter. Create or update an on-screen counter.

Editor: set counter ‹Counter id› — ‹Label› — to ‹Value› for ‹Shown to› at position ‹Sort position›

FieldTypeRequiredDescription
idcounterIdyesCounter id.
labeltextyesLabel template.
valueexpr (number)yesValue.
playersnumber[] | nullnoSeats that see this, or null/absent for everyone.
orderintnoSort position.
{"k":"setCounter","id":"lives","label":"Hello","value":1}

removeCounter

Remove counter. Remove a counter.

Editor: remove counter ‹Counter id›

FieldTypeRequiredDescription
idcounterIdyesCounter id.
{"k":"removeCounter","id":"lives"}

setLeaderboardTitle

Leaderboard title. Set the leaderboard title ("" hides it).

Editor: set the leaderboard title to ‹Title› for ‹Shown to›

FieldTypeRequiredDescription
titletextyesTitle template.
playersnumber[] | nullnoSeats that see this, or null/absent for everyone.
{"k":"setLeaderboardTitle","title":"Hello"}

setLeaderboardRow

Leaderboard row. Create or update a leaderboard row.

Editor: set leaderboard row ‹Row id› — ‹Label› — to ‹Value› at position ‹Sort position›

FieldTypeRequiredDescription
rowIdrowIdyesRow id.
labeltextyesLabel template.
valueexpr (number)yesValue.
orderintnoSort position.
{"k":"setLeaderboardRow","rowId":"p1","label":"Hello","value":1}

removeLeaderboardRow

Remove leaderboard row. Remove a leaderboard row.

Editor: remove leaderboard row ‹Row id›

FieldTypeRequiredDescription
rowIdrowIdyesRow id.
{"k":"removeLeaderboardRow","rowId":"p1"}

clearLeaderboard

Clear leaderboard. Remove every row and the title.

Editor: clear the leaderboard

No fields.

{"k":"clearLeaderboard"}

showDialog

Show dialog. Open a modal dialog; clicks fire dialogButton.

Editor: show dialog ‹Dialog id› titled ‹Title›, saying ‹Body›, with buttons ‹Buttons›, to ‹Shown to›

FieldTypeRequiredDescription
dialogIddialogIdyesDialog id.
titletextyesTitle template.
bodytextyesBody template.
buttonstextListyesButton labels (at least one).
playersnumber[] | nullyesSeats that see this, or null for everyone.
{"k":"showDialog","dialogId":"menu","title":"Choose","body":"Pick a reward.","buttons":["Gold","Lumber"],"players":null}

hideDialog

Hide dialog. Close a dialog.

Editor: hide dialog ‹Dialog id›

FieldTypeRequiredDescription
dialogIddialogIdyesDialog id.
{"k":"hideDialog","dialogId":"menu"}

ping

Ping minimap. Ping a tile on the minimap.

Editor: ping ‹At point› for ‹Shown to› in ‹Colour› for ‹Duration (ticks)› ticks

FieldTypeRequiredDescription
playersnumber[] | nullyesSeats that see this, or null for everyone.
atexpr (point)yesTile to ping.
colorHexcolorHexnoColour (default #ffcc00).
durationTicksint (≥ 1)noDuration in ticks (default 60).
{"k":"ping","players":null,"at":{"k":"regionCenter","region":"arena"}}

playSound

Play sound. Play a sound effect (base game or map custom sound).

Editor: play sound ‹Sound› for ‹Shown to›

FieldTypeRequiredDescription
soundIdsoundIdyesSound id.
playersnumber[] | nullyesSeats that see this, or null for everyone.
{"k":"playSound","soundId":"victory","players":null}

createUIFrame

Create UI frame. Create or replace a declarative HUD frame.

Editor: create UI frame ‹Frame ID› at ‹Anchor› (‹X offset (px)›, ‹Y offset (px)›) size ‹Width (px)›×‹Height (px)› titled ‹Title› saying ‹Text› progress ‹Progress 0..1› in ‹Progress colour› styled ‹Style› for ‹Shown to› visible ‹Visible›

FieldTypeRequiredDescription
frameIdframeIdyesFrame id.
anchor'top_left' | 'top_center' | 'top_right' | 'center_left' | 'center' | 'center_right' | 'bottom_left' | 'bottom_center' | 'bottom_right'yesScreen anchor.
xexpr (number)yesX offset from the anchor (px).
yexpr (number)yesY offset from the anchor (px).
widthexpr (number)yesWidth (px).
heightexpr (number)yesHeight (px).
titletextnoTitle template.
texttextnoBody template.
progressexpr (real)noProgress bar fill 0..1.
progressColorcolorHexnoProgress bar colour.
styleuiStylenoVisual style overrides.
playersnumber[] | nullnoSeats that see this, or null/absent for everyone.
visibleboolnoVisible (default true).
{"k":"createUIFrame","frameId":"hud","anchor":"top_left","x":1,"y":1,"width":1,"height":1}

updateUIFrame

Update UI frame. Update fields of an existing frame.

Editor: update UI frame ‹Frame ID› title ‹Title› text ‹Text› progress ‹Progress 0..1› colour ‹Progress colour› visible ‹Visible›

FieldTypeRequiredDescription
frameIdframeIdyesFrame id.
titletextnoTitle template.
texttextnoBody template.
progressexpr (real)noProgress 0..1.
progressColorcolorHexnoProgress bar colour.
visibleboolnoVisible.
{"k":"updateUIFrame","frameId":"hud"}

destroyUIFrame

Destroy UI frame. Remove a frame.

Editor: destroy UI frame ‹Frame ID›

FieldTypeRequiredDescription
frameIdframeIdyesFrame id.
{"k":"destroyUIFrame","frameId":"hud"}

clearUIFrames

Clear UI frames. Remove every frame.

Editor: clear all UI frames for ‹Shown to›

FieldTypeRequiredDescription
playersnumber[] | nullnoSeats that see this, or null/absent for everyone.
{"k":"clearUIFrames"}

setQuest

Set quest. Create or update a quest-log entry.

Editor: set quest ‹Quest ID› "‹Title›" to ‹State›: ‹Description› icon ‹Icon› at position ‹Sort position›

FieldTypeRequiredDescription
questIdquestIdyesQuest id.
titletextyesTitle template.
descriptiontextyesDescription template.
state'active' | 'completed' | 'failed'yesQuest state.
iconstringnoIcon key.
orderintnoSort position.
{"k":"setQuest","questId":"main_quest","title":"Defend the gate","description":"Survive ten waves.","state":"active"}

clearQuests

Clear quests. Remove every quest.

Editor: clear all quests

No fields.

{"k":"clearQuests"}

Cutscene actions

playCutscene

Play cutscene. Start a map scene for these seats; the sim records only the start.

Editor: play cutscene ‹Scene› for ‹Shown to›

FieldTypeRequiredDescription
sceneIdsceneIdyesScene id.
playersnumber[] | nullyesSeats that see this, or null for everyone.
{"k":"playCutscene","sceneId":"intro","players":null}

stopCutscene

Stop cutscene. End running cutscenes for these seats.

Editor: stop the cutscene playing for ‹Shown to›

FieldTypeRequiredDescription
playersnumber[] | nullyesSeats that see this, or null for everyone.
{"k":"stopCutscene","players":null}

Camera actions

cameraPan

Pan camera. Pan the camera to a point over a duration.

Editor: pan camera for ‹Shown to› to ‹Point› over ‹Duration (ticks)› ticks

FieldTypeRequiredDescription
playersnumber[] | nullyesSeats that see this, or null for everyone.
toexpr (point)yesTarget tile.
durationTicksint (≥ 0)noPan duration in ticks.
{"k":"cameraPan","players":null,"to":{"k":"regionCenter","region":"arena"}}

cameraSetZoom

Set camera zoom. Change the camera zoom.

Editor: set camera zoom for ‹Shown to› to ‹Zoom› over ‹Duration (ticks)› ticks

FieldTypeRequiredDescription
playersnumber[] | nullyesSeats that see this, or null for everyone.
zoomexpr (real)yesZoom factor.
durationTicksint (≥ 0)noTransition in ticks.
{"k":"cameraSetZoom","players":null,"zoom":1.5}

cameraLock

Lock camera. Lock the camera to a unit or a point.

Editor: lock camera for ‹Shown to› to ‹Follow unit› at ‹Hold point›

FieldTypeRequiredDescription
playersnumber[] | nullyesSeats that see this, or null for everyone.
unitexpr (unit)noUnit to follow.
atexpr (point)noPoint to hold.
{"k":"cameraLock","players":null,"unit":{"k":"eventUnit"}}

cameraUnlock

Unlock camera. Release a camera lock.

Editor: unlock camera for ‹Shown to›

FieldTypeRequiredDescription
playersnumber[] | nullyesSeats that see this, or null for everyone.
{"k":"cameraUnlock","players":null}

cameraSetBounds

Camera bounds. Confine the camera to a region, or null to clear.

Editor: confine camera for ‹Shown to› to ‹Region›

FieldTypeRequiredDescription
playersnumber[] | nullyesSeats that see this, or null for everyone.
regionregionId | nullyesRegion id, or null.
{"k":"cameraSetBounds","players":null,"region":"arena"}

cameraShake

Shake camera. Shake the camera.

Editor: shake camera for ‹Shown to› at ‹Intensity (0–1)› for ‹Duration (ticks)› ticks

FieldTypeRequiredDescription
playersnumber[] | nullyesSeats that see this, or null for everyone.
intensityexpr (real)yesShake intensity.
durationTicksint (≥ 0)noDuration in ticks.
{"k":"cameraShake","players":null,"intensity":1.5}

cameraReset

Reset camera. Clear locks, bounds and zoom overrides.

Editor: reset camera for ‹Shown to›

FieldTypeRequiredDescription
playersnumber[] | nullyesSeats that see this, or null for everyone.
{"k":"cameraReset","players":null}

Physics actions

applyImpulse

Apply impulse. Give a unit a kinematic velocity.

Editor: apply velocity (‹Velocity X›, ‹Velocity Y›) to ‹Unit› with friction ‹Friction› bounce ‹Bounce› for ‹Duration (ticks)› ticks

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
vxexpr (real)yesVelocity X (tiles/tick).
vyexpr (real)yesVelocity Y (tiles/tick).
frictionexpr (real)noPer-tick velocity multiplier.
bounceexpr (real)noRestitution on collision.
ticksexpr (int)noMaximum duration in ticks.
{"k":"applyImpulse","unit":{"k":"eventUnit"},"vx":1.5,"vy":1.5}

setUnitKinematics

Set kinematics. Tune kinematic parameters of a unit.

Editor: set kinematics of ‹Unit› friction ‹Friction› bounce ‹Bounce› stop below ‹Minimum speed›

FieldTypeRequiredDescription
unitexpr (unit)yesThe unit (entity id). A dead or missing unit is harmless: reads give zero values, writes do nothing.
frictionexpr (real)noPer-tick velocity multiplier.
bounceexpr (real)noRestitution on collision.
minSpeedCutoffexpr (real)noSpeed below which motion stops.
{"k":"setUnitKinematics","unit":{"k":"eventUnit"}}

Save codes actions

generateSaveCode

Generate save code. Encode named values into a tamper-evident code bound to this map, stored in a string variable.

Editor: generate save code for ‹Player› with ‹Data› into ‹Target variable›

FieldTypeRequiredDescription
playerexpr (player)yesSeat id (0-based) of the player.
toVarvarNameyesString variable receiving the code.
dataexprRecordyesField name → value expression.
{"k":"generateSaveCode","player":0,"toVar":"code","data":{"level":3}}

Script structure

TriggerScript

FieldTypeRequiredDescription
versionint (≥ 1, ≤ 1)yesAlways 1.
varsvarDeclsyesGlobal variables, initialised in order on map init.
regionsregionDefsyesNamed tile rectangles (RegionDef[]).
triggerstriggerDefsyesTriggers (TriggerDef[]), evaluated in array order.
saveCodeSaltstringnoBinds save codes to this map; defaults to the map name.
functionsfunctionDefsnoUser-defined functions (FunctionDef[]).
hashtableshashtableDeclsnoDeclared hashtables (HashtableDecl[]).

VarDecl

FieldTypeRequiredDescription
namestringyesIdentifier: letters, digits and _, not starting with a digit or __.
typevarTypeyesValue type.
arrayboolnoFixed-length array.
arraySizeint (≥ 1)noArray length (globals ≤ 8192, locals ≤ 1024).
initexpr (any)noInitial value (globals: at map init; locals: at each execution start).

RegionDef

FieldTypeRequiredDescription
idstringyesRegion id.
xintyesTop-left tile X.
yintyesTop-left tile Y.
wint (≥ 1)yesWidth in tiles (≥ 1).
hint (≥ 1)yesHeight in tiles (≥ 1).
namestringnoEditor label.

TriggerDef

FieldTypeRequiredDescription
idstringyesStable trigger id.
namestringnoEditor label.
enabledboolnoInitially enabled (default true).
runOnceboolnoFire at most once.
eventseventsyesEvents (any one fires the trigger).
conditionsexprListnoConditions, all of which must hold. They see globals only.
localsvarDeclsnoPer-execution local variables; survive wait and save/load.
actionsactionsyesActions, run top to bottom.

FunctionDef

FieldTypeRequiredDescription
namestringyesFunction identifier.
descriptionstringnoDocumentation.
paramsparamsnoTyped parameters (≤ 16, scalars only).
returnsvarTypenoReturn type; absent = returns nothing.
localsvarDeclsnoPer-call locals.
actionsactionsyesBody. May not contain wait or stopTrigger.

FunctionParam

FieldTypeRequiredDescription
namestringyesParameter identifier.
typevarTypeyesParameter type.
descriptionstringnoDocumentation.

HashtableDecl

FieldTypeRequiredDescription
namestringyesHashtable identifier.
valueTypevarTypeyesType every stored value is coerced to.
maxEntriesint (≥ 1, ≤ 16384)noEntry cap (≤ 16384).
descriptionstringnoDocumentation.

UnitFilter

FieldTypeRequiredDescription
playersintListnoOwner must be one of these seats.
ofPlayerexpr (player)noOwner must equal this seat.
alliedToexpr (player)noOwner must be allied to this seat.
enemyOfexpr (player)noOwner must not be allied to this seat.
unitTypeIdsunitTypeIdListnoUnit/building type must be one of these.
tagsstringListnoAuthored tag must be one of these.
aliveOnlyboolnoOnly living units (default true).
heroesOnlyboolnoOnly heroes.
buildingsOnlyboolnoOnly buildings.
excludeBuildingsboolnoNo buildings.
flyingOnlyboolnoOnly flyers.
excludeFlyingboolnoNo flyers.
excludingexpr (unitGroup)noDrop these units.

UIFrameStyle

FieldTypeRequiredDescription
backgroundColorstringnoCSS colour.
borderColorstringnoCSS colour.
textColorstringnoCSS colour.
fontSizenumbernoFont size (px).
borderRadiusnumbernoCorner radius (px).
paddingnumbernoPadding (px).