event module

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).

See also

Usage

local event = require("__flib__.event")

Functions

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.

Concepts

EventId

Functions

# on_init(handler)

Register or deregister a handler to be run during mod init.

Parameters:
  • handler : (function or nil) The handler to register, or nil to deregister the registered handler.
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)
# on_load(handler)

Register or deregister a handler to be run during mod load.

Parameters:
  • handler : (function or nil) The handler to register, or nil to deregister the registered handler.
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)
# on_configuration_changed(handler)

Register or deregister a handler to be run when mod configuration changes.

Parameters:
  • handler : (function or nil) The handler to register, or nil to deregister the registered handler.
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)
# on_nth_tick(nth_tick, handler)

Register or deregister a handler to run every N ticks.

Parameters:
  • nth_tick : (number)
  • handler : (function or nil) The handler to register, or nil to deregister the registered handler.
Usage:
-- 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(ids, handler[, filters])

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.

Parameters:
  • ids : (EventId or EventId[])
  • handler : (function or nil) The handler to register, or nil to deregister the registered handler.
  • filters : (EventFilters) (optional)
Usage:
-- 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_on_entity_destroyed(entity)

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 on_entity_destroyed will be fired at the end of the current tick or end of the next tick.

Parameters:
  • entity : (LuaEntity) The entity to register.
Returns:
  • (number) The registration number.
# generate_id()

Generate a new, unique event ID.

Returns: Usage:
-- 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, ...})
# get_handler(id)

Retrieve the handler for an event, if one exists.

Parameters: Returns:
  • (function) The registered handler, or nil if one isn’t registered.
# raise(id, event_data)

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:
  • id : (EventId)
  • event_data : (table) The event data that will be passed to the handlers.
Usage:
event.raise(defines.events.on_gui_click, {player_index=e.player_index, element=my_button, ...})
# get_order()

Retrieve the mod event order.

Returns:
# set_filters(ids, filters)

Set the filters for the given event(s).

Parameters:
  • ids : (EventId or EventId[])
  • filters : (EventFilters) The filters to set, or nil to clear the filters.
Usage:
-- 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)
# get_filters(id)

Retrieve the filters for the given event.

Parameters: Returns:
  • (EventFilters) filters The filters, or nil if there are none defined.

Concepts

# EventId

One of the following:

  • A member of defines.events.
  • A positive number corresponding to a custom event ID.
  • A string corresponding to a custom-input name.