Trigger reference

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›

{"k":"periodic","everyTicks":1}

atTick#

At tick. Fires once on an exact tick.

Editor: at tick ‹Tick›

{"k":"atTick","tick":1}

timerExpires#

Timer expires. Fires when a named timer reaches zero.

Editor: timer ‹Timer› expires

{"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›

{"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›

{"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›

{"k":"unitDies"}

unitTrained#

Unit trained. Fires when production completes a unit.

Editor: a unit finishes training matching ‹Filter›

{"k":"unitTrained"}

buildingComplete#

Building completes. Fires when construction finishes.

Editor: a building completes matching ‹Filter›

{"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›

{"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›

{"k":"heroLevels"}

unitDamaging#

Unit is about to take damage. Fires between armour and the hp write, for EVERY source of damage in the game — melee, projectiles, spells, burns, thorns, lava, a collapsing bridge. Unit = the victim, other unit = the dealer (0 for the environment), event damage = the amount about to land. This is the one event whose amount you can change: use "set event damage" for a custom armour system, a shield that absorbs part of a hit, or a damage-type table. Triggers fire in authored order and each sees the previous one's result. "wait" is not allowed in a trigger with this event, because the hit is only half resolved. Needs map format 3.

Editor: a unit is about to take damage — ‹Filter›

{"k":"unitDamaging"}

unitDamaged#

Unit has taken damage. Fires immediately after the hp is written, for every source of damage. Event damage = the amount that actually landed. Use it to react — a bloodlust stack, a retaliation, "the boss enrages below half". The victim of a killing blow is still alive with 0 hp here, so read hp rather than alive. "set event damage" does nothing on this event; there is nothing left to change. Needs map format 3.

Editor: a unit has taken damage — ‹Filter›

{"k":"unitDamaged"}

Item events#

itemPickedUp#

Item picked up. Fires when a hero picks up an item. NOTE: buying does not fire it — watch itemPurchased as well if you mean "the hero now holds one".

Editor: an item is picked up — ‹Item›

{"k":"itemPickedUp"}

itemUsed#

Item used. Fires when a hero consumes or activates an item — a potion, a scroll, a town portal, an active. Event unit = the hero, text = the item id. Needs map format 3.

Editor: a hero uses an item (‹Item›)

{"k":"itemUsed"}

itemPurchased#

Item purchased. Fires when a hero buys an item from a shop. Gambling-den rolls do NOT fire it. Event unit = the hero, text = the item id. Needs map format 3.

Editor: a hero buys an item (‹Item›)

{"k":"itemPurchased"}

itemSold#

Item sold. Fires when a hero sells an item. Event value = 1 if sold for XP, 0 if sold for gold. Needs map format 3.

Editor: a hero sells an item (‹Item›)

{"k":"itemSold"}

itemDropped#

Item dropped. Fires when a hero drops an item, from the backpack or off the paper doll. A hero DEATH drop fires it too, once per item. Needs map format 3.

Editor: a hero drops an item (‹Item›)

{"k":"itemDropped"}

Combat events#

abilityCastStart#

Cast starts. Fires once when a cast is committed, after every cost and range check has passed. Event unit = caster, other unit = target unit (0 if none), value = wind-up length in ticks, eventSpellId = the spell, eventTargetPoint = the target tile. An ordinary RTS or AI cast has NO wind-up (only a possessed hero or a spell with rtsCastBar does), so start, effect and finished all land on the same tick. Boss telegraphs use a separate engine and fire none of these. Needs map format 3.

Editor: a unit starts casting ‹Spell id›

{"k":"abilityCastStart"}

abilityCastEffect#

Cast resolves. Fires when the spell's effect actually resolves — the one to hang a consequence on. Event unit = caster, other unit = target unit, player = the caster's seat, eventSpellId = the spell, eventTargetPoint = the target tile. Needs map format 3.

Editor: a cast resolves (‹Spell id›)

{"k":"abilityCastEffect"}

abilityCastFinished#

Cast finishes. Fires once when a cast ends normally. Exactly-once per cast for both instant and cast-bar spells. Needs map format 3.

Editor: a cast finishes (‹Spell id›)

{"k":"abilityCastFinished"}

abilityCastCancelled#

Cast cancelled. Fires when a cast in progress is interrupted. Event text = the reason: move, death, damage, invalid or superseded. A cast REFUSED before it started (no mana, on cooldown, out of range, silenced, no line of sight) fires NOTHING, not even this. Sleep also strips a cast without firing it. Needs map format 3.

Editor: a cast is cancelled (‹Spell id›)

{"k":"abilityCastCancelled"}

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›

{"k":"projectileHits"}

Orders events#

orderIssued#

Order issued. Fires once when a unit or selection is ordered. COVERS every player order (right-click, drag, minimap, HUD, hotkey, queued waypoints), every trigger order action, and orders arriving by lockstep, replay, cinematic, possession or a mode's bot. DOES NOT cover the heuristic AI or the LLM commander, which write movement directly instead of issuing commands — so on an AI seat this is near-silent and must not be used to police AI behaviour. Event unit = the LOWEST entity id ordered, other unit = target unit (0 if none), value = how many units the order addressed, text = the order kind, eventTargetPoint = the target tile ((-1,-1) for stop/hold). ONE signal per order, not one per unit. Needs map format 3.

Editor: a unit is ordered to ‹Order› by player ‹From seat›

{"k":"orderIssued"}

Player events#

playerEliminated#

Player eliminated. Fires when a seat is eliminated.

Editor: a player is eliminated — ‹Player›

{"k":"playerEliminated"}

playerLeaves#

Player leaves. Fires on the tick a seat's human leaves the match, under any leaver policy. NOT the same as elimination and neither implies the other: a leaver under abandon keeps a living base, and an eliminated player usually stays to watch. Event player = the seat that left. Needs map format 3.

Editor: a player leaves — ‹Player›

{"k":"playerLeaves"}

upgradeComplete#

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

Editor: an upgrade completes — ‹Upgrade›

{"k":"upgradeComplete"}

playerChats#

Player chats. Fires when a seated player sends an all-chat line (team chat and whispers never fire it); event text = the line.

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

{"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›)

{"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

{"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›

{"k":"dialogButton"}

uiFrameClicked#

UI frame clicked. Fires when a player clicks one of your own HUD frames (arrives through lockstep, like a dialog button). Event player = the seat that clicked, text = the frame id. A click only counts when that seat can really see that frame right now — a frame that was destroyed, hidden, or shown to somebody else fires nothing, however the click arrived. Needs map format 3.

Editor: a UI frame is clicked: ‹Frame›

{"k":"uiFrameClicked"}

Custom events#

custom#

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

Editor: custom event ‹Event name› is raised

{"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

{"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›

{"k":"int","v":1}

real#

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

Editor: ‹Value›

{"k":"real","v":1}

bool#

Boolean — returns bool. true or false.

Editor: ‹Value›

{"k":"bool","v":true}

str#

Text — returns string. A string literal.

Editor: "‹Value›"

{"k":"str","v":"text"}

Geometry expressions#

point#

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

Editor: (‹Tile X›, ‹Tile 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›

{"k":"distance","a":1,"b":1}

pointX#

Point X — returns number. X of a point.

Editor: X of ‹Point›

{"k":"pointX","p":{"k":"regionCenter","region":"arena"}}

pointY#

Point Y — returns number. Y of a point.

Editor: Y of ‹Point›

{"k":"pointY","p":{"k":"regionCenter","region":"arena"}}

regionCenter#

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

Editor: centre of ‹Region›

{"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›

{"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›

{"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›)

{"k":"offsetPoint","p":{"k":"regionCenter","region":"arena"},"dx":1,"dy":1}

polarOffset#

Point at an angle — returns point. A point (or unit) moved distance tiles along angle. With angleBetween this is the whole of "spawn behind the hero", "ring of totems", "fire at this bearing". Needs map format 3.

Editor: ‹From› moved ‹Tiles› at ‹Direction›

{"k":"polarOffset","p":{"k":"regionCenter","region":"arena"},"angle":1,"distance":1}

angleBetween#

Bearing from A to B — returns real. Direction from A to B in radians, -pi..pi. Either side may be a unit or a point. Due west is +pi, not -pi, so compare bearings with a tolerance rather than for equality. Needs map format 3.

Editor: bearing from ‹From› to ‹To›

{"k":"angleBetween","a":1,"b":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›

{"k":"unitProp","unit":{"k":"eventUnit"},"prop":"hp"}

unitAboard#

Unit aboard transport — returns bool. Whether the original unit is held in the original transport cargo. False for missing units or hulls. Needs map format 3.

Editor: ‹Unit› is aboard ‹Transport›

{"k":"unitAboard","unit":{"k":"eventUnit"},"transport":{"k":"eventUnit"}}

unitPoint#

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

Editor: position of ‹Unit›

{"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›

{"k":"entityByAid","aid":"north_gate"}

unitHasBuff#

Unit has buff — returns bool. True while this exact buff id is on the unit and has not run out. A buff whose remaining time has reached zero already answers false, one tick before the engine sweeps it up — so "re-apply when it runs out" does not double-cast. Matches the whole id, never a prefix. Needs map format 3.

Editor: ‹Unit› has buff ‹Buff id›

{"k":"unitHasBuff","unit":{"k":"eventUnit"},"buffId":"text"}

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›]

{"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›

{"k":"add","a":1,"b":1}

sub#

A − B — returns number. Difference.

Editor: ‹A› − ‹B›

{"k":"sub","a":1,"b":1}

mul#

A × B — returns number. Product.

Editor: ‹A› × ‹B›

{"k":"mul","a":1,"b":1}

div#

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

Editor: ‹A› ÷ ‹B›

{"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›

{"k":"mod","a":1,"b":1}

neg#

Negate — returns number. Arithmetic negation.

Editor: −‹A›

{"k":"neg","a":1}

abs#

Absolute value — returns number. Absolute value.

Editor: |‹A›|

{"k":"abs","a":1}

min#

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

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

{"k":"min","a":1,"b":1}

max#

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

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

{"k":"max","a":1,"b":1}

clamp#

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

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

{"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›)

{"k":"trunc","a":1.5}

floor#

Floor — returns int. Largest integer at or below A. Needs map format 3.

Editor: floor(‹A›)

{"k":"floor","a":1}

ceil#

Ceiling — returns int. Smallest integer at or above A. Needs map format 3.

Editor: ceil(‹A›)

{"k":"ceil","a":1}

round#

Round — returns int. Nearest integer, halves going toward +Infinity — so round(2.5) is 3 and round(-2.5) is -2. Needs map format 3.

Editor: round(‹A›)

{"k":"round","a":1}

sqrt#

Square root — returns real. Square root. A negative A yields 0, never NaN. Needs map format 3.

Editor: √‹A›

{"k":"sqrt","a":1}

pow#

A to the power B — returns real. A raised to B. A non-finite result yields 0. Needs map format 3.

Editor: ‹A› ^ ‹B›

{"k":"pow","a":1,"b":1}

sign#

Sign — returns int. -1 for a negative A, 1 for a positive one, 0 for zero. Needs map format 3.

Editor: sign(‹A›)

{"k":"sign","a":1}

lerp#

Interpolate — returns real. A blended toward B by T: A + (B - A) x T. T is NOT clamped, so 2 overshoots and -1 extrapolates backwards. Needs map format 3.

Editor: blend ‹A› → ‹B› by ‹Blend factor›

{"k":"lerp","a":1,"b":1,"t":1}

Maths expressions#

sin#

Sine — returns real. Sine of an angle in radians. Needs map format 3.

Editor: sin(‹Angle›)

{"k":"sin","a":1}

cos#

Cosine — returns real. Cosine of an angle in radians. Needs map format 3.

Editor: cos(‹Angle›)

{"k":"cos","a":1}

tan#

Tangent — returns real. Tangent of an angle in radians. Needs map format 3.

Editor: tan(‹Angle›)

{"k":"tan","a":1}

atan2#

Angle of a vector — returns real. Direction of the vector (X, Y) in radians, -pi..pi. Y comes first, as it does in every atan2. Due west is +pi, not -pi. Needs map format 3.

Editor: angle of (‹Horizontal component›, ‹Vertical component›)

{"k":"atan2","y":1,"x":1}

asin#

Arc sine — returns real. Angle in radians whose sine is A. Outside -1..1 yields 0, never NaN. Needs map format 3.

Editor: asin(‹A›)

{"k":"asin","a":1}

acos#

Arc cosine — returns real. Angle in radians whose cosine is A. Outside -1..1 yields 0, never NaN. Needs map format 3.

Editor: acos(‹A›)

{"k":"acos","a":1}

exp#

e to the power A — returns real. e raised to A. A non-finite result yields 0. Needs map format 3.

Editor: e^‹A›

{"k":"exp","a":1}

log#

Natural logarithm — returns real. Natural log of A. A at or below zero yields 0, never -Infinity and never NaN. Needs map format 3.

Editor: ln(‹A›)

{"k":"log","a":1}

Comparison expressions#

eq#

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

Editor: ‹A› = ‹B›

{"k":"eq","a":1,"b":1}

ne#

A ≠ B — returns bool. Inequality.

Editor: ‹A› ≠ ‹B›

{"k":"ne","a":1,"b":1}

lt#

A < B — returns bool. Less than.

Editor: ‹A› < ‹B›

{"k":"lt","a":1,"b":1}

le#

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

Editor: ‹A› ≤ ‹B›

{"k":"le","a":1,"b":1}

gt#

A > B — returns bool. Greater than.

Editor: ‹A› > ‹B›

{"k":"gt","a":1,"b":1}

ge#

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

Editor: ‹A› ≥ ‹B›

{"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›

{"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›

{"k":"or","a":true,"b":true}

not#

Not A — returns bool. Logical negation.

Editor: not ‹A›

{"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›

{"k":"rand","min":1,"max":6}

randReal#

Random real — returns real. Random real in [min, max) from the synchronised game PRNG. Always consumes exactly one draw, even when min equals max, because a conditional draw would advance the stream on one client and not another. Needs map format 3.

Editor: random real ‹Minimum› to ‹Maximum (exclusive)›

{"k":"randReal","min":1,"max":1}

timerRemaining#

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

Editor: ticks left on ‹Timer›

{"k":"timerRemaining","timer":"wave_timer"}

timerRunning#

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

Editor: ‹Timer› is running

{"k":"timerRunning","timer":"wave_timer"}

Player expressions#

playerResource#

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

Editor: ‹Player›'s ‹Resource›

{"k":"playerResource","player":0,"resource":"gold"}

playerPop#

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

Editor: ‹Player›'s population

{"k":"playerPop","player":0}

playerMaxPop#

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

Editor: ‹Player›'s population cap

{"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

{"k":"playerAlive","player":0}

playerTeam#

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

Editor: ‹Player›'s team

{"k":"playerTeam","player":0}

playerHasUpgrade#

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

Editor: ‹Player› has researched ‹Upgrade›

{"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›

{"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›

{"k":"isEnemy","a":0,"b":0}

playerName#

Player's name — returns string. Display name of a seat. Today this is always "Player 1", "Player 2"… — the lobby name is a per-client string and a trigger variable is hashed, so it is deliberately not read here. Needs map format 3.

Editor: ‹Player›'s name

{"k":"playerName","player":0}

playerIsHuman#

A human is at this seat — returns bool. True when a human is present: a human slot whose player has not left. An AI seat is false, and so is a seat whose human has gone. Needs map format 3.

Editor: ‹Player› is a human player

{"k":"playerIsHuman","player":0}

playerCount#

Number of players — returns int. How many seats match. The creep and neutral seats are never counted, so "alive" on a two-player map with creeps answers 2. Needs map format 3.

Editor: number of ‹Which seats› players

{"k":"playerCount","of":"seated"}

isPointVisibleTo#

Seat can see tile — returns bool. True when THAT SEAT's own units or completed buildings reveal the tile right now. It is the simulation's own vision test, not the fog you are looking at, so it answers the same on every client and in a replay. Allied vision is NOT folded in: ask about each ally, or use "players are allied". A seat that is not in the lobby owns nothing and answers false; the creep seat answers like any other. It does not know about night, possession or a submerged submarine's halved sight — it is the daylight baseline radius plus the sightRadius buff. It SCANS every revealer in the world, so it costs about what "units of player" costs; do not put it inside a big loop. Needs map format 3.

Editor: ‹Player› can see ‹Tile›

{"k":"isPointVisibleTo","player":0,"at":{"k":"regionCenter","region":"arena"}}

Group expressions#

unitsInRegion#

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

Editor: units in ‹Region› matching ‹Filter›

{"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›

{"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›

{"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›

{"k":"unitsOfType","unitTypeId":"dwarf_ironguard"}

groupCount#

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

Editor: number of units in ‹Unit 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›

{"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›

{"k":"groupRandom","group":{"k":"unitsInRegion","region":"arena"}}

groupUnion#

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

Editor: ‹A› together with ‹B›

{"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›

{"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›

{"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"}

unitsInRadius#

Units within a radius — returns unitGroup. Sorted group of units within radius tiles of a point or unit. Measured on squared distance, which is exact on an integer grid; a radius below 0 matches nothing. Needs map format 3.

Editor: units within ‹Radius in tiles› of ‹Centre› matching ‹Filter›

{"k":"unitsInRadius","at":{"k":"regionCenter","region":"arena"},"radius":1}

closestUnit#

Closest unit — returns unit. The nearest matching unit to a point or unit, or no unit. A tie goes to the lowest entity id, so the answer never depends on iteration order. Needs map format 3.

Editor: closest unit to ‹From› within ‹Maximum distance› matching ‹Filter›

{"k":"closestUnit","at":{"k":"regionCenter","region":"arena"}}

groupSortBy#

Group in order — returns unitGroup. The group reordered. Ties always break on the LOWEST entity id, in both directions — so 'desc' reverses the keys but is not exactly the reverse of 'asc' when two units share a key, and "the weakest" and "the strongest" pick the same one of a tied pair. The result is NOT id-sorted, so storing it in a unitGroup variable loses the order (variables are canonicalised on write) — use it inline, with forEachUnit or groupAt. Needs map format 3.

Editor: ‹Unit group› ordered by ‹Order by› ‹Direction› from ‹Measure from›

{"k":"groupSortBy","group":{"k":"unitsInRegion","region":"arena"},"by":"hp"}

groupPickN#

N random units of group — returns unitGroup. At most N random members, sorted. Consumes exactly min(N, group size) PRNG draws — both numbers are hashed sim state, so every client draws the same count. Needs map format 3.

Editor: ‹How many› random units of ‹Unit group›

{"k":"groupPickN","group":{"k":"unitsInRegion","region":"arena"},"n":1}

groupFilter#

Group matching a filter — returns unitGroup. Members of the group that match the filter. The one way to narrow a group you already hold without rebuilding it from the world. Needs map format 3.

Editor: ‹Unit group› matching ‹Filter›

{"k":"groupFilter","group":{"k":"unitsInRegion","region":"arena"},"filter":{}}

Item expressions#

heroHasItem#

Unit has item — returns bool. True when the unit holds this item in its BACKPACK or has it EQUIPPED. Both halves, because "does he have the crown" does not mean "in his bag but not on his head". Needs map format 3.

Editor: ‹Unit› has ‹Item›

{"k":"heroHasItem","unit":{"k":"eventUnit"},"itemId":"healing_potion"}

heroItemCount#

Unit item count — returns int. How many of this item the unit holds: backpack stack counts summed, plus one for each equipped copy. Needs map format 3.

Editor: count of ‹Item› on ‹Unit›

{"k":"heroItemCount","unit":{"k":"eventUnit"},"itemId":"healing_potion"}