Reference
The trigger form and its options:
trigger(players, conditions, actions, options?) |
One trigger. players is a player or a list; up to 16 conditions and 64 actions. |
{ preserve, disabled, ignoreGameEnd, ignoreDisplay, conditionsMet, paused, waitSkipDisabled, flags } |
The options: each execution flag by name, and flags for raw bits. |
preserve() |
The same as { preserve: true }, as an action. |
not(condition) |
The opposite, where one condition can say it: a comparison flips, a switch test flips, always() becomes never(). "Exactly n" has no opposite and is an error. |
disabled(item) |
The condition or action kept in the trigger but switched off, as the Trigger Editor's disable does. |
hyperTriggers(owner?) |
The three preserved triggers of sixty-two waits that make the list run every frame. |
condition(type, …), action(type, …) |
A record by raw type number and fields, for anything the tables do not know. |
memory(address, comparison, value), setMemory(address, modifier, value) |
EUD: the value at a memory address, through the deaths table. |
The words the enumerated arguments take (StarEdit's labels work too):
| Argument | Words |
|---|---|
| Comparison | ">=", "<=", "==" |
| Modifier | "set", "add", "subtract" |
| Switch state, switch action | "set", "cleared"; "set", "clear", "toggle", "randomize" |
| Resource | "ore", "gas", "oreAndGas" |
| Score | "total", "units", "buildings", "unitsAndBuildings", "kills", "razings", "killsAndRazings", "custom" |
| Order | "move", "patrol", "attack" |
| Alliance | "enemy", "ally", "alliedVictory" |
| Unit state (doodads, invincibility) | "enable", "disable", "toggle" |
| Count | A number, or "All" |
| Text display | displayText(text) always displays; displayText(text, false) follows the game's message setting |
The names:
P1 … P12, CurrentPlayer, AllPlayers |
Constants. |
players. |
Every player group: Force1 … Force4 (and the force's own name), Foes, Allies, Neutral, NonAlliedVictory, and the twelve players again. |
units. |
Every unit type by StarEdit name as an identifier (TerranMarine) or a string index (units["Terran Marine"]), and by the custom name the map gives it. AnyUnit, Men, Buildings, Factories are there. |
locations. |
The map's locations by name; Anywhere and NoLocation. |
switches. |
Switch1 … Switch256, and any name the map sets. |
aiScripts. |
The AI scripts by StarEdit name; a four-letter code as a string works too. |
weapons., upgrades., techs., colors. |
The game's weapons, upgrades and technologies, for stats(); the player colours. |
| A number | Accepted wherever a name is: an EUD player, an unlisted unit id. |
Inside a program:
program(body, options?) |
Code that runs in the game; the map then needs StarCraft: Remastered. The one option is owner: a player, AllPlayers, a force, or a list — the last three run it once per player. |
game(fn) |
A function that runs in the game, for programs to call; it can live in any file and be imported. |
let n = 0, let f = false, let s = "", let u: Unit | null = null, let p = { … } |
A number, a boolean, a text, a unit of the game, a record of them. const is a value worked out when the script is applied, when it can be. |
u8, u16, u32 |
The declared range of a number variable that is never below zero: let lives: u8 = 3 stops at 0 and at 255; a u32 wraps at 4 294 967 295. A plain number is signed. |
u32(x), i32(x) |
The same 32 bits read the other way, for where a u32 meets a plain number. |
number[], boolean[], string[], { … }[], Unit[], number[][] |
An array of a program; one that is pushed to grows. push, pop, length, for…of; of numbers and booleans also fill, includes, indexOf. |
forEach, some, every, find, findIndex, reduce, map, filter, sort, reverse |
The array methods that take a function, on arrays and on the units of the game (unitsOf(P1).filter(…)). The function is written where it is used. |
slice, concat, toSorted, toReversed, Array.from, [...xs] |
Copies: a new array that grows. |
const { x, y } = p, const [a, ...rest] = xs, [a, b] = [b, a], { ...p, y: 9 } |
Patterns and spread, in declarations, for…of, parameters and assignments. |
class, new, extends, get / set, static |
Classes declared inside the program. An instance is a record; its class is settled when the script is applied. |
Record<K, V>, Map<K, V>, Set<K> |
A table keyed by an id of the game (UnitType, Player, Location, …): a cell for every id. |
Map<number, V>, Set<number>, Map<Unit, V>, Set<Unit> |
A table over any number, or over units: keys in the order they went in; values are numbers or booleans. |
shared(value) |
In a per-player program, one value for all the players instead of one each. |
sleep(duration) |
Give the frame back and carry on later. frames(n), seconds(n), minutes(n) make a duration. |
rose(condition), once(condition) |
True on the frame the condition becomes true; true the first time only. |
random(), random(n) |
A coin toss; a whole number from 0 to n − 1. |
deaths(p, unit), bring(p, unit, location), score(p, kind), … |
A comparing condition without its comparison and amount: the number itself. |
minerals(p), gas(p), resources(p, kind), countUnits(p, unit, location?), kills(p, unit), countdown(), elapsed() |
The same reads by plainer names. |
race(p), slot(p), isHuman(p), hasLeft(p), supply(p, of?, race?) |
The player: compare with races. and slots.; supply "used", "max" or "provided", as the top bar shows it. |
unitsAt(location, filter?), unitsOf(player, filter?), allUnits(filter?) |
The units a for…of runs over; a filter is { type, owner, at }. No sleep inside the loop. |
first(filter?), nearest(type, location, filter?), randomUnit(filter?) |
One unit, or null. |
u.hp, u.shields, u.energy, u.kills, u.cooldown, u.resources, u.stim …, u.invincible |
Read and written. u.hp = 0 kills. |
u.maxHp, u.maxShields, u.owner, u.type, u.x, u.y, u.orderId, u.burrowed, u.cloaked, u.hallucinated, u.underAttack |
Read only. |
u.order(kind, location), u.give(player), u.kill(), u.remove(), u.damage(n), u.heal(n), u.locate(location) |
What a unit can be told; damage and heal also take { percent }. |
stats(unitType), stats(weapon), stats(upgrade), stats(tech), stats(player) |
The game's tables: fields to read, = and +=. |
keyPressed(p, key), clicked(p, button?) |
True on the frame a press arrives. Keys: letters, digits, "F1" … "F12" (not "F6", which the game keeps to itself), "Space", "Enter", "Escape", the arrows and the rest of the list the editor offers; buttons "left", "right", "middle". |
mouse(p), underMouse(p, filter?), centerLocation(location, x, y) |
The cursor's place on the map as x and y; the unit nearest it (within 48 pixels, or the filter's within), or null; a location moved onto a point. |
chatted(p, pattern) |
null, or the values of a typed line: {n} a number, {what:unit} a unit type, `{kind:ore |
displayText(`… ${n} …`), name(p), color(p) |
A text with the program's numbers, a player's name and the colour code of their colour in it, for the current player. |
print(text, { to?, position? }) |
The same for another player, AllPlayers or a force, in the "chat" area or the "center" line. |
string: +, +=, ==, <, length, s[i], slice, indexOf, includes, startsWith, endsWith, padStart, padEnd, repeat, String(n), for (const ch of s) |
A text as a value. The objectives, a leaderboard's label, a transmission and a unit type's name take one the program made. |
clamp(x, lo, hi), Math.min, Math.max, Math.abs, the bitwise operators |
Work on variables. Math.floor and its siblings are accepted around a division and change nothing, since division is whole. |
wait(ms) |
The game's own Wait: allowed, stalls every trigger of the player, so prefer sleep. |
What a program cannot do:
- Play on a version of the game before Remastered.
trigger()does; a program does not. - A location or a player is fixed when the script is applied — also in a read; only the amounts, the counts, an action's unit type and the texts listed above can follow a variable. A sound's path or the next scenario's name is a text written in the script.
- Know that a key is being held, or read a key on a version before Remastered: the game reports each press once.
- A condition's own amount cannot be a variable — the game compares a quantity with a
number it is given — so read the quantity and compare it yourself:
minerals(P1) >= price. - Move a unit by writing where it is, cloak it, or change one unit's speed: the game ends
at a position write and showed nothing for the other two, so they are not offered.
order()and the Move Unit action move units;stats(type).speedis a type's speed. - A boolean has no text of its own (
${alive ? "yes" : "no"}), and a text has nosplit,replace,trimorparseInt. - Fractions: every number is whole.
Math.sqrtand the rest ofMathbeyondmin,maxandabswork on what the script knows, not on a variable: look the value up in a list the script worked out. - Keep a function in a variable, an array or a return value; write
function, or the arrow where the method takes it. Notry/catch/throw— the game has no exceptions — noasync, no generators, nofor…in. - On an array: no
shift,unshiftorsplice;mapmakes numbers or booleans, so push texts or records in afor…of. A function does not return a record or an array it made: hand it the one to fill in. - Loop for ever without a
sleep(): the editor refuses it, since the game would freeze. - No function that calls itself and sleeps, none more than 1 024 calls deep unless the
workspace's Settings raises it, no
forunrolled more than 256 times (write awhile), and no number past 2 147 483 647 either way (4 294 967 295 for au32): it wraps. - A
Mapholds numbers or booleans, and a text is not a key: for anything more, keep the place of a row of an array of records in it. - A program variable cannot reach a helper, a condition or an action, since those were computed when the script was applied.
The full description of the language, its compiler and the commands it offers other plugins is in the plugin's own README at scm-js/plugin-trigscript.