pressure above a certain value. Once a condition has completed its value is saved and any further checks will return this saved value.
To give a scenario a script a ScenarioScript.lua must be placed in the root of the scenario, this should define two functions.
function OnEvent ( event )
This is the event handler function it handles any event calls from the scenario system. It should return TRUE(1) if the event is handled or FALSE(0) if the event is unknown, event is the name of the event as defined in the instruction, trigger or TriggerDeferredEvent call.
function TestCondition ( condition )
This is the condition checker function, it is used to test whether the player has met additional conditions for an instruction. It should return one of CONDITION_NOT_YET_MET(0), CONDITION_SUCCEEDED(1) or CONDITION_FAILED(2), condition is the name of the condition as defined in the instruction or BeginConditonCheck call.
Scenario scripts have a slightly different calling convention to other scripts in the game. Rather than use Call, scenario scripts use SysCall.Â
SysCall has access to a number of global functions as well as to the normal script functions of any named objects. SysCall uses the same colon notation to describe the object or global module for which the function call is required. E.g.:
SysCall ( "ScenarioManager:ShowMessage", "Title", "Message" )
speed = SysCall ( "PlayerEngine:GetSpeed" )
A second colon can be used to get a child object, e.g.:
SysCall ( "PlayerEngine:Main Smoke Stack:GetEmitRate" )
Any object placed in a scenario can be named from the properties flyout in the 'Object Name' field. PlayerEngine is a special value and always pertains to the player's engine, any numbered rail vehicle can also be used.
Important Note: Since scripts are not persisted by a save the scenario script should be stateless. The state can be affected by the use of Checked Conditions and Deferred Events which are persisted by a save. |
Function Reference
The list of functions available, defined by module.
ScenarioManager
The core scenario scripting module.
TriggerScenarioFailure
Syntax: | TriggerScenarioFailure ( message ) |
Function: | Triggers the failure of the scenario |
Arguments: | message | The message to show indicating why the scenario failed |
Return: | N/A |
TriggerScenarioComplete
Syntax: | TriggerScenarioComplete ( message ) |
Function: | Triggers the successful completion of the scenario |
Arguments: | message | The message to show indicating why the scenario succeeded |
Return: | N/A |
TriggerDeferredEvent
Syntax: | TriggerDeferredEvent ( event, time ) |
Function: | Triggers a deferred event |
Arguments: | event | The name of the event |
| time | The time in seconds until the event should trigger |
Return: | false if the event was already scheduled |
Note: | Only one event per update may be triggered, two events with the same expiry time will be triggered in successive frames. |
CancelDeferredEvent
Syntax: | CancelDeferredEvent ( event ) |
Function: | Cancels a deferred event |
Arguments: | event | The name of the event |
Return: | false if the event was no longer scheduled |
BeginConditionCheck
Syntax: | BeginConditionCheck ( condition ) |
Function: | Begins testing of a condition |
Arguments: | condition | The name of the condition |
Return: | false if the condition was already scheduled |
Note: | As soon as the condition is completed as either CONDITION_SUCCEEDED(1) or CONDITION_FAILED(2), the condition will cease to be tested. If the condition was already complete at hte time of the call, no CheckCondition will be generated. |
EndConditionCheck
Syntax: | EndConditionCheck ( condition ) |
Function: | Removes a condition from checking per frame |
Arguments: | condition | The name of the condition |
Return: | false if the condition was no longer scheduled |
Note: | Cannot be called from within TestCondition |
GetConditionStatus
Syntax: | GetConditionStatus ( condition ) |
Function: | Get the status of a script condition |
Arguments: | condition | The name of the condition |
Return: | CONDITION_NOT_YET_MET(0), CONDITION_SUCCEEDED(1) or CONDITION_FAILED(2) |
Note: | The call only tests the saved status of a condition, it does not generate a call to CheckCondition |
ShowMessage
Syntax: | ShowMessage ( title, message, type ) |
Function: | Shows a dialogue box with a message |
Arguments: | title | The title for the message box |
| message | The text for the message |
| type | The type of message box INFO(0) or ALERT(1) |
Return: | N/A |
Note: | If title or message are in UUID format, then they are used as keys into the language table |
ShowInfoMessageExt
Syntax: | ShowInfoMessageExt ( title, message, time, pos, size, pause ) |
Function: | Shows an info dialogue box with a message and extended attributes |
Arguments: | title | The title for the message box |
| message | The text for the message |
| time | The time to show the message, 0.0 for indefinite |
| pos | The position of the message box (MSG_TOP(1), MSG_VCENTRE(2), MSG_BOTTOM(4), MSG_LEFT(8), MSG_CENTRE(16), MSG_RIGHT(32)) |
| size | The size of the message box (MSG_SMALL(0), MSG_REG(1), MSG_LRG(2)) |
| pause | If true pause the game while the message is shown |
Return: | N/A |
Note: | If title or message are in UUID format, then they are used as keys into the language table |
ShowAlertMessageExt
Syntax: | ShowAlertMessageExt ( title, message, time, event ) |
Function: | Shows an info dialogue box with a message and extended attributes |
Arguments: | title | The title for the message box |
| message | The text for the message |
| time | The time to show the message, 0.0 for indefinite |
| event | Event name triggered on click of message |
Return: | N/A |
Note: | If title or message are in UUID format, then they are used as keys into the language table |
IsAtDestination
Syntax: | IsAtDestination ( service, dest ) |
Function: | Triggers a deferred event |
Arguments: | service | The name of the event |
| dest | The time in seconds until the event should trigger |
Return: | false if the event was already scheduled |
Note: | Only one event per update may be triggered, two events with the same expiry time will be triggered in successive frames. |
GetScenarioTime
Syntax: | GetScenarioTime () |
Function: | Gets the time since the scenario start in seconds |
Arguments: | N/A |
Return: | The time since the scenario start in seconds |
GetTimeOfDay
Syntax: | GetTimeOfDay () |
Function: | Gets the time since midnight in seconds |
Arguments: | N/A |
Return: | The time since midnight in seconds |
LockControls
Syntax: | LockControls () |
Function: | Locks out controls and keyboard |
Arguments: | N/A |
Return: | N/A |
UnlockControls
Syntax: | UnlockControls () |
Function: | Unlocks controls and keyboard |
Arguments: | N/A |
Return: | N/A |
GetSeason
Syntax: | GetSeason () |
Function: | Gets the season |
Arguments: | N/A |
Return: | SEASON_SPRING = 0, SEASON_SUMMER = 1, SEASON_AUTUMN = 2, SEASON_WINTER = 3 |
WeatherController
The weather control module.
GetCurrentPrecipitationType
Syntax: | GetCurrentPrecipitationType () |
Function: | Gets the current type of precipitation |
Arguments: | N/A |
Return: | 0 = rain, 1 = sleet, 2 = hail, 3 = snow |
GetPrecipitationDensity
Syntax: | GetPrecipitationDensity () |
Function: | Gets the density of the precipitation |
Arguments: | N/A |
Return: | A value between 0 and 1 for the density of precipitation |
GetPrecipitationSpeed
Syntax: | GetPrecipitationSpeed () |
Function: | Gets the speed of the precipitation |
Arguments: | N/A |
Return: | The vertical fall speed of precipitation in metres per second |
CameraManager
The camera control module.
ActivateCamera
Syntax: | ActivateCamera ( name, time ) |
Function: | Switch to a named camera |
Arguments: | name | The name of the camera |
| time | The time in seconds before reverting back to previous camera. Use 0 for no revert |
Return: | N/A |
Note: | The camera can be any of hte standard cameras or a user-defined camera.
CabCamera - the cab interior camera (as assigned to Key 1) ExternalCamera - the exterior train tracking camera (as assigned to Key 2) HeadOutCamera - the head out camera (as assigned to Shift + Key 2) TrackSideCamrea - the trackside camera (as assigned to Key 4) CarriageCamera - the carriage interior camera (as assigned to Key 5) CouplingCamera - the coupling camera (as assigned to Key 6) YardCamera - the top-down camera view (as assigned to Key 7) FreeCamera - the free camera (as mapped to Key 8) |
LookAt
Syntax: | LookAt ( name ) |
Function: | Have the camera look at an objection |
Arguments: | name | The name of the object to look at |
Return: | True if the named object was found |
Note: | If name is a rail vehicle number, then the camera will look at that rail vehicle. If the name is that of a named object, then only the free camera will look at the object |
JumpTo
Syntax: | JumpTo ( longitude, latitude, height ) |
Function: | Move the camera to a location |
Arguments: | longitude | The longitude of the position |
| latitude | The latitude of the position |
| height | The height above sea level |
Return: | True if the camera could move to the location |
Note: | Only available for the free camera |
Example Script
------------------------------------------------
-- ScenarioScript.lua
-- Sample Scenario Script
------------------------------------------------
-- true/false defn
FALSE = 0
TRUE = 1
-- condition return values
CONDITION_NOT_YET_MET = 0
CONDITION_SUCCEEDED = 1
CONDITION_FAILED = 2
-- Message types
MT_INFO = 0 -- large centre screen pop up
MT_ALERT = 1 -- top right alert message
------------------------------------------------
-- Fn OnEvent
-- event - name of the event
-- return - TRUE/FALSE if event handled
function OnEvent ( event )
  Â
