Factorio.com|Forums|Wiki|Mod Portal|API Docs

# Factorio Runtime Docs Version 2.0.77

# LuaTrain - Runtime Docs

## Class LuaTrain

A train. Trains are a sequence of connected rolling stocks -- locomotives and wagons.

## Members

get_item_count(item?) | → uint32 | Get the amount of a particular item stored in the train.
Get the amount of a particular item stored in the train.
get_contents() | → array[ItemWithQualityCount] | Get a mapping of the train's inventory.
Get a mapping of the train's inventory.
remove_item(stack) | → uint32 | Remove some items from the train.
Remove some items from the train.
insert(stack) |  | Insert a stack into the train.
Insert a stack into the train.
clear_items_inside() |  | Clear all items in this train.
Clear all items in this train.
recalculate_path(force?) | → boolean | Checks if the path is invalid and tries to re-path if it isn't.
Checks if the path is invalid and tries to re-path if it isn't.
get_fluid_count(fluid?) | → double | Get the amount of a particular fluid stored in the train.
Get the amount of a particular fluid stored in the train.
get_fluid_contents() | → dictionary[string → FluidAmount] | Gets a mapping of the train's fluid inventory.
Gets a mapping of the train's fluid inventory.
remove_fluid(fluid) | → double | Remove some fluid from the train.
Remove some fluid from the train.
insert_fluid(fluid) | → double | Inserts the given fluid into the first available location in this train.
Inserts the given fluid into the first available location in this train.
clear_fluids_inside() |  | Clears all fluids in this train.
Clears all fluids in this train.
go_to_station(index) |  | Go to the station specified by the index in the train's schedule.
Go to the station specified by the index in the train's schedule.
get_rails() | → array[LuaEntity] | Gets all rails under the train.
Gets all rails under the train.
get_rail_end(direction) | → LuaRailEnd | Gets a LuaRailEnd object pointing away from the train at specified end of the train
Gets a LuaRailEnd object pointing away from the train at specified end of the train
get_schedule() | → LuaSchedule | This allows full access to the train schedule, including modifying the schedule records, the train group and the interrupts.
This allows full access to the train schedule, including modifying the schedule records, the train group and the interrupts.
manual_mode | :: RW boolean | When `true`, the train is explicitly controlled by the player or script. [...]
When `true`, the train is explicitly controlled by the player or script. [...]
speed | :: RW double | Current speed. [...]
Current speed. [...]
max_forward_speed | :: R double | Current max speed when moving forward, depends on locomotive prototype and fuel.
Current max speed when moving forward, depends on locomotive prototype and fuel.
max_backward_speed | :: R double | Current max speed when moving backwards, depends on locomotive prototype and fuel.
Current max speed when moving backwards, depends on locomotive prototype and fuel.
weight | :: R double | The weight of this train.
The weight of this train.
carriages | :: R array[LuaEntity] | The rolling stocks this train is composed of, with the numbering starting at the front of the train.
The rolling stocks this train is composed of, with the numbering starting at the front of the train.
locomotives | :: R table | Locomotives of the train.
Locomotives of the train.
cargo_wagons | :: R array[LuaEntity] | The cargo carriages the train contains.
The cargo carriages the train contains.
fluid_wagons | :: R array[LuaEntity] | The fluid carriages the train contains.
The fluid carriages the train contains.
schedule | :: RW TrainSchedule? | This train's current schedule, if any. [...]
This train's current schedule, if any. [...]
state | :: R defines.train_state | This train's current state.
This train's current state.
front_stock | :: R LuaEntity? | The front stock of this train, if any. [...]
The front stock of this train, if any. [...]
back_stock | :: R LuaEntity? | The back stock of this train, if any. [...]
The back stock of this train, if any. [...]
station | :: R LuaEntity? | The train stop this train is stopped at, if any.
The train stop this train is stopped at, if any.
has_path | :: R boolean | If this train has a path.
If this train has a path.
path_end_rail | :: R LuaEntity? | The destination rail this train is currently pathing to, if any.
The destination rail this train is currently pathing to, if any.
path_end_stop | :: R LuaEntity? | The destination train stop this train is currently pathing to, if any.
The destination train stop this train is currently pathing to, if any.
id | :: R uint32 | The unique train ID.
The unique train ID.
passengers | :: R array[LuaPlayer] | The player passengers on the train This does not index using player index. See LuaPlayer::index on each player instance for the player index.
The player passengers on the train This does not index using player index. See LuaPlayer::index on each player instance for the player index.
riding_state | :: R RidingState | The riding state of this train.
The riding state of this train.
killed_players | :: R dictionary[uint32 → uint32] | The players killed by this train. [...]
The players killed by this train. [...]
kill_count | :: R uint32 | The total number of kills by this train.
The total number of kills by this train.
path | :: R LuaRailPath? | The path this train is using, if any.
The path this train is using, if any.
signal | :: R LuaEntity? | The signal this train is arriving or waiting at, if any.
The signal this train is arriving or waiting at, if any.
group | :: RW string | The group this train belongs to. [...]
The group this train belongs to. [...]
front_end | :: R LuaRailEnd | Front end of the train: Rail and direction on that rail where the train will go when moving forward
Front end of the train: Rail and direction on that rail where the train will go when moving forward
back_end | :: R LuaRailEnd | Back end of the train: Rail and direction on that rail where the train will go when moving backward
Back end of the train: Rail and direction on that rail where the train will go when moving backward
valid | :: R boolean | Is this object valid? [...]
Is this object valid? [...]
object_name | :: R string | The class name of this object. [...]
The class name of this object. [...]

