Car

Car objects represent rolling stock in the game world. Get them from World methods like getCars(), placeTrain(), or getSelectedCar(). They are also passed to UI extension builder functions.

Locomotives are returned as BaseLocomotive, which extends Car with everything in Locomotive Controls below.

Properties

`air`

CarAir

Air brake state — see Air Brakes below.

`carType`

string

AAR car type code (e.g. "XM").

`components`

ComponentIndex

Access to definition components by id.

var comp = car.components["SomeComponentId"]

See also Styling below for querying components by style selector instead of id.

`isLocomotive`

bool

Whether this car is a locomotive. When true, the car is a BaseLocomotive and exposes Locomotive Controls.

`loadInfo`

CarLoadInfo[]

Load slot information, indexed to match the car definition’s load slots (car.loadInfo[0], car.loadInfo[1], …). A slot with no load information is null. See CarLoadInfo below.

`locationFront`

Location

Track location of the front end.

`locationRear`

Location

Track location of the rear end.

`name`

string

Display name: the reporting mark and road number (e.g. "ALW 600").

`properties`

Properties

Per-car key-value store (persists across saves, syncs in multiplayer). Indexed by string key — see Key-Value Properties below.

`roadNumber`

string

String road number (e.g. "600").

`speedMph`

float

Current speed in MPH (read/write). Positive is toward the front. Setting this also updates coupled cars’ velocity.

`waybill`

Waybill?

Current waybill (read/write). Assign null to clear it.

Key-Value Properties

car.properties["customize.option"] = true
var value = car.properties["customize.option"] ?? false

Reading a key that has never been set returns null, so ?? is the usual way to supply a default.

car.properties is a Properties object — see that page for observe() (react to changes).

Methods

CarEnd identifies an end of the car and is used by getLocation() and the coupling methods below. F/R are the car’s physical ends; A/B are its logical ends, which stay fixed to the car regardless of which physical end currently faces which direction. Unlike other enums, its cases are uppercase, matching the end labels shown in the game.

Value	Description
`CarEnd.F`	Physical front end
`CarEnd.R`	Physical rear end
`CarEnd.A`	Logical end A
`CarEnd.B`	Logical end B

`follow()`

Set the camera to follow this car.

`getLocation(carEnd)`

→ Location

carEnd CarEnd Which end to get the location of

Returns the track location at the specified end.

from railroader import CarEnd
var loc = car.getLocation(CarEnd.A)

`select()`

Select this car (as if clicked).

`stopped(duration)`

→ bool

duration float Minimum stopped duration in seconds

Returns true if the car has been stopped for at least duration seconds.

Coupling

`getAirOpenCars(carEnd)`

→ Car[]

carEnd CarEnd? = null Direction to walk; defaults to logical end A

Returns a list of all cars in the direction of carEnd that are connected by an open air line (anglecocks open at every coupling in between), not including this car. Useful for reasoning about brake line continuity.

`getCoupledCar(carEnd)`

→ Car?

carEnd CarEnd Which end to check

Returns the car coupled at the specified end, or null.

`getCoupledCars(carEnd)`

→ Car[]

carEnd CarEnd? = null Direction to walk; defaults to logical end A

Returns a list of all cars coupled in the direction of carEnd, in order, not including this car.

`isCoupled(carEnd)`

→ bool

carEnd CarEnd Which end to check

Returns true if coupled at the specified end.

`setAnglecock(carEnd, value)`

carEnd CarEnd Which end's anglecock to set

value float 0.0 = closed, 1.0 = open

Set the anglecock at the specified end.

`uncouple(carEnd)`

carEnd CarEnd Which end to uncouple

Uncouple at the specified end by pulling the cut lever.

Loads

`getLoadPercent(loadId)`

→ float

loadId string

Returns the fill percentage (0.0 to 1.0) for a load.

`hasLoad(loadId)`

→ bool

loadId string

Returns true if the car has a nonzero quantity of the specified load.

`setLoadPercent(loadId, percent)`

loadId string

percent float Fill percentage, 0.0 to 1.0

Set the fill percentage for a load. Throws if the load can’t be applied to this car.

CarLoadInfo

Each element of loadInfo describes one load slot:

Property	Type	Description
`load`	Load?	The load occupying this slot, or `null` if empty
`quantity`	float	Quantity currently in this slot

Load

Identifies the load in a load slot:

Property	Type	Description
`id`	string	The load’s identifier, e.g. `rr/coal`
`name`	string	Display name

`asString()`

→ string

Returns the load’s display name (same as name).

The remaining fields of a Load definition — units, density, costPerUnit, carTypeFilter, and the rest — are not yet reachable from Relay; an API for reading load definitions has not been added.

Passengers

These methods throw ArgumentException if the car is not a passenger car.

`addPassengers(originId, destinationId, count)`

originId string

destinationId string

count int

Add passengers to this car.

`getPassengerCount(destinationId)`

→ int

destinationId string

Returns the number of passengers headed to a destination.

`hasPassengerDestination(destinationId)`

→ bool

destinationId string

Returns true if the destination is set.

`removePassengers(destinationId, count)`

destinationId string

count int

Remove up to count passengers headed to a destination.

`setPassengerDestination(destinationId, enabled)`

destinationId string

enabled bool

Enable or disable a passenger destination on this car.

Auto Destinations

`setAutoDestination(loadOrEmpty, destinationId)`

→ bool

loadOrEmpty string "load" or "empty"

destinationId string? Destination identifier, or null to clear

Set the automatic destination for this car. Returns true on success. Throws ArgumentException if loadOrEmpty isn’t "load"/"empty" or the destination can’t be resolved.

Styling

Component style selectors use the grammar Element.class, e.g. "Renderer.body" (element Renderer, class body), ".body" (class only), "Renderer" (element only), or "#left-herald" (id only).

`getComponentsForStyle(selector)`

→ Component[]

selector string Style selector, e.g. Renderer.body, .body, Renderer, or #left-herald

Returns the component proxies matching a style selector, regardless of hydration state. Material operations on a returned proxy require the car’s model to be loaded. An unmatched or empty selector returns an empty array.

`resolveStyle(selector)`

→ any?

selector string Style selector, e.g. Renderer.body

Returns the merged (base style + inline overrides) property bundle for a style selector as a key-value map, e.g. to read a zone color set via the in-game Customize UI. Returns null if the car has no style, the style can’t be resolved, or nothing matches the selector.

Air Brakes

The air property exposes brake pressure readings:

Property	Type	Description
`air.brakeCylinder`	float	Brake cylinder pressure
`air.brakeLine`	float	Brake line pressure

Events

`observe(carEvent, callback)`

→ Disposable

carEvent CarEvent Event to subscribe to

callback (any) => void Called when the event fires

Subscribe to car events. Returns a disposable — call dispose() to unsubscribe.

from railroader import CarEvent

var sub = car.observe(CarEvent.coupledDidChange, (arg) => {
    print("Coupling changed!")
})

// Later:
sub.dispose()

Available events:

Event	Description
`CarEvent.coupledDidChange`	Car coupled or decoupled
`CarEvent.visibleDidChange`	Car visibility changed
`CarEvent.isNearbyDidChange`	Car nearby state changed
`CarEvent.didLoadModels`	Car models finished loading