if event == "Event1" then
  Â
  Â
SysCall ( "AnimObject1:PlayAnim", "Anim1", 0, 1.0 ); -- Play anim once non looping at normal(1.0x) speed
  Â
  Â
SysCall ( "CameraManager:ActivateCamera", "CabCamera", 0 ); -- Switch to cab view
  Â
  Â
return TRUE;
  Â
end -- if event == "Event1" then
  Â
if event == "Event2" then
  Â
  Â
SysCall ( "ScenarioManager:ShowMessage", "Title", "Message", MT_INFO ); -- Show message
  Â
  Â
return TRUE;
  Â
end -- if event == "Event2" then
  Â
if event == "Event3" then
  Â
  Â
SysCall ( "ScenarioManager:BeginConditionCheck", "TestCondition1" ); --
  Â
  Â
Start continual testing of a condition
  Â
  Â
SysCall ( "ScenarioManager:TriggerDeferredEvent", "DeferredEvent1", 300.0 );--Trigger a deferred event in 300s
  Â
  Â
return TRUE;
  Â
end -- if event == "Event3" then
  Â
if event == "DeferredEvent1" then
  Â
  Â
SysCall ( "ScenarioManager:EndConditionCheck", "TestCondition1" );
  Â
  Â
if SysCall ( "ScenarioManager:GetConditionStatus", "TestCondition1" ) ~= CONDITION_SUCCEEDED then
  Â
  Â
  Â
