lua Script Referenzen

Update 2015-09-03:

At some point in the near future I will be moving this to a GitBook format. It will still be available here, however this may not be maintained as often as its replacement.

The move to GitBook will allow the use of Git for editing and versioning, as well as the source to be hosted on GitHub where its various features can be used.

If you would like to get involved in this, contact me on GitHub (davidjrichardson) and we’ll see what can be done.

TS2015 Scripting Reference
Word of Note
Any method call that begins Call(“<Entity>:...”) where <Entity> is anything such as <ParticleEmitter> or <ChildName> can also be called using the Call(“*:...”) qualifier so the parent and all descendant entities are checked, rather than specifying the entity to check.

It is also worth mentioning that this reference is WIP as most of this is undocumented and it can change at any time as it is not an official document. If anything is incorrect, leave a comment in the highlighted area with a description of what is wrong (and if possible, how to correct it).

You are free to use any code located within this document for personal or commercial use, with or without modification.

Core Functions:
function Initialise()

Function that is called once upon scenario initialisation but before route load. Should be used to set up variables/simulation elements of a script at the start of a scenario e.g. turning off/on lights.

function Setup()

Function that is called once when the script is initialised (e.g. when the player clicks the consist.) Can be used for when an event is to occur when the consist is clicked, e.g. raising a pantograph.

function Update(interval)

Function that is called every new frame to update the entities simulation. Parameter interval is the time since last update (known as the delta time, or delta for short.). Interval is in the units of seconds.

function OnConsistMessage(id, content, direction)

Function that is called when the entity in the consist receives a message that has been sent by the Call(“SendConstistMessage”, …) method. Parameter id is the unique identifier of the message and of type integer (int), content is the content of the message of type string and direction is the direction that the message was sent, 1 for forwards and -1 for backwards.

function OnCameraEnter(cabEnd, carriageCam)

Function that is called when the player camera enters a cab or passenger view. Parameter cabEnd is the cab that the player has entered and is either 1 or 2 and carriageCam denotes whether it was a passenger view or not, being 1 if it is a passenger view.

function OnCameraLeave()

Function that is called when the player leaves a camera view for another.

function OnCustomSignalMessage(message)

Function that is called when an entity in a consist receives a new message from a signal on the route. Parameter message is the message string that the signal has sent.

Method Calls:
Call(“*:BeginUpdate”)

Method to request the game to start sending updates to the script.

Call(“*:EndUpdate”)

Method to request the game ceases to send updates to the script. In previous versions of RailWorks (or Train Simulator 201X), prior to RW4, you had to call EndUpdate as many times as you did BeginUpdate, this, however, is not the case in RailWorks 4 (Train Simulator 2013) and onwards.

Call(“<ChildName>:AddTime”, “<AnimationID>”, time)

Method call to animate a child object using a specified animation id. Parameter <ChildName> is the name of the child object in the entities blueprint, <AnimationID> is the animation id that has been set up in the entities blueprint and time is the time to advance the animation (note that it is independent of FPS). Will return a value of 0 while animating and a non-zero value when it has finished.

Call(“<ChildName>:Reset”, “<AnimationID>”)

Method call to reset the animation to time = 0 of a given child object in the entities blueprint. Parameter <ChildName> is the child object name as specified in the entities blueprint and <AnimationID> is the animation as it is specified in the entities blueprint.

Call(“*:ActivateNode”, “<Node Name>”, active)

Method call to activate a node in the source geometry, where <Node Name> is the name of the node in the geometry and active is 1 for “on” or 0 for “off”.

Call(“*:SendConsistMessage”, id, content, direction)

Method call to send a message down the consist. Parameters id is the unique identifier of the message, content is the content of the message that must be a string and direction is 0 for forwards and 1 for backwards down the consist. Note direction is listed as “not used” as per RSDL’s documentation (which could very well be out of date). Will respond with 1 if the message has been forwarded in the requested direction or 0 if not.

Call(“*:SetControlValue”, “<ControlValue>”, index, value)

Method call to set the value of a control that has been specified in the engine blueprint of a locomotive. Parameter <ControlValue> is the name of the control as it is in the engine blueprint, index is the index in an array of controls that share the same name (should generally be 0) and value is the value to set the control to.

Call(“*:GetControlValue”, “<ControlValue>”, index)

Method call to retrieve the value of a control that has been specified in the engine blueprint of a locomotive. Parameter <ControlValue> is the name of the control as it is in the engine blueprint and index is the index in an array of controls that share the same name (should generally be 0).

