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

require("stdlib/event/event")

Functions

dispatch (event)	Calls the handlers that are registered to the given event.
register (event_ids, handler)	Registers a handler for the given events.
remove (event_ids, handler)	Removes a handler from the given events.

Tables

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

Functions

# 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

# register (event_ids, handler)

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_ids parameter takes in either a single, multiple, or mixture of defines.events, int, and string.

Parameters:

• event_ids : (defines.events, int, string, or {defines.events, int, string,...})
• handler : (function) the function to call when the given events are triggered

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) print event.tick end)
-- Create an event that prints the new ID of a train.
Event.register(Trains.on_train_id_changed, function(event) print(event.new_id) end)
-- Function call chaining
Event.register(event1, handler1).register(event2, handler2)

# remove (event_ids, handler)

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_ids parameter takes in either a single, multiple, or mixture of defines.events, int, and string.

Parameters:

• event_ids : (defines.events, int, string, or {defines.events, int, string,...})
• handler : (function) the handler to remove

Returns:

• (Event) Event module object allowing for call chaining

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)