Skip to Content
defold-typescript libraries
Insality

Insality/defold-event/event

The Event module, used to create and manage events. Allows to subscribe to events and trigger them.

  • GitHub: Insality/defold-event — pinned to 21
    1. This repo publishes no stable release. Pick a tag from Insality/defold-event tags and add its Source code (zip) URL — for the pinned tag, https://github.com/Insality/defold-event/archive/refs/tags/21.zip — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as event from "event"

Functions

create(callback?: ((...args: any[]) => unknown) | event | undefined, callback_context?: unknown | undefined): event

Generate a new event instance. This instance can then be used to subscribe to and trigger events. The callback function will be called when the event is triggered. The callback_context parameter is optional and will be passed as the first parameter to the callback function. Usually, it is used to pass the self instance. local e = event.create() local e = event.create(function(self) print("ok") end, self)

Parameters

  • callback?: ((...args: any[]) => unknown) | event | undefined — The function to be called when the event is triggered. Or the event instance to subscribe.
  • callback_context?: unknown | undefined — The first parameter to be passed to the callback function.

Returns

  • event — A new event instance.

is_event(value: unknown): boolean

Check if the table is an event instance. if event.is_event(my_value) then my_value:trigger() end

Parameters

  • value: unknown

Returns

  • boolean

set_logger(logger_instance?: event_logger | LuaTable | undefined)

Customize the logging mechanism used by Event module. You can use Defold Log library or provide a custom logger. By default, the module uses the pprint logger for errors.

Parameters

  • logger_instance?: event_logger | LuaTable | undefined — A logger object that follows the specified logging interface, including methods for trace, debug, info, warn, error. Pass nil to remove the default logger.

set_mode(mode: "pcall")

Set the mode of the event module.

Parameters

  • mode: "pcall" — | "xpcall" | "none" The mode to set.

Types

event_logger

event_logger.trace: (logger: event_logger, message: string, data: unknown | undefined) => void

Log a trace message.

event_logger.debug: (logger: event_logger, message: string, data: unknown | undefined) => void

Log a debug message.

event_logger.info: (logger: event_logger, message: string, data: unknown | undefined) => void

Log an info message.

event_logger.warn: (logger: event_logger, message: string, data: unknown | undefined) => void

Log a warning message.

event_logger.error: (logger: event_logger, message: string, data: unknown | undefined) => void

Log an error message.

event

event.subscribe(callback: ((...args: any[]) => unknown) | event, callback_context?: unknown | undefined): boolean

Subscribe a callback to the event or other event. The callback will be invoked whenever the event is triggered. The callback_context parameter is optional and will be passed as the first parameter to the callback function. If the callback with context is already subscribed, the warning will be logged. local function callback(self) print("clicked!") end on_click_event:subscribe(callback, self)

-- Subscribe an event to another event event_1 = event.create(callback) event_2 = event.create() event_2:subscribe(event_1) -- Now event2 will trigger event1

Parameters

  • callback: ((...args: any[]) => unknown) | event — The function to be executed when the event occurs.
  • callback_context?: unknown | undefined — The first parameter to be passed to the callback function.

Returns

  • boolean — True if event is subscribed (Will return false if the callback is already subscribed)

event.subscribe_once(callback: ((...args: any[]) => unknown) | event, callback_context?: unknown | undefined): boolean

Subscribe a callback for a single trigger. After the first trigger the callback is automatically unsubscribed. on_click_event:subscribe_once(function(self) print("one-time click!") end, self)

Parameters

  • callback: ((...args: any[]) => unknown) | event — The function or event to run once.
  • callback_context?: unknown | undefined — Same as subscribe.

Returns

  • boolean — True if subscribed

event.unsubscribe(callback: ((...args: any[]) => unknown) | event, callback_context?: unknown | undefined): boolean

Remove a previously subscribed callback from the event. The callback_context should be the same as the one used when subscribing the callback. If there is no callback_context provided, all callbacks with the same function will be unsubscribed. on_click_event:unsubscribe(callback, self)

Parameters

  • callback: ((...args: any[]) => unknown) | event — The callback function to unsubscribe.
  • callback_context?: unknown | undefined — The first parameter to be passed to the callback function. If not provided, will unsubscribe all callbacks with the same function.

Returns

  • boolean — True if event is unsubscribed

event.is_subscribed(callback: ((...args: any[]) => unknown) | event, callback_context?: unknown | undefined): LuaMultiReturn<[boolean, number | undefined]>

Determine if a specific callback is currently subscribed to the event. The callback_context should be the same as the one used when subscribing the callback. local is_subscribed = on_click_event:is_subscribed(callback, self)

