Syntax sugar for event manipulation.
Along with the list of functions below, this module dynamically generates syntax-shortcuts for all defines.events events. These shortcuts are only to be used when registering a handler to a single event. To register a handler to multiple events, use event.register.
To use a shortcut, replace event.register(defines.events.on_built_entity, handler, filters)
with
event.on_built_entity(handler, filters)
. You can also deregister the handler using event.on_built_entity(nil)
.
local event = require("__flib__.event")
on_init(handler) | Register or deregister a handler to be run during mod init. |
on_load(handler) | Register or deregister a handler to be run during mod load. |
on_configuration_changed(handler) | Register or deregister a handler to be run when mod configuration changes. |
on_nth_tick(nth_tick, handler) | Register or deregister a handler to run every N ticks. |
register(ids, handler[, filters]) | Register or deregister a handler to or from an event or group of events. |
register_on_entity_destroyed(entity) | Register an entity to raise on_entity_destroyed when it's destroyed. |
generate_id() | Generate a new, unique event ID. |
get_handler(id) | Retrieve the handler for an event, if one exists. |
raise(id, event_data) | Raise an event as if it were actually called. |
get_order() | Retrieve the mod event order. |
set_filters(ids, filters) | Set the filters for the given event(s). |
get_filters(id) | Retrieve the filters for the given event. |
EventId |
Register or deregister a handler to be run during mod init.
Parameters: Usage:
-- register a handler to run during mod init
event.on_init(function() log("on_init") end)
-- deregister the registered handler, if one exists
event.on_init(nil)
Register or deregister a handler to be run during mod load.
Parameters: Usage:
-- register a handler to run during mod load
event.on_load(function() log("on_load") end)
-- deregister the registered handler, if one exists
event.on_load(nil)
Register or deregister a handler to be run when mod configuration changes.
Parameters: Usage:
-- register a handler to run when mod configuration changes
event.on_configuration_changed(function() log("on_configuration_changed") end)
-- deregister the registered handler, if one exists
event.on_configuration_changed(nil)
Register or deregister a handler to run every N ticks.
Parameters:
nil
to deregister the registered handler.
-- register a handler to run every 30 ticks
event.on_nth_tick(30, function(e) log("30th tick!") end)
-- deregister the registered handler, if one exists
event.on_nth_tick(30, nil)
Register or deregister a handler to or from an event or group of events.
Unlike script.on_event
, event.register
supports adding compatible filters to multiple events at once.
Additionally, event.register
supports registering to custom-inputs and other events simultaneously.
nil
to deregister the registered handler.
-- register a handler to a defines.events event that supports filters
event.register(defines.events.on_built_entity, function(e) log("ghost built!") end, {{filter="ghost"}})
-- register a handler to a custom-input
event.register("my-input", function(e) log("my-input pressed!") end)
-- register a handler to multiple events of different types
event.register({"my-input", defines.events.on_lua_shortcut}, function(e) log("do something!") end)
-- deregister a handler from a single event, if one is registered
event.register("my-input", nil)
-- deregister a handler from multiple events, if one is registered
event.register({"my-input", defines.events.on_lua_shortcut}, nil)
Register an entity to raise on_entity_destroyed
when it's destroyed.
Once an entity is registered it's registered forever (until it's destroyed) and persists through save/load.
Registered is global across all mods: once an entity is registered the event will be fired for all mods when its destroyed.
An entity registered multiple times will only fire the event once and gives back the same registration number.
Depending on when a given entity is destroyed onentitydestroyed will be fired at the end of the current tick or end of the next tick.
Parameters:Generate a new, unique event ID.
Returns:
-- generate a new event ID
local my_event = event.generate_id()
-- raise that event with custom parameters
event.raise(my_event, {whatever_you_want=true, ...})
Retrieve the handler for an event, if one exists.
Parameters:
nil
if one isn't registered.
Raise an event as if it were actually called.
This will only work for events that actually support being raised, and custom mod events.
Parameters: Usage:event.raise(defines.events.on_gui_click, {player_index=e.player_index, element=my_button, ...})
Retrieve the mod event order.
Returns:
Set the filters for the given event(s).
Parameters:
nil
to clear the filters.
-- set the filters for a single event
event.set_filters(defines.events.on_built_entity, {
{filter="ghost"},
{filter="type", type="assembling-machine"}
})
-- set the filters for multiple events that have compatible formats
event.set_filters({defines.events.on_built_entity, defines.events.on_robot_built_entity}, {
{filter="ghost"},
{filter="type", type="assembling-machine"}
})
-- clear event filters if any are set
event.set_filters(defines.events.on_robot_built_entity, nil)
Retrieve the filters for the given event.
Parameters:
nil
if there are none defined.
One of the following: