StdLib.Event.Trains

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.

Methods10

function Trains.find_filtered(criteria: StdLib.Event.Trains.criteria | nil) -> any

Given a @{criteria|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 @{defines.train_state|state}.

Parameters

criteriaStdLib.Event.Trains.criteria | nil: a table used to search for trains @return ({@{train_details},...}) an array of train IDs and LuaTrain instances @usage Trains.findfiltered({ surface = "nauvis", state = defines.trainstate.wait_station })

Returns

any

function Trains.get_train_id(train: LuaTrain) -> uint | nil

Find the ID of a LuaTrain instance.

Parameters

trainLuaTrain

Returns

uint | nil: the ID of the train

function Trains._on_locomotive_changed() -> nil

Event fired when some change happens to a locomotive. @lfunction

function Trains.get_main_locomotive(train: LuaTrain) -> LuaEntity | nil

Get the main locomotive of a train.

Parameters

trainLuaTrain

Returns

LuaEntity | nil: the main locomotive

function Trains.to_entity(train: LuaTrain) -> table

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

function Trains.set_data(train: LuaTrain, data: any) -> any

Associates the user data to a train. This is a helper around @{Entity.Entity.set_data}. The user data will be stored in the storage object and it will persist between loads.

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

Parameters

trainLuaTrain: the train to set the user data for
dataany: the user data to set, or nil to delete the user data associated with the train

Returns

any: the previous user data or nil if the train had no previous user data

function Trains.get_data(train: LuaTrain) -> any

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 storage object and it persists between loads.

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

Parameters

trainLuaTrain: the train to look up user data for

Returns

any: the user data, or nil if no user data exists for the train

function Trains.create_train_registry() -> any

Creates a registry of known trains. @return table a mapping of train id to LuaTrain object

function Trains.on_train_created(event) -> nil

function Trains.register_events() -> StdLib.Event.Trains

This needs to be called to register events for this module

Fields3

Trains.__class: string = "Trains"

Trains.__index : unknown

Trains.on_train_id_changed : defines.events

Event ID fired when a train's ID changes. A train's ID is derived from its main locomotive, so attaching or detaching locomotives can cause the ID to change.

@usage Event.register(Trains.ontrainidchanged, myhandler)