Call(“*:ControlExists”, “<ControlValue>”, index)

Method that will return 1 if a given control value exists in a blueprint or 0 if not. Parameter <ControlValue> is the control value to check, as specified in the engine blueprint and index is the index in an array of controls if there are multiple controls with the same name.

Call(“*:SetEngineValue”, “<ControlValue>”, value)
Method that will set the lead engine’s given control value(?) to a specified value. Parameter <ControlValue> is the control value to affect, and value is the new value to set the control to.

Call(“<ChildName>:SetText”, text, set)

Method to set the entity text to a given value. Parameter <ChildName> is the child object that is to be manipulated, text is the text to set and set is is whether to use a primary or secondary set. Use 0 for a primary set and 1 for a secondary set.

Call(“*:GetSimulationTime”)

Method call that returns the time that the scenario/simulation has been running in seconds.

Call(“*:GetCurrentSpeedLimit”)

Method call that will retrieve the speed limit of the section of track that the consist is currently on, measured in m/s.

Call(“*:GetNextSpeedLimit”, direction, distancetolookfrom)

Method call that will retrieve the next speed limit in a given direction within 10km of the entity in the consist. Parameter direction is the direction to check, with 0 for forward and 1 for backwards. Parameter distancetolookfrom is the distance (in meters) to look from to get the next speed limit. Omitting this parameter is equivalent of setting it to 0.
Returns 3 pieces of data; type, speed and distance. type indicates the cause of restriction on the line, speed is the new speed restriction, measured in m/s and distance is the distance in metres that are remaining until the new speed limit. The values that type can undertake are:

• 0 - indicating end of line,
• 1 - indicating speed change but no linked trackside sign,
• 2 - indicating speed change with linked trackside sign,
• -1 - indicating no change in speed over the next 10km.

I only get speed that is behind me, even if i put direction on 0. I then test this “Call(“*:GetNextSpeedLimit”, direction)” and it’s work, i get next speed limit if i put in direction “0” and if i put direction on “1” then i get speed limit that is behind me.example:
type, speed, distance = Call("GetNextSpeedLimit", 0) --to see next speed limit
Print("type " .. tostring(type)) -- here you get type
Print("speed " .. tostring(speed)) -- here you get speed in m/s
Print("distance " .. tostring(distance)) -- here you distance in m

Call(“*:GetNextRestrictiveSignal”, direction, distancetolookfrom)

Method call that will gather information about the next non-green signal (such that it is not “clear”). Parameter direction is the direction to look, with 0 for forward and 1 for backward. Parameter distancetolookfrom is the distance (in meters) to look from to get the next restrictive signal. Omitting this parameter is equivalent of setting it to 0.
Returns 4 values; type, state, distance and aspect. type is representative of the values that follow it, and will carry a range of values itself. state indicates the state of the signal in the signalling system; 0 is “clear”, 1 is “warning” and 2 is “stop”. distance is the distance, in metres, until the signal has been reached and aspect is the aspect set by the signal script (that is relative to “Set2dMapProSignalState”). For UK signals this can be:

• 0 - indicates signal is green,
• 1 - indicates signal is single yellow,
• 2 - indicates signal is double yellow,
• 3 - indicates signal is red,
• 10 - indicates signal is flashing single yellow,
• 11 - indicates signal is flashing double yellow.

The values that can be used by type are as follows:

• -1 - indicates there are no restrictive signals within 10km of the consist entity,
• 0 - indicates end of line (such that state & aspect can be ignored),
• 1 - indicates there is a restrictive signal on the line within 10km, and as such, state, distance & aspect should be checked for more info.

Note that state and aspect shouldn’t be 0 as they indicate that the signal is not restrictive.
Call(“*:GetAcceleration”)

Method call that will retrieve the acceleration the player is undergoing at that specific point in time, measured in m/s^2.

Call(“*:GetSpeed”)

Method call that returns the velocity of the player at that specific point in time. Can be used when dealing with advanced physics along side the tractive effort values of the entity

Call(“*:GetIsPlayer”)

Method call that will return if the consist is the player consist. 1 is returned if true, else 0 is returned.
Call(“*:GetIsDeadEngine”)

Method that will return if the engine is specified “dead” as an attribute that has been set in the scenario editor. If true 1 is returned, else 0.

Call(“*:GetIsEngineWithKey”)

Method that will return 1 if the engine is being driven by the player, otherwise it will return 0.

