Event.Trains module

Tools for working with trains.

When this module is loaded into a mod, it automatically registers a number of new events in order to keep track of the trains as their locomotives and wagons are moved around.

To handle the events, you should use the Event module.

Events

on_train_id_changed	This event fires when a train’s ID changes.

Functions

find_filtered(criteria)	Given a search criteria, search for trains that match the criteria.
get_train_id(train)	Find the ID of a LuaTrain instance.
get_main_locomotive(train)	Get the main locomotive of a train.
to_entity(train)	Creates an entity from a train that is compatible with the Entity.Entity module.
set_data(train, data)	Associates the user data to a train.
get_data(train)	Gets the user data that is associated with a train.
register_events()	This needs to be called to register events for this module

Tables

criteria	This table should be passed into find_filtered to find trains that match the criteria.
train_details	find_filtered returns an array with one or more of this table based on the search criteria.
train_entity	to_entity returns this table.

Events

# on_train_id_changed

This event fires when a train’s ID changes.

The train ID is a property of the main locomotive, which means that when locomotives are attached or detached from their wagons or from other locomotives, the ID of the train changes.

For example: A train with a front and rear locomotives will get its ID from the front locomotive. If the front locomotive gets disconnected, the rear locomotive becomes the main one and the train’s ID changes.

Event Parameters:

• old_id : (uint) the ID of the train before the change
• new_id : (uint) the ID of the train after the change

Usage:

Event.register(Trains.on_train_id_changed, my_handler)

Functions

# find_filtered(criteria)

Given a search criteria, search for trains that match the criteria.

If criteria.surface is not supplied, this function searches through all existing surfaces. If criteria.force is not supplied, this function searches through all existing forces. If criteria.state is not supplied, this function gets trains in any state.

Parameters:

• criteria : (criteria) a table used to search for trains

Returns:

• ({train_details,…}) an array of train IDs and LuaTrain instances

Usage:

Trains.find_filtered({ surface = "nauvis", state = defines.train_state.wait_station })

# get_train_id(train)

Find the ID of a LuaTrain instance.

Parameters:

• train : (LuaTrain)

Returns:

• (uint) the ID of the train

# get_main_locomotive(train)

Get the main locomotive of a train.

Parameters:

• train : (LuaTrain)

Returns:

• (LuaEntity) the main locomotive

# to_entity(train)

Creates an entity from a train that is compatible with the Entity.Entity module.

Parameters:

• train : (LuaTrain)

Returns:

• (train_entity)

# set_data(train, data)

Associates the user data to a train.

This is a helper around Entity.Entity.set_data.

The user data will be stored in the global object and it will persist between loads.

The user data will be removed from a train when the train becomes invalid.

Parameters:

• train : (LuaTrain) the train to set the user data for
• data : (nil or Mixed) the user data to set, or nil to delete the user data associated with the train

Returns:

• (nil or Mixed) the previous user data or nil if the train had no previous user data

# get_data(train)

Gets the user data that is associated with a train.

This is a helper around Entity.Entity.get_data.

The user data is stored in the global object and it persists between loads.

The user data will be removed from a train when the train becomes invalid.

Parameters:

• train : (LuaTrain) the train to look up user data for

Returns:

• (nil or Mixed) the user data, or nil if no user data exists for the train

# register_events()

This needs to be called to register events for this module

Returns:

• (Trains)

Tables

# criteria

This table should be passed into find_filtered to find trains that match the criteria.

Fields:

• surface : (nil, string, {string,...}, LuaSurface or {LuaSurface,...}) the surfaces to look up for the trains (optional)
• force : (nil, string or LuaForce) the force of the trains to search (optional)
• state : (nil or defines.train_state) the state of the trains to search (optional)

# train_details

find_filtered returns an array with one or more of this table based on the search criteria.

Fields:

• train : (LuaTrain) an instance of the train
• id : (uint) the ID of the train

# train_entity

to_entity returns this table.

Fields:

• name : (string) the name of the train entity with the train ID as its suffix
• valid : (boolean) whether or not if the train is in a valid state in the game
• equals : (function) — function(entity) — a function to check if another entity is equal to the train that this table represents