## Methods

### get_item_count(item?) → uint32

Get the amount of a particular item stored in the train.

#### Parameters

item | :: ItemFilter? | If not given, counts all items.
If not given, counts all items.

### get_contents() → array[ItemWithQualityCount]

Get a mapping of the train's inventory.

#### Return values

→ array[ItemWithQualityCount] | List of all items in the train.

### remove_item(stack) → uint32

Remove some items from the train.

#### Parameters

stack | :: ItemStackIdentification | The amount and type of items to remove
The amount and type of items to remove

#### Return values

→ uint32 | Number of items actually removed.

### insert(stack)

Insert a stack into the train.

#### Parameters

stack | :: ItemStackIdentification |

### clear_items_inside()

Clear all items in this train.

### recalculate_path(force?) → boolean

Checks if the path is invalid and tries to re-path if it isn't.

#### Parameters

force | :: boolean? | Forces the train to re-path regardless of the current path being valid or not.
Forces the train to re-path regardless of the current path being valid or not.

#### Return values

→ boolean | If the train has a path after the repath attempt.

### get_fluid_count(fluid?) → double

Get the amount of a particular fluid stored in the train.

#### Parameters

fluid | :: string? | Fluid name to count. If not given, counts all fluids.
Fluid name to count. If not given, counts all fluids.

### get_fluid_contents() → dictionary[string → FluidAmount]

Gets a mapping of the train's fluid inventory.

#### Return values

→ dictionary[string → FluidAmount] | The counts, indexed by fluid names.

### remove_fluid(fluid) → double

Remove some fluid from the train.

#### Parameters

fluid | :: Fluid |

#### Return values

→ double | The amount of fluid actually removed.

### insert_fluid(fluid) → double

Inserts the given fluid into the first available location in this train.

#### Parameters

fluid | :: Fluid |

#### Return values

→ double | The amount inserted.

### clear_fluids_inside()

Clears all fluids in this train.

### go_to_station(index)

Go to the station specified by the index in the train's schedule.

#### Parameters

index | :: uint32 |

### get_rails() → array[LuaEntity]

Gets all rails under the train.

### get_rail_end(direction) → LuaRailEnd

Gets a LuaRailEnd object pointing away from the train at specified end of the train

#### Parameters

direction | :: defines.rail_direction |

### get_schedule() → LuaSchedule

This allows full access to the train schedule, including modifying the schedule records, the train group and the interrupts.

## Attributes

### manual_mode :: Read|Write boolean