Call(“*:GetTractiveEffort”)

Method that will retrieve the tractive effort that the locomotive is outputting at that moment in time, measured in kN.

Method that will retrieve the tractive effort of that a locomotive that is outputting at a given point in time as a fraction of the MaxForce blueprint parameter. Note that to get the absolute tractive effort, Call(“*:GetControlValue”, “TractiveEffort”, 0) can be used, however this will return T.E. in KlbF or Kilo-p0ounds-force.

Call(“*:GetGradient”)

Method that will return the grade of the track that the consist is currently on.

Call(“*:GetCurvature”)
Method that will get the curvature of the track that the consist is currently on.

Call(“*:GetCurvatureAhead”, distance)

Method that will get the curvature of the track at a given distance in front of the consist. Parameter distance is the distance ahead to look in metres. It is measured as the reciprocal of the radius of the curve (1/radius) such that the curvature of a straight line is 0.

Call(“*:GetConsistLength”)

Method that will return the length of the consist at that given point in time, in metres.

Call(“*:GetConsistTotalMass”)

Method that will get the total mass of the consist that the entity is in, inclusive of ballast/fuel. mass is measured in tons.

Call(“*:GetTotalMass”)

Method that will get the total mass of the entity that is calling this method, inclusive of ballast/fuel, measured in tons. Will only work within an engine script/blueprint, and not a wagon script/blueprint.

Call(“*:GetFireboxMass”)

Method that will retrieve the mass of the firebox as a fraction of its maximum value.

Call(“*:GetRVNumber”)

Method that will return the number of the entity that called this method. The number is the attribute that can be set in the scenario editor.
Call(“<LightChild>:SetRange”, range)

Method that will set a light entities maximum range. Parameter <LightChild> is the entity to be affected and range is the maximum distance in metres that the light can cast.

Call(“<LightChild>:Activate”, active)

Method that will set whether a light entity is activated or not. Parameter <LightChild> is the entity to be affected and active is either 1 or 0; 1 for “on”, 0 for “off”.

Call(“<LightChild>:SetColor”, r, g, b)

Method that will set the colour of a given light entity. Parameter <LIghtChild> is the entity to be affected and the values r, g & b are float values of range 0 - 1 that represent each colour channel.

Call(“<LightChild>:SetUmbraAngle”, angle)

Method that will set the “full beam” angle of the light (the area that is lit fully by a directional light). Parameter <LightChild> is the entity to be affected and angle is the angle of the beam in degrees.

Call(“<LightChild>:SetPenumbraAngle”, angle)

Method that will set the “fuzzy” angle of the light (the fall off of the main beam). Parameter <LightChild> is the entity to be affected and angle is the angle of the fuzzy area in degrees.

Call(“<ParticleEmitter>:SetInitialVelocityMultiplier”, multiplier)

Method that will set the initial velocity of a particle in an emitter entity. Parameter <ParticleEmitter> is the entity to be affected and multiplier is the multiplier of the initial velocity.

Call(“<ParticleEmitter>:SetEmitterActive”, active)

Method that is used to set a particle emitter to be active or not. Parameter <ParticleEmitter> is the emitter to be affected and active is either 1 or 0; 1 for “on” or 0 for “off”.

Call(“<ParticleEmitter>:SetEmitterRate”, interval)

Method that is called to set the rate of particle emission of a particle emitter. Parameter <ParticleEmitter> is the emitter to be affected and interval is the time between particle emissions.

Call(“<ParticleEmitter>:SetEmitterColour”, r, g, b)

Method called to set the colour of the particles being emitted from a particle emitter. Parameter <ParticleEmitter> is the emitter to be affected and the values r, g & b are the 3 colour channels to set the colour to. Each colour channel is a float of value 0 - 1.

Call(“<ParticleEmitter>:GetEmitterActive”)

Method that will obtain whether a specified particle emitter is active or not. Parameter <ParticleEmitter> is the emitter to be checked.

Call(“<ParticleEmitter>:GetEmitterRate”)

Method call that will return the time interval between particle emissions for a specified particle emitter. Parameter <ParticleEmitter> is the particle emitter to be checked.

Call(“<ParticleEmitter>:GetEmitterColour”)

Method call that will return the r, g & b values of the particle emitter that it is emitting. the values of r, g & b are floats of range 0 - 1. Parameter <ParticleEmitter> is the particle emitter to be tested.

Call(“ControlSound:SetParameter”, “<Sound>”, value)