Parameters

  • callback: ((...args: any[]) => unknown) | event — The callback function in question. Or the event instance to check.
  • callback_context?: unknown | undefined — The first parameter to be passed to the callback function.

Returns

  • boolean — True if the callback is subscribed to the event
  • number | undefined — Index of callback in event if subscribed (return first found index)

event.trigger(...args: unknown[]): unknown

Trigger the event, causing all subscribed callbacks to be executed. Any parameters passed to trigger will be forwarded to the callbacks. The return value of the last executed callback is returned. The event:trigger(...) can be called as event(...). on_click_event:trigger("arg1", "arg2")

-- The event can be triggered as a function on_click_event("arg1", "arg2")

Parameters

  • ...args: unknown — Any number of parameters to be passed to the subscribed callbacks.

Returns

  • unknown — Result of the last triggered callback

event.is_empty(): boolean

Check if the event has no subscribed callbacks. local is_empty = on_click_event:is_empty()

Returns

  • boolean — True if the event has no subscribed callbacks

event.clear()

Remove all callbacks subscribed to the event, effectively resetting it. on_click_event:clear()

promise_cancelled_context

promise_cancelled_context.is_cancelled: boolean

promise_cancelled_context.on_cancel: event

promise

promise.next(on_resolved?: ((...args: any[]) => unknown) | promise | event | undefined, on_rejected?: ((...args: any[]) => unknown) | promise | event | undefined, context?: unknown | undefined): promise

Attach resolve and reject handlers to the promise. Returns a new promise that will be resolved or rejected based on the handlers' return values. load_data():next(function(data) return process(data) end):next(display):catch(show_error)

Parameters

  • on_resolved?: ((...args: any[]) => unknown) | promise | event | undefined — Handler called when promise is resolved. If nil, value passes through.
  • on_rejected?: ((...args: any[]) => unknown) | promise | event | undefined — Handler called when promise is rejected. If nil, rejection passes through.
  • context?: unknown | undefined — The context to call the handlers with.

Returns

  • promise — A new promise representing the result of the handlers.

promise.catch(on_rejected: ((...args: any[]) => unknown) | event, context?: unknown | undefined): promise

Attach a rejection handler to the promise. Equivalent to next(nil, on_rejected). load_data():catch(function(err) print("Failed:", err) end)

Parameters

  • on_rejected: ((...args: any[]) => unknown) | event — Handler called when promise is rejected.
  • context?: unknown | undefined — The context to call the handler with.

Returns

  • promise — A new promise representing the result of the handler.

promise.finally(on_finally: ((...args: any[]) => unknown) | event, context?: unknown | undefined): promise

Attach a handler that is called regardless of whether the promise is resolved or rejected. The handler is called with the resolved value or rejection reason. When context is provided, it is passed as the first argument. The handler return value is ignored. load_data():finally(function() hide_loading_spinner() end)

Parameters

  • on_finally: ((...args: any[]) => unknown) | event — Handler called when promise is finished (resolved or rejected).
  • context?: unknown | undefined — The context to call the handler with.

Returns

  • promise — A new promise that resolves/rejects with the same value/reason as the original.

promise.is_pending(): boolean

Check if the promise is in pending state.

Returns

  • boolean — True if the promise is pending.

promise.is_resolved(): boolean

Check if the promise is in resolved state.

Returns

  • boolean — True if the promise is resolved.

promise.is_rejected(): boolean

Check if the promise is in rejected state.

Returns

  • boolean — True if the promise is rejected.

promise.is_finished(): boolean

Check if the promise is finished (either resolved or rejected).

Returns

  • boolean — True if the promise is finished.

promise.is_cancelled(): boolean

Check if the shared cancel_context was cancelled.

Returns

  • boolean — True if the promise chain was cancelled.

promise.resolve(value: unknown)

Resolve the promise. my_promise:resolve(result)

Parameters

  • value: unknown — The value to resolve with.

promise.reject(reason: unknown)

Reject the promise. my_promise:reject("failed")

Parameters

  • reason: unknown — The reason to reject with.

promise.cancel()

Cancel in-progress work in this promise chain. A pending promise is rejected with the cancelled reason and on_cancel runs. A settled promise is left as-is; pending descendants linked via next / append / adopt are still rejected, and they trigger the shared on_cancel. If nothing is still pending, this is a no-op. my_promise:cancel()

promise.append(task: ((value: unknown) => unknown) | promise): promise

Append a task to this promise's internal sequence without reassigning. The task may return a value or a promise. If task is a promise, the pipeline waits for it to finish and adopts its result. The incoming value is not forwarded into task (same as append(function() return task end)). Returns self for chaining. Almost similar to promise = promise:next(task), but without reassigning the promise. pipeline:append(step1) pipeline:append(step2) pipeline:append(step3) local last = pipeline:tail() print("Is going to check status of", last:is_pending())