When `true`, the train is explicitly controlled by the player or script. When `false`, the train moves autonomously according to its schedule.

### speed :: Read|Write double

Current speed.

Changing the speed of the train is potentially an unsafe operation because train uses the speed for its internal calculations of break distances, etc.

### max_forward_speed :: Read double

Current max speed when moving forward, depends on locomotive prototype and fuel.

### max_backward_speed :: Read double

Current max speed when moving backwards, depends on locomotive prototype and fuel.

### weight :: Read double

The weight of this train.

### carriages :: Read array[LuaEntity]

The rolling stocks this train is composed of, with the numbering starting at the front of the train.

### locomotives :: Read table

Locomotives of the train.

#### Table fields

front_movers | :: array[LuaEntity] | Array of locomotives.
Array of locomotives.
back_movers | :: array[LuaEntity] | Array of locomotives.
Array of locomotives.

#### Example

    -- called on a LuaTrain with 3 locomotives, it returns 3 LuaEntities:
    train.locomotives -- => {front_movers = {loco1, loco2}, back_movers = {loco3}}

### cargo_wagons :: Read array[LuaEntity]

The cargo carriages the train contains.

### fluid_wagons :: Read array[LuaEntity]

The fluid carriages the train contains.

### schedule :: Read|Write TrainSchedule?

This train's current schedule, if any. Set to `nil` to clear.

The schedule can't be changed by modifying the returned table. Instead, changes must be made by assigning a new table to this attribute.

This is a simiplifed schedule that does not include train groups and interrupts. See LuaTrain::get_schedule for full access to the train schedule, including interrupts and train groups.

### state :: Read defines.train_state

This train's current state.

### front_stock :: Read LuaEntity?

The front stock of this train, if any. The front of the train is in the direction that a majority of locomotives are pointing in. If it's a tie, the North and West directions take precedence.

### back_stock :: Read LuaEntity?

The back stock of this train, if any. The back of the train is at the opposite end of the front.

### station :: Read LuaEntity?

The train stop this train is stopped at, if any.

### has_path :: Read boolean

If this train has a path.

### path_end_rail :: Read LuaEntity?

The destination rail this train is currently pathing to, if any.

### path_end_stop :: Read LuaEntity?

The destination train stop this train is currently pathing to, if any.

### id :: Read uint32

The unique train ID.

### passengers :: Read array[LuaPlayer]

The player passengers on the train

This does not index using player index. See LuaPlayer::index on each player instance for the player index.

### riding_state :: Read RidingState

The riding state of this train.

### killed_players :: Read dictionary[uint32 → uint32]

The players killed by this train.

The keys are the player indices, the values are how often this train killed that player.

### kill_count :: Read uint32

The total number of kills by this train.

### path :: Read LuaRailPath?

The path this train is using, if any.

### signal :: Read LuaEntity?

The signal this train is arriving or waiting at, if any.

### group :: Read|Write string

The group this train belongs to.

Setting the group will apply the schedule of the group to this train.

### front_end :: Read LuaRailEnd

Front end of the train: Rail and direction on that rail where the train will go when moving forward

### back_end :: Read LuaRailEnd

Back end of the train: Rail and direction on that rail where the train will go when moving backward

### valid :: Read boolean

Is this object valid? This Lua object holds a reference to an object within the game engine. It is possible that the game-engine object is removed whilst a mod still holds the corresponding Lua object. If that happens, the object becomes invalid, i.e. this attribute will be `false`. Mods are advised to check for object validity if any change to the game state might have occurred between the creation of the Lua object and its access.

### object_name :: Read string

The class name of this object. Available even when `valid` is false. For LuaStruct objects it may also be suffixed with a dotted path to a member of the struct.

Class used in

- LuaEntity::get_train_stop_trains()
- LuaEntity::get_stopped_train()
- LuaEntity::train
- LuaSchedule::owner
- LuaTrainManager::get_train_by_id()
- LuaTrainManager::get_trains()
- LuaTrainManager::request_train_path()
- RegistrationTarget
- on_train_changed_state
- on_train_created
- on_train_schedule_changed