Engine Function Reference

Function Names

Function names can be either:
  1. function
  2. *:function
  3. name:function
Function is the function to call; name is a name of an entity/child entity and * means entity and all child entities for (a) just the owning entity is searched for a matching function, (b) the owning entity and all descendants are searched, function is called the first component that implements the function and (c) A search is made of the owning entity and all descendants for the first called 'name' which implements function.

Script Component

These functions are available only to scripted entities.

BeginUpdate

Syntax: BeginUpdate ()
Function: Request script to get update call once per frame
Arguments: N/A
Return: N/A

EndUpdate

Syntax: EndUpdate ()
Function: Request script to end update call once per frame
Arguments: N/A
Return: N/A

GetSimulationTime

Syntax: GetSimulationTime ()
Function: Get the simulation time in seconds
Arguments: N/A
Return: Integer of the simulation time in seconds

IsExpertMode

Syntax: IsExpertMode ()
Function: Is the game using expert mode controls
Arguments: N/A
Return: 1 = if the controls are in expert mode, 0 = if the controls are not in expert mode

PosOri

These functions are related to the position and/or orientation of a component.

getNearPosition

Syntax: getNearPosition()
Function: Get the position in the current world frame of the object (local coordinates are local to a moving origin centred on teh camera's current tile)
Arguments: N/A
Return: The position x, y, z in metres relative to the origin

Rail Vehicle Component

These functions apply to the base class of all rail vehicles.

GetIsPlayer

Syntax: GetIsPlayer ()
Function: Is the rail vehicle controlled by the player
Arguments: N/A
Return: 1 = if the train is player controlled, 0 = if the train is AI controlled

GetSpeed

Syntax: GetSpeed ()
Function: Gets the rail vehicle's current speed
Arguments: N/A
Return: The speed in metres per second

GetAcceleration

Syntax: GetAcceleration ()
Function: Get the rail vehicle's acceleration
Arguments: N/A
Return: The acceleration in metres per second squared

GetTotalMass

Syntax: GetTotalMass ()
Function: Get the total mass of the rail vehicle including cargo
Arguments: N/A
Return: The mass in kilograms

GetConsistTotalMass

Syntax: GetConsistTotalMass ()
Function: Get the total mass of the entire consist including cargo
Arguments: N/A
Return: The mass in kilograms

GetConsistLength

Syntax: GetConsistLength ()
Function: Get the consist length
Arguments: N/A
Return: The length in metres

GetGradient

Syntax: GetGradient ()
Function: Get the gradient at the front of the consist
Arguments: N/A
Return: The gradient as a percentage

GetRVNumber

Syntax: GetRVNumber ()
Function: Get the rail vehicle's number
Arguments: N/A
Return: The rail vehicle number

SetRVNumber

Syntax: SetRVNumber ( number )
Function: Sets the rail vehicle's number (used for changing destination boards)
Arguments: number The new number for the vehicle
Return: N/A

GetCurvature

Syntax: GetCurvature ()
Function: Get the curvature (radius of curve) at the front of the consist
Arguments: N/A
Return: The radius of the curve in metres-1

SendConsistMessage

Syntax: SendConsistMessage ( message, argument, direction )
Function: Send a message to the next or previous rail vehicle in the consist. Calls the script function OnConsistMessage ( message, argument, direction ) in the next or previous rail vehicle
Arguments: message the ID of a message to send (IDs 0 to 100 are reserved, please use IDs greater than 100)
  argument a string argument
  direction 0 = sends a message to the vehicle in front, 1 = sends a message to the vehicle behind
Return: 1 = if there was a next/previous rail vehicle

GetCurvatureAhead

Syntax: GetCurvatureAhead ( displacement )
Function: Get the curvature relative to the front of the vehicle
Arguments: displacement If positive, gets curvature this number of metres ahead of the front of the vehicle. If negative, gets curvature this number of metres behind the rear of the vehicle.
Return: The radius of the curve in metres-1 positive if curving to the right, negative if curving to the left, relative to the way the vehicle is facing. 

SetBrakeFailureValue

Syntax: SetBrakeFailureValue ( namevalue )
Function: Sets a failure value on the train brake system for this vehicle
Arguments: name The name of the failure type. Either one of "BRAKE_FADE" (the proportion of brake power lost due to fade in the braking as a result of excess heat) or "BRAKE_LOCK" (the proportion of max force the brake is stuck at due to locking on the wheel)
  value The value of the failure dependent on failure type
Return: N/A

GetNextRestrictiveSignal

Syntax: GetNextRestrictiveSignal ( [direction = 0][minDistance = 0], [maxDistance = 10000] )
Function: Get the next restrictive signal's distance and state
Arguments: direction Optional. 0 = forwards, 1 = backwards. Defaults to 0
  minDistance Optional. How far ahead in metres to start searching. Defaults to 0
  maxDistance Optional. How far ahead in metres to stop searching. Defaults to 10000
Return: param1 -1 = nothing found, 0 = end of track, >0 = signal found.
  param2 Basic signal state: -1 = invalid, 1 = warning, 2 = red.
  param3 Distance in metres to signal.
  param4 2D map's "pro" signal state for more detailed aspect information. -1 = invalid, 1 = yellow, 2 = double-yellow, 3 = red, 10 = flashing-yellow, 11 = flashing-double-yellow.

Example of Use

local result, state, distance, proState = Call( "GetNextRestrictiveSignal" )

    if result <=0 then

        Print( "No restrictive signals ahead!" )

    else

        Print( "Restrictive Signal State: " ..state .. ", Distance: " .. distance .. ", Pro State: " .. proState )

end

Important Note: If a signal is within 1cm of minDistance, it is ignored. This is to compensate for floating point rounding errors and to help prevent an infinite loop being stuck at the same signal in a while loop.

If calling GetNextRestrictiveSignal iteratively, based on the last call's distance, you should include a check to make sure the last and new distances are not equal. If they are equal, add 1cm to the next minDistance. This will also prevent an infinite loop.

GetNextSpeedLimit

Syntax: GetNextSpeedLimit ( [direction = 0][minDistance = 0], [maxDistance = 10000] )
Function: Get the next restrictive signal's distance and state
Arguments: direction Optional. 0 = forwards, 1 = backwards. Defaults to 0
  minDistance Optional. How far ahead in metres to start searching. Defaults to 0
  maxDistance Optional. How far ahead in metres to stop searching. Defaults to 10000
Return: param1 -1 = nothing found, 0 = end of track, 1 = track speed limit (no signage), 2 = track speed limit sign, 3 = track speed limit.
  param2 Restriction in metres per second.
  param3 Distance in metres to speed limit.

Example of Use

local limitType, limit, distance = Call( "GetNextSpeedLimit" )

    if limitType == -1 then

        Print( "No speed limit ahead!" )

    elseif limitType == 0 then

        Print( "End of track: " .. distance )

    else

        Print( "Speed limit: " .. limit .. ", Distance:" .. distance .. ", Type: " .. limitType )

    end

Important Note: If a speed limit is within 1cm of minDistance, it is ignored. This is to compensate for floating point rounding errors and to help prevent an infinite loop being stuck at the same speed limit in a while loop.

If calling GetNextSpeedLimit iteratively, based on the last call's distance, you should include a check to make sure the last and new distances are not equal. If they are equal, add 1cm to the next minDistance. This will also prevent an infinite loop.

GetCurrentSpeedLimit

Syntax: GetCurrentSpeedLimit ( [component = 0] )
Function: Get the current speed limit for the consist
Arguments: component Optional. 0 = return current limit, 1 = return separate track and signal limit. Defaults to 0
Return: If component is set to 0, then a single value is returned. Otherwise, two values are returned for track and signal limits respectively

Example of Use

-- For a single combined limit
local currentLimit = Call("GetCurrentSpeedLimit")

Print("Current limit is " .. currentLimit)

-- For separate limits:
local trackLimit, signalLimit = Call("GetCurrentSpeedLimit", 1)

Print("Track limit is " .. trackLimit .. ", Signal limit is " .. signalLimit)

-- The minimum of trackLimit and signalLimit will be equal to currentLimit

GetConsistType

Syntax: GetConsistType ()
Function: Get the class of the consist
Arguments: N/A
Return: 0 = eTrainTypeSpecial,
1 = eTrainTypeLightEngine,
2 = eTrainTypeExpressPassenger,
3 = eTrainTypeStoppingPassenger,
4 = eTrainTypeHighSpeedFreight,
5 = eTrainTypeExpressFreight,
6 = eTrainTypeStandardFreight,
7 = eTrainTypeLowSpeedFreight,
8 = eTrainTypeOtherFreight,
9 = eTrainTypeEmptyStock,
10 = eTrainTypeInternational

GetIsNearCamera

Syntax: GetIsNearCamera ()
Function: Evaluates if the camera is near this vehicle ( < 4km)
Arguments: N/A
Return: True if near

GetIsInTunnel

Syntax: GetIsInTunnel ()
Function: Evaluates if the vehicle is in a tunnel
Arguments: N/A
Return: True if in a tunnel

Render Component

These functions relate to the RenderComponent which encompases the model, nodes and animations.

ActivateNode

Syntax: ActivateNode ( name, activate )
Function: Activate/Deactivate a node in a model
Arguments: name name of the node (use "all" for all nodes)
  activate 1 = show, 0 = hide
Return: N/A

AddTime

Syntax: AddTime ( nameactivate )
Function: Add time to an animation
Arguments: name name of the animation
  activate the amount of time in seconds, either positive or negative
Return: The remaining time in the animation

Reset

Syntax: ActivateNode ( nameactivate )
Function: Reset an animation
Arguments: name name of the animation
Return: N/A

SetTime

Syntax: SetTime ( name, time )
Function: Set the time of an animation
Arguments: name name of the animation
  time the amount of time in seconds, either positive or negative
Return: The remaining time in the animation

Sound Component

These functions are related to the Sound Component aspect of rail vehicles.

SetParameter

Syntax: SetParameter ( namevalue )
Function: Set a parameter on an audio proxy
Arguments: name name of the parameter
  value the value
Return: N/A

Control Container

These functions are related to the Control Container aspect of rail vehicles.

ControlExists

Syntax: ControlExists ( nameindex )
Function: Evaluates whether a control with a specific name exists
Arguments: name name of the control
  index the index of the control (usually 0 unless there are multiple controls with the same name)
Return: True if the control exists

GetControlValue

Syntax: GetControlValue ( nameindex )
Function: Get the value for a control
Arguments: name name of the control
  index the index of the control (usually 0 unless there are multiple controls with the same name)
Return: The value for the control

SetControlValue

Syntax: SetControlValue ( nameindex, value )
Function: Sets a value for a control
Arguments: name name of the control
  index the index of the control (usually 0 unless there are multiple controls with the same name)
  value the value to set the control to
Return: N/A

GetControlMinimum

Syntax: GetControlMinimum ( nameindex )
Function: Get the minimum value for a control
Arguments: name name of the control
  index the index of the control (usually 0 unless there are multiple controls with the same name)
Return: The control's minimum value

GetControlMaximum

Syntax: GetControlMaximum ( nameindex )
Function: Get the maximum value for a control
Arguments: name name of the control
  index the index of the control (usually 0 unless there are multiple controls with the same name)
Return: The control's maximum value

GetWiperValue

Syntax: GetWiperValue ( indexwiper )
Function: Get the normalised value of a wiper animation current frame
Arguments: index index of the wiper pair
  wiper the wiper to get the value of in the wiper pair
Return: A value between 0.0 and 1.0 of the wiper's current position in the animation

SetWiperValue

Syntax: SetWiperValue ( indexwiper, value )
Function: Set the normalised value of a wiper's animation
Arguments: index index of the wiper pair
  wiper the wiper to set the value of in the wiper pair
  value the value to set the wiper to
Return: N/A

GetWiperPairCount

Syntax: GetWiperPairCount ()
Function: Get the number of wiper pairs this control container has
Arguments: N/A
Return: Number of wiper pairs in the control container

IsControlLocked

Syntax: IsControlLocked ()
Function: Evaluate whether or not a control is locked
Arguments: N/A
Return: 0 = unlocked, 1 = locked

LockControl

Syntax: LockControl ( nameindex, locked )
Function: Locks a control so the user can no longer affect it e.g. to simulate a failure
Arguments: name name of the control
  index the index of the control (usually 0 unless there are multiple controls with the same name)
  locked True = lock a control, False = unlock a control
Return: N/A

Engine

These functions are also available to Engines specifically.

GetTractiveEffort

Syntax: GetTractiveEffort ()
Function: Get the proportion of tractive effort being used
Arguments: N/A
Return: The proportion of tractive effort between 0 and 100%

GetIsEngineWithKey

Syntax: GetIsEngineWithKey ()
Function: Is this the player controlled primary engine
Arguments: N/A
Return: True if this is the engine the player is controlling

GetIsDeadEngine

Syntax: GetIsDeadEngine ()
Function: Evaluate whether this engine is disabled
Arguments: N/A
Return: True if this engine is disabled

SetPowerProportion

Syntax: SetPowerProportion ( indexvalue )
Function: Set the proportion of normal power a diesel unit should output
Arguments: index index of the power unit (use -1 for all power units)
  value the proportion of normal power output between 0.0 and 1.0
Return: N/A

GetFireboxMass

Syntax: GetFireboxMass ()
Function: Get the proportion of full firebox mass
Arguments: N/A
Return: The mass of the firebox as a proportion of max in the range 0.0 to 1.0

Emitter Component

These functions are related to particle emitter aspects involved in rail vehicles.

SetEmitterColour

Syntax: SetEmitterColour ( r, g, b, [a] )
Function: Sets the emitter colour multiplier
Arguments: r, g, b, [a] = red, green, blue and (optionally) alpha
Return: N/A

SetEmitterRate

Syntax: SetEmitterRate ( rate )
Function: Set the emitter rate multiplier
Arguments: rate the rate. Defaults to 1
Return: N/A

SetEmitterActive

Syntax: SetEmitterActive ( active )
Function: Activate an emitter
Arguments: active 1 = activate, 0 = deactivate
Return: N/A

GetEmitterColour

Syntax: GetEmitterColour ()
Function: Gets the current emitter colour
Arguments: N/A
Return: The colour in rgba with components r, g, b, a

GetEmitterRate

Syntax: GetEmitterRate ()
Function: Gets the emitter rate multiplier. 1.0 is default, 0.0 is no emission.
Arguments: N/A
Return: The emitter rate

GetEmitterActive

Syntax: GetEmitterActive ()
Function: Gets whether the emitter is active
Arguments: N/A
Return: True if active

RestartEmitter

Syntax: RestartEmitter ()
Function: Restart the emitter
Arguments: N/A
Return: N/A

SetInitialVelocityMultiplier

Syntax: SetInitialVelocityMultiplier ( value )
Function: Multiply the initial velocity by a given value. Default value is 1.0
Arguments: value Multiplier to scale X, Y, Z velocity components
Return: N/A

Light Component

These functions concern the operation of Spot and Point lights on rail vehicles.

Activate

Syntax: Activate ( value )
Function: Turn the light on or off
Arguments: value 1 = on, 0 = off
Return: N/A

SetColour

Syntax: SetColour ( r, g, b )
Function: Set the colour of the light
Arguments: r,g,b = the red, green and blue components of the colour
Return: N/A

GetColour

Syntax: GetColour ()
Function: Get the colour of the light
Arguments: N/A
Return: r,g,b = the red, green and blue components of the colour

SetRange

Syntax: SetRange ( range )
Function: Sets the range of the light
Arguments: range The range of the light in metres
Return: N/A

GetRange

Syntax: GetRange ()
Function: Get the range of the light
Arguments: N/A
Return: The range of the light in metres

SetUmbraAngle

Syntax: SetUmbraAngle ( umbra )
Function: Sets the umbra of a spot light
Arguments: umbra the angle of the outer cone in degrees
Return: N/A

GetUmbraAngle

Syntax: GetUmbraAngle ()
Function: Gets the umbra of a spot light
Arguments: N/A
Return: The angle of the outer cone in degrees

SetPenumbraAngle

Syntax: SetPenumbraAngle ( penumbra )
Function: Sets the penumbra of a spot light
Arguments: penumbra the angle of the inner cone in degrees
Return: N/A

GetPenumbraAngle

Syntax: GetPenumbraAngle ()
Function: Gets the penumbra of a spot light
Arguments: N/A
Return: The angle of the inner cone in degrees