Events

event.fire(name, ...args)

Send an event to matching script handlers.

Arguments

name: string. Remaining arguments: values for the handler, in order.

Returns

nil.

Works with

Enabled scripts receiving named events.

Missing values and errors

An event is queued, not a direct function call. No listener means no handler runs. A missing or non-string name reports an error.

Also available as: fire_event.

on score_changed(amount) {
    debug.log("Score:", amount)
}
event.fire("score_changed", 25)

object.on_touch = fn(thing) { ... }

React when another object starts touching this object.

Arguments

thing: the contact object handle.

Returns

The callback return value is not used.

Works with

Supported Cell, Actor, and Entity contact callbacks.

Missing values and errors

Not limited to the Player. Entity contact paths supply an Entity; other paths supply the corresponding contact handle.

const coins = find("Coin")
if basket.len(coins) > 0 {
    coins[0].on_touch = fn(thing) {
        debug.log(thing)
    }
}

fn on_overlap(overlapping, cell) { ... }

Receive a supported overlap event.

Arguments

overlapping: bool. cell: contact Cell handle.

Returns

The handler return value is not used.

Works with

Bound Entity script overlap handlers.

Missing values and errors

Requires the matching lifecycle binding; this is not a global function call.

entity Contact {
    fn on_overlap(overlapping, cell) {
        debug.log(overlapping, cell)
    }
}

on.keypress(key, down) { ... }

React to key press and release.

Arguments

key: physical key name string. down: true on press, false on release.

Returns

The handler return value is not used.

Works with

Enabled gameplay scripts.

Missing values and errors

Auto-repeat is suppressed. Focus loss releases held keys.

on.keypress(key, down) {
    if key == "F" && down {
        debug.log("Attack")
    }
}

on navigation_finished(actor) { ... } [BETA]

React when an engine-owned route completes.

Arguments

actor: Actor handle.

Returns

The handler return value is not used.

Works with

Actors using navigate_to().

Missing values and errors

Object callback form takes no arguments. Completion is emitted once per finished route.

Also available as: actor.on_navigation_finished.

on navigation_finished(actor) {
    debug.log("Arrived:", actor.id)
}

on navigation_failed(actor, reason) { ... } [BETA]

React when navigation cannot finish.

Arguments

actor: Actor handle. reason: failure string.

Returns

The handler return value is not used.

Works with

Actors using navigate_to().

Missing values and errors

Object callback form receives only reason. Failure includes no route or stuck movement.

Also available as: actor.on_navigation_failed.

on navigation_failed(actor, reason) {
    debug.log("Route failed:", reason)
}