Function Names
Function names can be either:
- function
- *:function
- 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 ComponentThese 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 ( name, value ) |
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 ( name, activate ) |
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 ( name, activate ) |
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 ( name, value ) |
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 ( name, index ) |
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 ( name, index ) |
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 ( name, index, 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 ( name, index ) |
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 ( name, index ) |
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 ( index, wiper ) |
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 ( index, wiper, 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 ( name, index, 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 ( index, value ) |
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 |
|