Merge pull request #17 from Insality/develop

Release v14

Author: Insality

.github/workflows/ci_workflow.yml

@@ -14,7 +14,7 @@ jobs:
           - uses: actions/setup-java@v3
             with:
                 distribution: 'zulu'
-                java-version: '21'
+                java-version: '25'
 
           - name: Build && Run
             run: |

.vscode/settings.json

@@ -23,7 +23,6 @@
 	"Lua.completion.autoRequire": false,
 	"Lua.workspace.ignoreDir": [
 		".vscode",
-		"annotations"
 	],
 	"Lua.workspace.library": [
 		"~/Library/Application Support/Code/User/workspaceStorage/ac07c8aee1c361dc3b09cd3c42fcca08/astronachos.defold",

README.md

@@ -30,10 +30,10 @@
 
 Open your `game.project` file and add the following line to the dependencies field under the project section:
 
-**[Defold Event](https://github.com/Insality/defold-event/archive/refs/tags/13.zip)**
+**[Defold Event](https://github.com/Insality/defold-event/archive/refs/tags/14.zip)**
 
 ```
-https://github.com/Insality/defold-event/archive/refs/tags/13.zip
+https://github.com/Insality/defold-event/archive/refs/tags/14.zip
 ```
 
 ### Library Size
@@ -51,38 +51,55 @@ https://github.com/Insality/defold-event/archive/refs/tags/13.zip
 
 Event module can work in 3 modes:
 
-| Mode | Default | Cross-Context | Error Behavior | Tracebacks | Notes |
-| --- | --- | --- | --- | --- | --- |
-| `pcall` | ✅ | ✅ | **Continue on error** | Basic | Errors are logged, other subscribers still run, code after trigger continues. |
-| `xpcall` | ❌ | ✅ | **Continue on error** | Full | Same as pcall but with detailed tracebacks. More memory usage. |
-| `none` | ❌ | ❌ | **Stop on error** | Full | Error stops all execution immediately. No cross-context support. |
+| Mode      | Default | Error Behavior         | Tracebacks | Notes                                                                                       |
+|-----------|:-------:|-----------------------|------------|---------------------------------------------------------------------------------------------|
+| `pcall`   |   ✅    | Continue on error     | Basic      | Errors are logged; other subscribers still run; code after trigger continues.               |
+| `xpcall`  |   ❌    | Continue on error     | Full       | Same as pcall but with detailed tracebacks. More memory usage.                              |
+| `none`    |   ❌    | Stop on error         | Full       | Error stops all execution immediately. Callbacks run with xpcall; error rethrown w/ traceback. |
 
-You can set the Event Mode with code:
-
-```lua
-event.set_mode("pcall")
-event.set_mode("xpcall")
-event.set_mode("none")
-```
 
 ## What is context?
 
 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.
 
-## Error Behavior
 
-**Continue on error** (`pcall` and `xpcall` modes):
-- If one subscriber throws an error, it gets logged but other subscribers still run
-- Code after `event:trigger()` continues executing
+## Basic Usage
+
+```lua
+-- Lua module /my_module.lua
+local event = require("event.event")
+
+local M = {}
+
+-- Create events anywhere
+M.on_value_changed = event.create()
+
+function M.set_value(self, value)
+	M._value = value
+	-- Trigger the event when required to call subscribers
+	M.on_value_changed:trigger(value)
+end
 
-**Stop on error** (`none` mode):
-- If any subscriber throws an error, execution stops immediately
-- No more subscribers are called, code after `event:trigger()` doesn't run
-- **Important limitation**: Cross-context switching is disabled. Callbacks execute in the trigger's context rather than their subscription context, which removes the primary advantage of this event system over standard Lua function calls
+return M
 
-The mode setting is global and affects all events in your project.
+-- Lua script /my_script.script
+local my_module = require("my_module")
 
-**Recommendation**: Use `pcall` for production (safe, fast) and `xpcall` for debugging (detailed errors).
+local function on_value_changed(self, value)
+	print("Value changed to:", value)
+end
+
+function init(self)
+	-- Subscribe to the event when required to call subscribers
+	-- Self is passed as the first parameter to the callback
+	my_module.on_value_changed:subscribe(on_value_changed, self)
+end
+
+function final(self)
+	-- Unsubscribe from the event when the script is destroyed
+	my_module.on_value_changed:unsubscribe(on_value_changed, self)
+end
+```
 
 ## API Reference
 
@@ -94,7 +111,7 @@ event.set_logger([logger])
 event.set_mode("pcall" | "xpcall" | "none")
 
 local object = event.create([callback], [callback_context])
-object(...)
+object(...) -- Alias for object:trigger(...)
 object:trigger(...)
 object:subscribe(callback, [callback_context])
 object:unsubscribe(callback, [callback_context])
@@ -103,7 +120,7 @@ object:is_empty()
 object:clear()
 
 local events = require("event.events")
-events(event_id, ...)
+events(event_id, ...) -- Alias for events.trigger(event_id, ...)
 events.trigger(event_id, ...)
 events.subscribe(event_id, callback, [callback_context])
 events.unsubscribe(event_id, callback, [callback_context])
@@ -121,6 +138,7 @@ For detailed API documentation, please refer to:
 - [Global Queues API](api/queues_api.md)
 - [Promise API](api/promise_api.md)
 
+
 ## Use Cases
 
 Read the [Use Cases](USE_CASES.md) file to see several examples of how to use the Event module in your Defold game development projects.
@@ -219,6 +237,10 @@ If you have any issues, questions or suggestions please [create an issue](https:
 	- Added `promise:append` function to append a task to the promise
 	- Added `promise:tail` and `promise:reset` functions to manage the promise tail
 
+### **V14**
+	- Enable cross-context for "none" event mode
+	- In "none" mode callbacks are run with xpcall; on error, error is rethrown with `error()` (full traceback)
+
 </details>
 
 ## ❤️ Support project ❤️

api/api.md

@@ -8,7 +8,7 @@ event.set_logger(logger)
 event.set_mode("pcall" | "xpcall" | "none")
 
 local object = event.create([callback], [callback_context])
-object(...)
+object(...) -- Alias for object:trigger(...)
 object:trigger(...)
 object:subscribe(callback, [callback_context])
 object:unsubscribe(callback, [callback_context])
@@ -21,7 +21,9 @@ object:clear()
 ```lua
 local events = require("event.events")
 
+events(event_id, ...) -- Alias for events.trigger(event_id, ...)
 events.trigger(event_id, ...)
+events.get(event_id)
 events.subscribe(event_id, callback, [callback_context])
 events.unsubscribe(event_id, callback, [callback_context])
 events.is_subscribed(event_id, callback, [callback_context])

api/event_api.md

@@ -40,7 +40,7 @@ By default, the module uses the `pprint` logger for errors.
 event.set_mode(mode)
 ```
 
-Set the mode of the event module.
+Set the mode of the event module. All modes support cross-context. In "none" mode callbacks run with xpcall; on error, the error is rethrown with full traceback.
 ```lua
 mode:
     | "pcall"

api/events_api.md

@@ -10,6 +10,7 @@ This is particularly useful for events that need to be handled by multiple scrip
 - [trigger](#trigger)
 - [clear](#clear)
 - [clear_all](#clear_all)
+- [get](#get)
 - [subscribe](#subscribe)
 - [unsubscribe](#unsubscribe)
 - [is_subscribed](#is_subscribed)
@@ -61,6 +62,27 @@ Remove all callbacks subscribed to the specified global event.
 ```lua
 events.clear("on_game_over")
 ```
+### get
+
+---
+```lua
+events.get(event_id)
+```
+
+Get an event instance for the specified global event. Creates the event if it does not exist.
+
+- **Parameters:**
+	- `event_id` *(string)*: The id of the global event.
+
+- **Returns:**
+	- `event_instance` *(event)*: An event instance that can be used to subscribe to and trigger the event.
+
+- **Example Usage:**
+
+```lua
+local on_game_over = events.get("on_game_over")
+on_game_over:subscribe(callback, self)
+```
 ### clear_all
 
 ---

event/event.lua

@@ -1,7 +1,7 @@
 local event_mode = sys.get_config_string("event.event_mode", "pcall")
 local USE_XPCALL = event_mode == "xpcall"
 local USE_PCALL = event_mode == "pcall"
-local USE_CONTEXT_CHANGE = USE_PCALL or USE_XPCALL
+local USE_NONE = event_mode == "none"
 
 ---Array of next items: { callback, callback_context, script_context }
 ---@class event.callback_data: table
@@ -70,7 +70,7 @@ end
 function M.set_mode(mode)
 	USE_PCALL = mode == "pcall"
 	USE_XPCALL = mode == "xpcall"
-	USE_CONTEXT_CHANGE = USE_PCALL or USE_XPCALL
+	USE_NONE = mode == "none"
 end
 
 
@@ -120,7 +120,6 @@ end
 function M:subscribe(callback, callback_context)
 	assert(callback, "A function must be passed to subscribe to an event")
 
-	-- If callback is an event, subscribe to it and return
 	if M.is_event(callback) then
 		return self:subscribe(callback.trigger, callback)
 	end
@@ -228,7 +227,7 @@ function M:trigger(...)
 		local event_script_context = callback[3]
 
 		-- Set context for the callback
-		if USE_CONTEXT_CHANGE and current_script_context ~= event_script_context then
+		if current_script_context ~= event_script_context then
 			set_context(event_script_context)
 		end
 
@@ -237,7 +236,7 @@ function M:trigger(...)
 		if event_callback_context then
 			if USE_PCALL then
 				ok, result_or_error = pcall(event_callback, event_callback_context, ...)
-			elseif USE_XPCALL then
+			elseif USE_XPCALL or USE_NONE then
 				local args = { event_callback_context }
 				local n = select("#", ...)
 				for i = 1, n do
@@ -254,7 +253,7 @@ function M:trigger(...)
 		else
 			if USE_PCALL then
 				ok, result_or_error = pcall(event_callback, ...)
-			elseif USE_XPCALL then
+			elseif USE_XPCALL or USE_NONE then
 				local args = {}
 				local n = select("#", ...)
 				for i = 1, n do
@@ -271,15 +270,19 @@ function M:trigger(...)
 		end
 
 		-- Restore context
-		if USE_CONTEXT_CHANGE and current_script_context ~= event_script_context then
+		if current_script_context ~= event_script_context then
 			set_context(current_script_context)
 		end
 
 		-- Handle errors
 		if not ok then
+			if USE_NONE then
+				error(result_or_error, 2)
+			end
+
 			local caller_info = debug.getinfo(2)
 			local place = caller_info.short_src .. ":" .. caller_info.currentline
-			logger:error("Error from trigger event here: " .. place)
+			logger:error("Error from trigger event here: " .. place, 2)
 			logger:error(USE_XPCALL and result_or_error or debug.traceback(result_or_error, 2))
 		end
 

event/events.lua

@@ -105,6 +105,15 @@ function M.is_empty(event_id)
 end
 
 
+---Get a event instance for the specified global event.
+---@param event_id string The id of the global event to get a callback for.
+---@return event event_instance A event instance that can be used to subscribe to and trigger the event.
+function M.get(event_id)
+	M.events[event_id] = M.events[event_id] or Event.create()
+	return M.events[event_id]
+end
+
+
 -- Make the module callable as a shorthand for trigger
 setmetatable(M, {
 	__call = function(_, event_id, ...)

game.project

@@ -13,7 +13,7 @@ input_method = HiddenInputField
 
 [project]
 title = Defold Event
-version = 13
+version = 14
 publisher = Insality
 developer = Maksim Tuprikov, Insality
 dependencies#0 = https://github.com/Insality/defold-log/archive/refs/tags/2.zip

settings_deployer

@@ -2,13 +2,13 @@
 bob_folder=./
 
 # You can point bob version for project in format "filename:sha"
-bob_sha="181:fd1ad4c17bfdcd890ea7176f2672c35102384419"
+bob_sha="1_12_0:3206f699aaff89f357c9d549050b8453e080c5d2"
 
 # Select Defold channel. Values: stable, beta, alpha
 bob_channel="stable"
 
 # If true, it will check and download latest bob version. It will ignore bob_sha param
-use_latest_bob=true
+use_latest_bob=false
 
 # Select Defold build server
 build_server="https://build.defold.com"