Docs Quick code

Events and messages

Event nodes, reacting to events from code with on(), and scripts talking to each other with send / on_message.

#Event nodes

A script's chains start at Event nodes (Scripts tab). An object's script can start on:

Event	Runs when
Player presses E (the use key)	The player uses it.
Player touches / steps on it	The player walks into or onto it.
Player enters the level	The level starts (also for level scripts).
It is destroyed	Its Health runs out.
Every few seconds	Over and over, every so often.
Called by Run script	Another script runs it: `run_script(id, data)`.
It bumps into something	It meets the player / anything / objects with tags.
Player presses a key / mouse button	That key (within a range, if you set one).
Player enters / leaves a zone	The player crosses a zone (Zone tool).
A level's goal is complete / A world is complete	Goals finished.
A message is sent	Code sends that message: `send("boss_phase", data)`.

#Events from code: on

Inside an object's script, on(event, fn) calls fn each time that event happens to the object:

Event	`fn` gets
`"touched"`	— (the player touched it)
`"bumped"`	what it bumped into (an object or the player)
`"used"`	— (the player pressed E at it; the object needs something to use, like a Player presses E event, so the game shows the E prompt)
`"hurt"`	how much health it lost
`"destroyed"`	—

-- On a pressure plate's script (Event: Player enters the level):
on("touched", function()
  object("gate").move(0, 3, 0, 1)
  play("door")
end)

Handlers run as tasks: they can wait, and several can run at once. They're forgotten when the player leaves the level (the level's code sets them up again when it's entered).

#Messages: scripts talking to each other

send(message, data) tells everyone listening; on_message(message, fn) listens. The data can be anything — a number, a text, a table.

-- The boss's script:
self.hp = 100
on("hurt", function()
  if self.hp < 50 and not self.angry then
    self.angry = true
    send("boss_phase", {phase = 2, boss = self})
  end
end)

-- The arena's script (a level script):
on_message("boss_phase", function(d)
  banner("Phase " .. d.phase .. "!")
  object("arena_bars").hide()
  music_fade("boss_theme_fast", 1)
end)

A message also starts every A message is sent Event node with that message name (capitals don't matter); in that chain's code, event_data() is the data. send gives how many listeners it reached.

#Passing data to a script

run_script("scr_door", {open = true}) starts that script's Called by Run script events; its code reads the data with event_data():

local d = event_data()
if d ~= nil and d.open then self.move(0, 3, 0, 1) end