Parameters

  • task: ((value: unknown) => unknown) | promise

Returns

  • promise

promise.tail(): promise

Get the current tail promise representing all appended work. local last = pipeline:tail() last:next(on_complete)

Returns

  • promise

promise.reset(): promise

Reset the internal sequence to an already resolved promise. pipeline:reset() pipeline:append(new_step)

Returns

  • promise

promise._reject_cancel_children()

Reject pending child promises when a settled promise is cancelled.

promise.state: promise_state

Current state of the promise (pending, resolved, rejected)

promise.value: unknown

The resolved value or rejection reason

promise.on_cancel: event

Event for cancellation cleanup subscriptions (shared across the promise chain)

queue_event_data

queue_event_data.data: unknown

queue_event_data.on_handle: event

queue

queue.push(data: unknown, on_handle?: ((...args: any[]) => unknown) | event | undefined, context?: unknown | undefined)

Push a new event to the queue. The event will exist until it's handled by a subscriber. If there are already subscribers for this queue instance, they will be called immediately. If multiple subscribers handle the event, all subscribers will still be called. The on_handle callback will be called for each subscriber that handles the event. my_queue:push(save_data) my_queue:push(save_data, function() print("saved!") end)

Parameters

  • data: unknown — The data associated with the event.
  • on_handle?: ((...args: any[]) => unknown) | event | undefined — Callback function or event to be called when the event is handled.
  • context?: unknown | undefined — The context to be passed as the first parameter to the on_handle function when the event is handled.

queue.subscribe(handler: ((...args: any[]) => unknown) | event, context?: unknown | undefined): boolean

Subscribe a handler to this queue instance. When an event is pushed to this queue, the handler will be called. If there are already events in the queue, they will be processed immediately. Return a non-nil value from the handler to mark the event as handled and remove it from the queue. local function on_save(self, data) do_save(data) return true end my_queue:subscribe(on_save, self)

Parameters

  • handler: ((...args: any[]) => unknown) | event — The handler function or event to be called when an event is pushed.
  • context?: unknown | undefined — The context to be passed as the first parameter to the handler function.

Returns

  • boolean — True if handler was subscribed successfully

queue.subscribe_once(handler: ((...args: any[]) => unknown) | event, context?: unknown | undefined): boolean

Subscribe a handler until it handles one event. The handler is invoked for each event in the queue until it returns non-nil (handles an event) then it is automatically unsubscribed and will not be invoked again, even if more events remain in the queue. my_queue:subscribe_once(function(self, data) return process(data) end, self)

Parameters

  • handler: ((...args: any[]) => unknown) | event — The handler function or event to be called when an event is pushed.
  • context?: unknown | undefined — The context to be passed as the first parameter to the handler function.

Returns

  • boolean — True if handler was subscribed successfully

queue.unsubscribe(handler: ((...args: any[]) => unknown) | event, context?: unknown | undefined): boolean

Unsubscribe a handler from this queue instance. my_queue:unsubscribe(on_save, self)

Parameters

  • handler: ((...args: any[]) => unknown) | event — The handler function or event to unsubscribe.
  • context?: unknown | undefined — The context that was passed when subscribing.

Returns

  • boolean — True if handler was unsubscribed successfully

queue.is_subscribed(handler: ((...args: any[]) => unknown) | event, context?: unknown | undefined): LuaMultiReturn<[boolean, number | undefined]>

Check if a handler is subscribed to this queue instance. local ok = my_queue:is_subscribed(on_save, self)

Parameters

  • handler: ((...args: any[]) => unknown) | event — The handler function or event to check.
  • context?: unknown | undefined — The context that was passed when subscribing.

Returns

  • boolean — True if handler is subscribed
  • number | undefined — Index of handler if subscribed

queue.process(event_handler: ((...args: any[]) => unknown) | event, context?: unknown | undefined)

Process all events in this queue immediately. Subscribers will not be called in this function. Events can be handled and removed in event handler callback. If event is handled, it will be removed from the queue. my_queue:process(function(self, data) return handle(data) end, self)

Parameters

  • event_handler: ((...args: any[]) => unknown) | event — Specific handler or event to process the events. If this function returns non-nil, the event will be removed from the queue.
  • context?: unknown | undefined — The context to be passed to the handler.

queue.process_next(event_handler?: ((...args: any[]) => unknown) | event | undefined, context?: unknown | undefined): boolean

Process exactly one queued event with a specific handler (subscribers will NOT be called). If the handler returns non-nil the event will be removed from the queue. local handled = my_queue:process_next(function(data) return handle(data) end)

