util.event.on
Shared
Registers a handler function for the specified event
Syntax
local status = util.event.on(
name,
exec,
config = nil
)The thread instance is only available inside async handlers.
- When
async = true— handler runs inside a dedicated thread; thread can be accessed viautil.thread.current(). - When
async = false— handler runs inline on the calling thread.
Parameters
| Type | Name | Description |
|---|---|---|
string | name | Name of the event to subscribe to |
function | exec | Handler function to invoke when the event fires |
table | config | Configuration table Refer Config section |
Returns
| Type | Name | Description |
|---|---|---|
bool | status | true on successful registration, false otherwise |
Config
| Type | Key | Default | Description |
|---|---|---|---|
bool | async | false | • When true - runs the handler inside a dedicated thread• When false - runs the handler inline on the calling thread |
int | subscription_limit | nil | Maximum number of times this handler will fire before being automatically removed • Must be >= 1 if set• Omit for unlimited invocations |
int | priority | 0 | Determines fire order relative to other handlers on the same event • Higher values fire earlier, similar to a z-index • Handlers with equal priority fire in registration order • May be negative |
Callback: exec
exec(...)| Type | Name | Description |
|---|---|---|
any | ... | Arguments forwarded from the emitting call |
Examples
util.event.on("on_player_join", function(player)
core.engine.print("info", "Player joined:", player)
end)util.event.on("on_pickup_collected", function(pickup)
core.engine.print("info", "Collected:", pickup)
end, { subscription_limit = 1 })util.event.on("on_round_start", function()
local thread = util.thread.current()
core.engine.print("info", "Round started, waiting 5 seconds...")
thread:sleep(5000)
core.engine.print("info", "5 seconds elapsed")
end, { async = true })util.event.on("sandbox:draw", function()
core.engine.print("info", "Fires first - highest priority")
end, { priority = 10 })
util.event.on("sandbox:draw", function()
core.engine.print("info", "Fires second - default priority")
end)
util.event.on("sandbox:draw", function()
core.engine.print("info", "Fires last - lowest priority")
end, { priority = -10 })