Event.Event module

Makes working with events in Factorio a lot more simple.

By default, Factorio allows you to register only one handler to an event.

This module lets you easily register multiple handlers to an event.

Using this module is as simple as replacing script.on_event with Event.register.

Due to the way that Factorio’s event system works, it is not recommended to intermingle script.on_event and Event.register in a mod.
This module hooks into Factorio’s event system, and using script.on_event for the same event will change which events are registered.

This module does not have many of the multiplayer protections that script.on_event does.
Due to this, great care should be taken when registering events conditionally.

Usage

local Event = require('__stdlib__/stdlib/event/event')

Functions

register(event_id, handler[, filter=nil][, pattern=nil][, options=nil])	Registers a handler for the given events.
remove(event_id[, handler][, filter][, pattern])	Removes a handler from the given events.
on_load(...)	Shortcut for Event.register(Event.core_events.on_load, function)
on_configuration_changed(...)	Shortcut for Event.register(Event.core_events.on_configuration_changed, function)
on_init(...)	Shortcut for Event.register(Event.core_events.on_init, function)
on_nth_tick(nth_tick, ...)	Shortcut for Event.register(-nthTick, function)
on_event()	Shortcut for Event.register(defines.events, function)
dispatch(event)	Calls the handlers that are registered to the given event.
generate_event_name(event_name)	Retrieve or Generate an event_name and store it in Event.custom_events
get_event_handler(event_id)	Get event handler.
set_protected_mode(bool)	Set protected mode.
set_debug_mode(bool)	Set debug mode default for Event module.
set_option(option, bool)	Set default options for the event module.

Tables

event_data	The user should create a table in this format, for a table that will be passed into Event.dispatch.

Functions

# register(event_id, handler[, filter=nil][, pattern=nil][, options=nil])

Registers a handler for the given events.

If a nil handler is passed, remove the given events and stop listening to them.

Events dispatch in the order they are registered.

An event ID can be obtained via defines.events, script.generate_event_name which is in int, and can be a custom input name which is in string.

The event_id parameter takes in either a single, multiple, or mixture of defines.events, int, and string.

Parameters:

• event_id : (defines.events, int, string, or {defines.events, int, string,…})
• handler : (function) the function to call when the given events are triggered
• filter : (function) a function whose return determines if the handler is executed. event and pattern are passed into this (default: nil)
• pattern : (mixed) an invariant that can be used in the filter function, passed as the second parameter to your filter (default: nil)
• options : (table) a table of options that take precedence over the module options. (default: nil)

Returns:

• (Event) Event module object allowing for call chaining

Usage:

-- Create an event that prints the current tick every tick.
Event.register(defines.events.on_tick, function(event) game.print(event.tick) end)
-- Register something for Nth tick using negative numbers.
Event.register(-120, function() game.print('Every 120 ticks') end
-- Function call chaining
Event.register(event1, handler1).register(event2, handler2)

# remove(event_id[, handler][, filter][, pattern])

Removes a handler from the given events.

When the last handler for an event is removed, stop listening to that event.

An event ID can be obtained via defines.events, script.generate_event_name which is in int, and can be a custom input name which is in string.

The event_id parameter takes in either a single, multiple, or mixture of defines.events, int, and string.

Parameters:

• event_id : (defines.events, int, string, or {defines.events, int, string,…})
• handler : (function) the handler to remove, if not present remove all registered handlers for the event_id (optional)
• filter : (function) (optional)
• pattern : (mixed) (optional)

Returns:

• (Event) Event module object allowing for call chaining

# on_load(...)

Shortcut for Event.register(Event.core_events.on_load, function)

Parameters:

• ...

Returns:

• (Event) Event module object allowing for call chaining

# on_configuration_changed(...)

Shortcut for Event.register(Event.core_events.on_configuration_changed, function)

Parameters:

• ...

Returns:

• (Event) Event module object allowing for call chaining

# on_init(...)

Shortcut for Event.register(Event.core_events.on_init, function)

Parameters:

• ...

Returns:

• (Event) Event module object allowing for call chaining

# on_nth_tick(nth_tick, ...)

Shortcut for Event.register(-nthTick, function)

Parameters:

• nth_tick
• ...

Returns:

• (Event) Event module object allowing for call chaining

# on_event()

Shortcut for Event.register(defines.events, function)

Returns:

• (Event) Event module object allowing for call chaining

# dispatch(event)

Calls the handlers that are registered to the given event.

Abort calling remaining handlers if any one of them has invalid userdata.

Handlers are dispatched in the order they were created.

Parameters:

• event : (event_data) the event data table

See also:

• Invalid Event Objects

# generate_event_name(event_name)

Retrieve or Generate an event_name and store it in Event.custom_events

Parameters:

• event_name : (string) the custom name for your event.

Returns:

• (int) the id associated with the event.

Usage:

Event.register(Event.generate_event_name("my_custom_event"), handler)

# get_event_handler(event_id)

Get event handler.

Parameters:

• event_id

# set_protected_mode(bool)

Set protected mode.

Parameters:

• bool

# set_debug_mode(bool)

Set debug mode default for Event module.

Parameters:

• bool

# set_option(option, bool)

Set default options for the event module.

Parameters:

• option
• bool

Tables

# event_data

The user should create a table in this format, for a table that will be passed into Event.dispatch.

In general, the user should create an event data table that is in a similar format as the one that Factorio returns.

The event data table MUST have either name or input_name.

Fields:

• name : (int or defines.events) unique event ID generated with script.generate_event_name OR defines.events (optional)
• input_name : (string) custom input name of an event (optional)
• ... : any # of additional fields with extra data, which are passed into the handler registered to an event that this table represents (optional)

Usage:

-- below code is from Trains module.
-- old_id & new_id are additional fields passed into the handler that's registered to Trains.on_train_id_changed event.
local event_data = {
old_id = renaming.old_id,
new_id = renaming.new_id,
name = Trains.on_train_id_changed
}
Event.dispatch(event_data)