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- 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— togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as event from "event"
- 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,
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 fortrace,debug,info,warn,error. Passnilto 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 eventnumber | 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 subscribednumber | 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()