Skip to content

Events

React to the game. The server and the client each raise the events they see.

server + client

Calls fn(payload) each time the event fires, under pcall. Handlers run by priority (lower first), then in load order. A handler that errors 5 times is switched off. One that runs over 4 ms three times in a row is switched off. For a cancel event, returning false stops the action and the handlers after yours.

Parameter Type
event string An event name (see the table below).
fn function fn(payload); the payload is read-only.
options table? { priority = number }, default 0.

Returns a handle (a number) for mod.off

Raises

  • unknown event '
  • options must be a table
  • priority must be a number
mod.on("island_wiped", function(e)
mod.log("island", e.to, "was wiped by", e.from)
end)

server + client

Stops listening. A handle that is not yours, or already off, is ignored.

Parameter Type
handle number What mod.on returned.
local h
h = mod.on("tier_up", function(e)
mod.log("first tier up:", e.name)
mod.off(h)
end)

server + client table

The event names, as a read-only set: mod.events.tick == true. Cancel events hold "cancel".

assert(mod.events.weapon_landed)

slot, from and to are island numbers (0 is the Silo). Payloads are read-only.

Event Fires in When Payload
ready server + client Every mod has loaded. { mods }: read-only list of active mod ids
match_start server + client The game is starting. On the server it fires before the world exists. { role, settings }: settings is a copy, server only
match_end server The game is closing. There is no other end. { reason = "quit" }
tick server About every 0.2 s of game time. { dt, t }
frame client Every rendered frame. You pay for it. { dt }
tier_up server + client A new best missile tier on an island. { slot, tier, name }
unit_built server + client A missile or a ship was built. missile: { kind = "missile", slot, tier, variant }; ship: { kind = "ship", ship, slot, uid }
weapon_fire server cancel A superweapon is about to fire at island target. Return false to refuse it. by is a player name or "bot". { weapon, target, by }
weapon_fired server + client The lock-on began. { weapon, from, to, level, seconds }
weapon_landed server + client The strike hit. weapon is "ion" for the Ion cannon. { weapon, from, to, level, knocked, destroyed }
island_wiped server + client Every building on an island is down at once. { from, to, cash }
silo_broken server + client The Silo broke. {}
ui_open client A game sheet opened (screen is its name), or the pause menu ("pause"). In a running match only. { screen }
save_loaded server Your saved data is back: mod.save.get works. Fires at start, before ready. Single player only. { mods }
save_saving server Just before mod data is written (also once at start). {}

Limits: a handler that errors 5 times is switched off; one that runs over 4 ms 3 times in a row is switched off. An event with no listener costs the game one table lookup.