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

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.
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) 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) 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) 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 : (uint)
  • handler : (function) 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.

Parameters:
  • ids : (EventId or EventId[])
  • handler : (function) 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)
# 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.

Parameters:
  • id : (EventId)
  • event_data : (EventData) 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 uint corresponding to a custom event ID.
  • A string corresponding to a custom-input name.