Method that will set a specific sound parameter’s value(?). Parameter <Sound> is the sound to be affected, as specified in the engine/wagon blueprint and value is the value to set it to, with respect to the values that have been set within a sound control blueprint.

SysCall(“ScenarioManager:GetSeason”)

System method call that will get the season of the simulation. Value returned is in the range 0 - 3 where 0 is Spring and 3 is Winter.

SysCall(“ScenarioManager:GetTimeOfDay”)

System method call that will retrieve the time since midnight in seconds of the current scenario/simulation.

SysCall(“ScenarioManager:TriggerScenarioComplete”, message)

System method call that will trigger the scenario to complete, showing a message to the user. Parameter message is the message to be shown to the user.

SysCall(“ScenarioManager:TriggerScenarioFailure”, message)

System method call that will trigger the scenario to end in a failure, showing a message to the user. Parameter message is the message that is to be shown to the user.

SysCall(“ScenarioManager:ShowMessage”, message)

System method call that will show a message to the player. Parameter message is the message that is to be shown to the player.
Call(“<ChildName>:getNearPosition”)

Method that will obtain the x, y & z coordinates of a position of an entity that is specified. Parameter <ChildName> is the child entity to be checked.

Call(“<ChildName>:setNearPosition”, x, y, z)

Method that will set the position of a specified child object. Parameter <ChildName> is the child entity to be affected and the values x, y & z are the coordinates of the position to set the child to.

Incomplete Methods:
These are method calls that have not got entirely complete sets of information about them, inclusive of return values, parameters, etc... Feel free to suggest things if you have knowledge through the use of the comment section.

SysCall("CameraManager:ActivateCamera", “<Camera>”, unknown)

Method to force the camera of the player to a specific camera view. Parameter <Camera> is the camera name to use and unknown is thought to be camera type. Known <Camera> values are:

• CabCamera
• FreeCamera

It is suggested to set the value of unknown to 0 for CabCamera and 7 for FreeCamera.

SysCall("ScenarioManager:ShowInfoMessageExt", header, message, timeout, offset, size, pause)

Method to display a scenario message box to the user. Parameter header is the header of the message, message is the message content, timeout is the time it will stay on screen in seconds, offset is unknown, size is the size of the message box and pause is whether or not the scenario is paused during the display of the message box. 1 is true and 0 is false.

Values of size are as follows:

• 0 - Small message box,
• 1 - Regular message box,
• 2 - Large message box.

SysCall(“ScenarioManager:ShowAlertMessageExt”, header, message, timeout, unknown)

Method to display an alert box to the user in game. Parameter header is the header of the message, message is the message content, timeout is the time it will stay on screen in seconds and unknown has no known purpose but is required. It is recommended to set it to 0.

Call(“CameraManager:JumpTo”, x, y, z)

Method to set the position of the player camera to specific position relative to to the route origin(?). Parameters x, y, z are positions relative to the route origin in metres(?)

Call(“*:LockControl”, “<ControlValue>”, index, value”)

Method that will lock a control in place so it cannot be changed in game (and perhaps in code?). Parameter <ControlValue> is the control to be locked, as specified in the engine blueprint. index is the index of the control in an array of controls with the same name and value is the value to determine whether the control is locked or not, with 1 being locked in place and 0 being unlocked.

SysCall ( "ScenarioManager:LockControls");

Method that will lock all controls and the actual view.

Useful Functions:

function ChangeControlValue(name, index, value)
if Call("*:ControlExists", name, index) then
Call("*:SetControlValue", name, index, value);
end
end

A convenience function that relies on a global boolean value to determine whether the script is in debug mode or not named DEBUG. If the script is in debug mode (DEBUG is true) then it will log a message to Logmate. Parameter message is the message to be logged to Logmate.

function DebugShowAlert(message, timeout)
if (DEBUG) then
SysCall(“ScenarioManager:ShowAlertMessageExt”,
“Debug Log”, message, timeout, 0);
end
end

Another convenience function that relies on a global boolean value to determine whether the script is in debug mode or not named DEBUG. If the script is in debug mode (DEBUG is true) then it will display an alert message box in game for a specified amount of time with a specified message. Parameter message is the message to be displayed and timeout is the timeout of the alert message. This is particularly useful as Logmate will not be required to be run to debug, but messages could be produced too fast to read.

function OnConsistMessage(id, content, direction)
Call(“*:SendConsistMessage”, id, content, direction);
end

Convenience function that will forward the message that has been passed down the consist to the next consist entity in the same direction.