Events
Look up events calls and properties.
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")
}
}observe.property(handle, name, callback) [BETA]
Watch a supported property and call a function when it changes.
- Arguments
Live Actor, Cell, Light or Entity handle; property name string; function callback taking old and new values.
- Returns
Positive numeric subscription ID.
- Works with
Live engine objects.
- Missing values and errors
Invalid handles, unreadable properties, callbacks or excessive subscriptions report errors.
Callbacks are delivered after script execution; maximum 1024 subscriptions.
const door = proj.find("Door")
if door != nil {
const token = observe.property(door, "visible", fn(old_value, new_value) {
debug.log(new_value)
})
}observe.cancel(subscription_id) [BETA]
Stop a property-change subscription.
- Arguments
Positive whole-number token returned by observe.property.
- Returns
Boolean; true if a subscription was removed.
- Works with
Runtime observers.
- Missing values and errors
Zero, fractional and nonfinite tokens report errors.
const door = proj.find("Door")
if door != nil {
const token = observe.property(door, "visible", fn(old_value, new_value) {
debug.log(new_value)
})
observe.cancel(token)
}