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 |
|
