This Module allows for registering multiple handlers to the same event, overcoming the limitation of script.register.
** Event.add(event_name, handler) **
Handlers added with Event.add must be added at the control stage or in Event.on_init or Event.on_load. Remember that for each player, on_init or on_load is run, never both. So if you can't add the handler in the control stage add the handler in both on_init and on_load. Handlers added with Event.add cannot be removed. For handlers that need to be removed or added at runtime use Event.add_removable.
local Event = require 'utils.event' --- @dep utils.event
Event.add(
defines.events.on_built_entity,
function(event)
game.print(serpent.block(event)) -- prints the content of the event table to console.
end
)
** Event.add_removable(event_name, token) **
For conditional event handlers. Event.add_removable can be safely called at runtime without desync risk.
Only use this if you need to add the handler at runtime or need to remove the handler, otherwise use Event.add
Event.add_removable can be safely used at the control stage or in Event.on_init. If used in on_init you don't
need to also add in on_load (unlike Event.add).
Event.add_removable cannot be called in on_load, doing so will crash the game on loading.
Token is used because it's a desync risk to store closures inside the global table.
local Token = require 'utils.token' --- @dep utils.token
local Event = require 'utils.event' --- @dep utils.event
Token.register must not be called inside an event handler.
local handler =
Token.register(
function(event)
game.print(serpent.block(event)) -- prints the content of the event table to console.
end
)
The below code would typically be inside another event or a custom command.
Event.add_removable(defines.events.on_built_entity, handler)
When you no longer need the handler.
Event.remove_removable(defines.events.on_built_entity, handler)
It's not an error to register the same token multiple times to the same event, however when
removing only the first occurrence is removed.
** Event.add_removable_function(event_name, func) **
Only use this function if you can't use Event.add_removable. i.e you are registering the handler at the console.
The same restrictions that apply to Event.add_removable also apply to Event.add_removable_function.
func cannot be a closure in this case, as there is no safe way to store closures in the global table.
A closure is a function that uses a local variable not defined in the function.
local Event = require 'utils.event' --- @dep utils.event
If you want to remove the handler you will need to keep a reference to it.
global.handler = function(event)
game.print(serpent.block(event)) -- prints the content of the event table to console.
end
The below code would typically be used at the command console.
Event.add_removable_function(defines.events.on_built_entity, global.handler)
When you no longer need the handler.
Event.remove_removable_function(defines.events.on_built_entity, global.handler)
** Other Events **
Use Event.on_init(handler) for script.on_init(handler)
Use Event.on_load(handler) for script.on_load(handler)
Use Event.on_nth_tick(tick, handler) for script.on_nth_tick(tick, handler)
Favour this event over Event.add(defines.events.on_tick, handler)
There are also Event.add_removable_nth_tick(tick, token) and Event.add_removable_nth_tick_function(tick, func)
That work the same as above.
** Custom Scenario Events **
local Event = require 'utils.event' --- @dep utils.event
local event_id = script.generate_event_name()
Event.add(
event_id,
function(event)
game.print(serpent.block(event)) -- prints the content of the event table to console.
end
)
The table contains extra information that you want to pass to the handler.
script.raise_event(event_id, {extra = 'data'})| utils.event_core |
| utils.global |
| utils.token |
| overrides.debug |
| Event.add(event_name, handler) | Register a handler for the event_name event. |
| Event.on_init(handler) | Register a handler for the script.on_init event. |
| Event.on_load(handler) | Register a handler for the script.on_load event. |
| Event.on_nth_tick(tick, handler) | Register a handler for the nth_tick event. |
| Event.add_removable(event_name, token) | Register a token handler that can be safely added and removed at runtime. |
| Event.remove_removable(event_name, token) | Removes a token handler for the given event_name. |
| Event.add_removable_function(event_name, func) | Register a handler that can be safely added and removed at runtime. |
| Event.remove_removable_function(event_name, func) | Removes a handler for the given event_name. |
| Event.add_removable_nth_tick(tick, token) | Register a token handler for the nth tick that can be safely added and removed at runtime. |
| Event.remove_removable_nth_tick(tick, token) | Removes a token handler for the nth tick. |
| Event.add_removable_nth_tick_function(tick, func) | Register a handler for the nth tick that can be safely added and removed at runtime. |
| Event.remove_removable_nth_tick_function(tick, func) | Removes a handler for the nth tick. |
Register a handler for the event_name event.
This function must be called in the control stage or in Event.on_init or Event.on_load. See documentation at top of file for details on using events.
Parameters:Register a handler for the script.on_init event.
This function must be called in the control stage or in Event.on_init or Event.on_load See documentation at top of file for details on using events.
Parameters:Register a handler for the script.on_load event.
This function must be called in the control stage or in Event.on_init or Event.on_load See documentation at top of file for details on using events.
Parameters:Register a handler for the nth_tick event.
This function must be called in the control stage or in Event.on_init or Event.on_load. See documentation at top of file for details on using events.
Parameters:Register a token handler that can be safely added and removed at runtime.
Do NOT call this method during on_load. See documentation at top of file for details on using events.
Parameters:Removes a token handler for the given event_name.
Do NOT call this method during on_load. See documentation at top of file for details on using events.
Parameters:Register a handler that can be safely added and removed at runtime.
The handler must not be a closure, as that is a desync risk. Do NOT call this method during on_load. See documentation at top of file for details on using events.
Parameters:Removes a handler for the given event_name.
Do NOT call this method during on_load. See documentation at top of file for details on using events.
Parameters:Register a token handler for the nth tick that can be safely added and removed at runtime.
Do NOT call this method during on_load. See documentation at top of file for details on using events.
Parameters:Removes a token handler for the nth tick.
Do NOT call this method during on_load. See documentation at top of file for details on using events.
Parameters:Register a handler for the nth tick that can be safely added and removed at runtime.
The handler must not be a closure, as that is a desync risk. Do NOT call this method during on_load. See documentation at top of file for details on using events.
Parameters:Removes a handler for the nth tick.
Do NOT call this method during on_load. See documentation at top of file for details on using events.
Parameters: