Skip to content
AEOWUN
Docs Menu

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")
    }
}

on navigation_finished(actor) { ... }

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) { ... }

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)
}

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)
}