Event is an event system for the Defold game engine. It provides events, queues, promises, and global messaging using a publish-subscribe pattern. Events are triggered instantly and automatically preserve script context, allowing you to call events from any context.
- Event Management: Create, subscribe, unsubscribe, and trigger events.
- Cross-Context: You can subscribe to events from different scripts.
- Callback Management: Attach callbacks to events with optional data.
- Global Events: Create and subscribe global events that can be triggered from anywhere in your game.
- Queue: Create queue instances to queue events until they are handled by subscribers. Unlike regular events which are immediately processed, queued events are stored in a queue until they are explicitly handled.
- Global Queues: Create and subscribe global queue instances that can be accessed from anywhere in your game.
- Promise: A promise implementation built on top of the event system for asynchronous operations and chaining.
- Logging: Set a logger to log event activities.
Open your game.project file and add the following line to the dependencies field under the project section:
https://github.com/Insality/defold-event/archive/refs/tags/13.zip
Note: The library size is calculated based on the build report per platform Events, Queues, and Promise modules will be included in the build only if you use them.
| Platform | Event Size | Events Size | Queue Size | Queues Size | Promise Size |
|---|---|---|---|---|---|
| HTML5 | 1.68 KB | 0.41 KB | 1.11 KB | 0.49 KB | 1.74 KB |
| Desktop / Mobile | 2.88 KB | 0.71 KB | 2.03 KB | 0.97 KB | 3.22 KB |
Event module can work in 3 modes:
| Mode | Default | Cross-Context | Detailed Tracebacks | Notes |
|---|---|---|---|---|
pcall |
✅ | ✅ | ❌ | Uses pcall function to handle subscribers. |
xpcall |
❌ | ✅ | ✅ | Uses xpcall function to handle subscribers. More memory allocations per event:trigger call. |
none |
❌ | ❌ | ✅ | The error will be thrown as usual Lua error. |
You can set the Event Mode with code:
event.set_mode("pcall")
event.set_mode("xpcall")
event.set_mode("none")Context is the script context where the event is triggered. It can be a GO script or a GUI script in Defold. Without context changing, you can't call gui.set_text from GO script for example.
The context changing is disabled in case of none mode. That means the event callback will be executed in the same context as the event trigger, which can lead to unexpected behavior. With pcall (default) the subscribed callback will be executed in the same context where created.
The xpcall mode is more verbose than pcall mode. It will return a detailed traceback in case of an error in the event callback. But the drawback of it is memory allocations per event:trigger call. Currently, I'm recommending to use pcall mode for production builds and xpcall mode for debugging purposes.
local event = require("event.event")
event.set_logger(logger)
event.set_mode("pcall" | "xpcall" | "none")
local event_instance = event.create([callback], [callback_context])
event_instance:subscribe(callback, [callback_context])
event_instance:unsubscribe(callback, [callback_context])
event_instance:is_subscribed(callback, [callback_context])
event_instance:trigger(...)
event_instance:is_empty()
event_instance:clear()
local events = require("event.events")
events.subscribe(event_id, callback, [callback_context])
events.unsubscribe(event_id, callback, [callback_context])
events.is_subscribed(event_id, callback, [callback_context])
events.trigger(event_id, ...)
events.is_empty(event_id)
events.clear(event_id)
events.clear_all()
local queue = require("event.queue")
local queue_instance = queue.create([handler], [handler_context])
queue_instance:push(data, [on_handle], [context])
queue_instance:subscribe(handler, [context])
queue_instance:unsubscribe(handler, [context])
queue_instance:process(event_handler, [context])
queue_instance:get_events()
queue_instance:clear_events()
queue_instance:clear_subscribers()
queue_instance:is_empty()
queue_instance:has_subscribers()
queue_instance:clear()
local queues = require("event.queues")
queues.push(queue_id, data, [on_handle], [context])
queues.subscribe(queue_id, handler, [context])
queues.unsubscribe(queue_id, handler, [context])
queues.process(queue_id, event_handler, [context])
queues.get_events(queue_id)
queues.clear_events(queue_id)
queues.clear_subscribers(queue_id)
queues.is_empty(queue_id)
queues.has_subscribers(queue_id)
queues.clear(queue_id)
queues.clear_all()
local promise = require("event.promise")
local promise_instance = promise.create([executor])
promise_instance:next([on_resolved], [on_rejected])
promise_instance:catch(on_rejected)
promise_instance:finally(on_finally)
promise_instance:is_pending()
promise_instance:is_resolved()
promise_instance:is_rejected()
promise_instance:is_finished()
-- Create specific promise instances
promise.resolved(value)
promise.rejected(reason)
promise.all(promises)
promise.race(promises)For detailed API documentation, please refer to:
- Event API Reference
- Global Events API Reference
- Queue API Reference
- Global Queues API Reference
- Promise API Reference
Read the Use Cases file to see several examples of how to use the Event module in your Defold game development projects.
This project is licensed under the MIT License - see the LICENSE file for details.
Used libraries:
If you have any issues, questions or suggestions please create an issue.
- Initial release
- Add global events module
- The `event:subscribe` and `event:unsubscribe` now return boolean value of success
- Event Trigger now returns value of last executed callback
- Add `events.is_empty(name)` function
- Add tests for Event and Global Events modules
- Rename `lua_script_instance` to `event_context_manager` to escape conflicts with `lua_script_instance` library
- Fix validate context in `event_context_manager.set`
- Better error messages in case of invalid context
- Refactor `event_context_manager`
- Add `event.set_memory_threshold` function. Works only in debug builds.
- The `event:trigger(...)` can be called as `event(...)` via `__call` metamethod
- Add default pprint logger. Remove or replace it with `event.set_logger()`
- Add tests for context changing
- Optimize memory allocations per event instance
- Localize functions in the event module for better performance
- Optimize memory allocations per event instance
- Default logger now empty except for errors
- Optimize memory allocations per subscription (~35% less)
- Better error tracebacks in case of error in subscription callback
- Update annotations
- The `event:unsubscribe` now removes all subscriptions with the same function if `callback_context` is not provided
- You can use events instead callbacks in `event:subscribe` and `event:unsubscribe`. The subcribed event will be triggered by the parent event trigger.
- Update docs and API reference
- Introduced behavior in the `defer` module. The Defer module provides a queuing mechanism for events. Unlike regular events which are immediately processed, deferred events are stored in a queue until they are explicitly handled by a subscriber. This is useful for events that need to persist until they can be properly handled.
- Add `use_xpcall` option to get detailed tracebacks in case of an error in the event callback.
- Moved detailed API documentation to separate files
- Remove annotations files. Now all annotations directly in the code.
- **MIGRATION**: Replace `require("event.defer")` with `require("event.queues")` in case of using `defer` module
- **BREAKING CHANGE**: Refactored defer system to be instance-based like event system. `defer.lua` now creates defer instances with `defer.create()` instead of global event_id system
- **BREAKING CHANGE**: Renamed `defer` module to `queues` for better clarity
- Removed memory allocation tracking feature
- Added `queues.lua` for global queues operations (renamed from defer.lua functionality)
- Added **Promise** module on top of event module
- Fixed queue event processing order from LIFO to FIFO (events now processed in correct queue order)
- Added no_context_change mode to disable context changing in event callback and using `pcall` by default
- Added `event.set_mode` function to set the event mode
- Added `queue:process_next` function to process exactly one event in the queue with a specific handler (subscribers will not be called)
- Make `promise:resolve` and `promise:reject` public functions
- Added `promise:append` function to append a task to the promise
- Added `promise:tail` and `promise:reset` functions to manage the promise tail
Your donation helps me stay engaged in creating valuable projects for Defold. If you appreciate what I'm doing, please consider supporting me!