SysCall ( "ScenarioManager:ShowMessage", "Failed", "TestCondition1", MT_ALERT ); -- Show message
  Â
  Â
end -- if SysCall ( "ScenarioManager:GetConditionStatus", "TestCondition1" ) == CONDITION_FAILED then
  Â
  Â
return TRUE;
  Â
end -- if event == "DeferredEvent1" then
  Â
return FALSE;
end -- function OnEvent ( event )
------------------------------------------------
-- Fn TestCondition
-- condition - name of the condition
-- return state of the condition
function TestCondition ( condition )
  Â
if condition == "Condition1" then -- consist weight > 100000 kg
  Â
  Â
mass = SysCall ( "PlayerEngine:GetConsistTotalMass" );
  Â
  Â
if mass > 100000 then
  Â
  Â
  Â
return CONDITION_SUCCEEDED;
  Â
  Â
else
  Â
  Â
  Â
return CONDITION_FAILED;
  Â
  Â
end
  Â
end -- if condition == "Condition1" then
Â
  Â
if condition == "Condition2" then -- using whistle
  Â
  Â
controlValue = SysCall( "PlayerEngine:GetControlValue", "Horn", 0 );
  Â
  Â
if controlValue > 0.5 then
  Â
  Â
  Â
return CONDITION_SUCCEEDED;
  Â
  Â
else
  Â
  Â
  Â
return CONDITION_FAILED;
  Â
  Â
end
  Â
end -- if condition == "Condition2" then
  Â
if condition == "Condition3" then -- engaged low gear
  Â
  Â
gear = SysCall( "PlayerEngine:GetControlValue", "Gear", 0 );
  Â
  Â
if gear < 3 then
  Â
  Â
  Â
return CONDITION_SUCCEEDED;
  Â
  Â
else
  Â
  Â
  Â
return CONDITION_FAILED;
  Â
  Â
end
  Â
end -- if condition == "Condition2" thenÂ
  Â
if condition == "TestCondition1" then -- reached 100mph (44.704 m/s)
  Â
  Â
speed = SysCall ( "PlayerEngine:GetSpeed" );
  Â
  Â
if speed > 44.704 then
  Â
  Â
  Â
return CONDITION_SUCCEEDED;
  Â
  Â
end -- if speed > 44.704 then
  Â
end -- if condition == "TestCondition1" then
  Â
-- default to not met
  Â
return CONDITION_NOT_YET_MET;
end -- function TestCondition ( condition )