Event - is a single file Lua module for the Defold game engine. It provides a simple and efficient way to manage events and callbacks in your game.
- 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.
- Defer: 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
- Logging: Set a logger to log event activities.
- Memory Allocations Tracker: Detects if an event callback causes a huge memory allocations.
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/11.zip
Note: The library size is calculated based on the build report per platform Events and Defer module will be included in the build only if you use them.
| Platform | Event Size | Events Size | Defer Size |
|---|---|---|---|
| HTML5 | 1.85 KB | 0.42 KB | 1.07 KB |
| Desktop / Mobile | 3.14 KB | 0.71 KB | 1.93 KB |
Enabling in game.project
To monitor memory allocations for event callbacks, add to your game.project:
[event]
memory_threshold_warning = 50memory_threshold_warning: Threshold in kilobytes for logging warnings about memory allocations.0disables tracking.
The event memory tracking is not 100% accurate and is used to check unexpected huge leaks in the event callbacks. The memory tracking applied additional memory allocations for tracking purposes.
Memory allocation tracking is turned off in release builds, regardless of the game.project settings.
You can use xpcall to get detailed tracebacks in case of an error in the event callback. Usually, in case of an error, you will get a line with event.trigger and traceback ended in event module. To get a detailed traceback to help with debug, you can use use_xpcall:
[event]
use_xpcall = 1In this case, you will get a detailed traceback with the exact line of the error in the event callback. But the drawback of it is memory allocations per event:trigger call. Should be used only for debugging purposes.
local event = require("event.event")
event.set_logger(logger)
event.set_memory_threshold(threshold)
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 defer = require("event.defer")
defer.push(event_id, data, [on_handle], [context])
defer.subscribe(event_id, handler, [context])
defer.unsubscribe(event_id, handler, [context])
defer.process(event_id, handler, [context])
defer.get_events(event_id)
defer.clear_events(event_id)
defer.clear_subscribers(event_id)
defer.clear_all()For detailed API documentation, please refer to:
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 tests for 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.
Your donation helps me stay engaged in creating valuable projects for Defold. If you appreciate what I'm doing, please consider supporting me!
