Events

Events are how the runtime hands control to your script. An event declaration looks like a function but is named for a runtime-defined event and is invoked by the runtime, never by your code.

event frame(frame_num: i32) {
    // runs once per frame
}

Events are a first-class language feature, distinct from functions:

• The runtime invokes events, not your code. A script can't call its own event handlers.
• Registration is declaration. Declaring event frame registers it. There's no register() call.
• Top-level only, like functions. Events can't be nested.

The parameters of an event are whatever the runtime supplies for it. Each event is permitted only in a specific role; declaring a server event in client (or vice versa) is an error.

The events

Client events

Event	Signature	Fires when
frame	(frame_num: i32)	once per emulator frame
receive	(data: u8[])	bytes arrive from the server
input	(button: i32, pressed: bool)	a button changes state
fetch_error	(url: string, msg: string)	an HTTP fetch failed (optional)
db_error	(op, namespace, key, msg: string)	a persistence op hit trouble (optional)

event frame is the client heartbeat. On emulator-backed clients it fires at the moment the game commits its sprite state for the frame, so every memory read inside reflects exactly the state the game just drew with. frame_num counts up from 0.

Server events

Event	Signature	Fires when
tick	(tick_num: i32)	periodically (the server heartbeat)
receive	(from: client, data: u8[])	a client sends bytes
connect	(client: client, handoff: u8[])	a client joins
disconnect	(client: client)	a client leaves
receive_from	(from_url: string, data: u8[])	another instance sends bytes
db_error	(op, namespace, key, msg: string)	a persistence op hit trouble (optional)

event tick is the server heartbeat, analogous to event frame. Its rate is configurable — see Server & slots.

Where each event is documented in depth

• frame / input → Input and the Learn path
• receive (both sides), receive_from → Networking and Instances
• tick, connect, disconnect → Server & slots
• db_error → Persistence
• fetch_error → Fetch