The script API

What a script is

12

The source lives in the document — an XP is one file, and a level whose behaviour is in four other files arrives half missing. Each source is capped at 64 kB, and each entity gets its own run of its script: two turrets sharing patrol each get their own variables, because a script is compiled as a factory, not evaluated as a module.

A script attaches to a blueprint — or to the level itself, as a director: no body, self is a handle onto nothing, and everything goes through world and getEntityByName. The director gets onSpawn and onTick, never onTrigger.

The three hooks

All three are optional. Within a frame: new entities get their onSpawn, then every onTick runs, then what the scripts set off among themselves is delivered — a thing spawned this frame gets its onSpawn this frame and its first tick the next.

What onTrigger hears

Two things decide whether a script hears anything at all. A blueprint only receives enter/exit if it carries at least one trigger — a bare listener is conventionally a harmless emit. And the rest of the vocabulary — pressed, finished, returned, emitted — fires rules, never scripts: a script that must react to the whistle watches a property a rule wrote.

self — the entity

world — the clock, the dice, the data

One gap worth knowing before it costs you an evening: the level's data is not reachable from onTrigger — reads answer 0 and writes do nothing, silently. The pattern round it is a flag: the hook sets a variable, and onTick does the spending.

let asked = false

function onTrigger(event) {
  if (event === 'enter') asked = true
}

function onTick() {
  if (!asked) return
  asked = false
  if (world.spend('coins', 5)) self.spawn('prize', 0, 1, 0)
  else log('not enough coins')
}

What was taken away

A fresh sandbox simply is the language: no fetch, no setTimeout, no window. Two more are removed deliberately, because two clients run the same script over the same entities and have to agree: Date is deleted — a clock is per machine — and Math.random throws, with a message naming the replacement, rather than disappearing. Both are the first things anybody reaches for, and a script using either looks correct on the machine it was written on and desynchronises everywhere else.

There is no setTimeout because a delay is world.time and a number you kept — the only version of a delay two clients agree about:

let ready = 0

function onTick() {
  if (world.time < ready) return
  ready = world.time + 1
  self.add('shots', 1)
}

When one goes wrong

One throw stops that entity'sscript, permanently, for that run — it would otherwise throw the same failure sixty times a second and bury the one that mattered. The rest of the level keeps running. Failures are shown on the HUD during play with the script's name and your line numbers; compile errors arrive as document problems when the level opens. A script that quietly stopped is the failure all of this exists to prevent.

Limits, and what a hook costs

The real cost is not lines of JavaScript but crossings — each call that touches the world crosses the sandbox boundary. A thousand entities doing arithmetic is four per cent of a frame; the same thousand looking each other up is most of one. Cache what getEntityByName gave you, read self.x once into a variable — the way to raise the ceiling is to touch the world less, not to write less code.

What a script cannot do

For working code to start from, the shooter write-up walks two real scripts — the runner on a clock and the mine that comes for you — line by line.