Parameters

  • event_handler?: ((...args: any[]) => unknown) | event | undefined — Specific handler or event to process the event. If this function returns non-nil, the event will be removed from the queue.
  • context?: unknown | undefined — The context to be passed to the handler.

Returns

  • boolean — True if the head event was handled and removed

queue.get_events(): queue_event_data[]

Get all pending events in this queue. for _, event_data in ipairs(my_queue:get_events()) do print(event_data.data) end

Returns

  • queue_event_data[] — A table of pending events.

queue.clear_events()

Clear all pending events in this queue. my_queue:clear_events()

queue.clear_subscribers()

Clear all subscribers from this queue instance. my_queue:clear_subscribers()

queue.is_empty(): boolean

Check if this queue has no pending events. if my_queue:is_empty() then return end

Returns

  • boolean — True if the queue has no pending events

queue.has_subscribers(): boolean

Check if this queue instance has no subscribed handlers. if my_queue:has_subscribers() then my_queue:push(data) end

Returns

  • boolean — True if the queue instance has subscribed handlers

queue.clear()

Remove all events and handlers from this queue instance, effectively resetting it. my_queue:clear()

On this page

Functionscreate(callback?: ((...args: any[]) => unknown) | event | undefined, callback_context?: unknown | undefined): eventis_event(value: unknown): booleanset_logger(logger_instance?: event_logger | LuaTable | undefined)set_mode(mode: "pcall")Typesevent_loggerevent_logger.trace: (logger: event_logger, message: string, data: unknown | undefined) => voidevent_logger.debug: (logger: event_logger, message: string, data: unknown | undefined) => voidevent_logger.info: (logger: event_logger, message: string, data: unknown | undefined) => voidevent_logger.warn: (logger: event_logger, message: string, data: unknown | undefined) => voidevent_logger.error: (logger: event_logger, message: string, data: unknown | undefined) => voideventevent.subscribe(callback: ((...args: any[]) => unknown) | event, callback_context?: unknown | undefined): booleanevent.subscribe_once(callback: ((...args: any[]) => unknown) | event, callback_context?: unknown | undefined): booleanevent.unsubscribe(callback: ((...args: any[]) => unknown) | event, callback_context?: unknown | undefined): booleanevent.is_subscribed(callback: ((...args: any[]) => unknown) | event, callback_context?: unknown | undefined): LuaMultiReturn<[boolean, number | undefined]>event.trigger(...args: unknown[]): unknownevent.is_empty(): booleanevent.clear()promise_cancelled_contextpromise_cancelled_context.is_cancelled: booleanpromise_cancelled_context.on_cancel: eventpromisepromise.next(on_resolved?: ((...args: any[]) => unknown) | promise | event | undefined, on_rejected?: ((...args: any[]) => unknown) | promise | event | undefined, context?: unknown | undefined): promisepromise.catch(on_rejected: ((...args: any[]) => unknown) | event, context?: unknown | undefined): promisepromise.finally(on_finally: ((...args: any[]) => unknown) | event, context?: unknown | undefined): promisepromise.is_pending(): booleanpromise.is_resolved(): booleanpromise.is_rejected(): booleanpromise.is_finished(): booleanpromise.is_cancelled(): booleanpromise.resolve(value: unknown)promise.reject(reason: unknown)promise.cancel()promise.append(task: ((value: unknown) => unknown) | promise): promisepromise.tail(): promisepromise.reset(): promisepromise._reject_cancel_children()promise.state: promise_statepromise.value: unknownpromise.on_cancel: eventqueue_event_dataqueue_event_data.data: unknownqueue_event_data.on_handle: eventqueuequeue.push(data: unknown, on_handle?: ((...args: any[]) => unknown) | event | undefined, context?: unknown | undefined)queue.subscribe(handler: ((...args: any[]) => unknown) | event, context?: unknown | undefined): booleanqueue.subscribe_once(handler: ((...args: any[]) => unknown) | event, context?: unknown | undefined): booleanqueue.unsubscribe(handler: ((...args: any[]) => unknown) | event, context?: unknown | undefined): booleanqueue.is_subscribed(handler: ((...args: any[]) => unknown) | event, context?: unknown | undefined): LuaMultiReturn<[boolean, number | undefined]>queue.process(event_handler: ((...args: any[]) => unknown) | event, context?: unknown | undefined)queue.process_next(event_handler?: ((...args: any[]) => unknown) | event | undefined, context?: unknown | undefined): booleanqueue.get_events(): queue_event_data[]queue.clear_events()queue.clear_subscribers()queue.is_empty(): booleanqueue.has_subscribers(): booleanqueue.clear()