System Scripting Variables and Events

List of System Script variables with description

There exist many system variables in LOTUS. A script can read from and write to these variables, depending on the variable.

Some system variables are declared beforehand and do not need to be again declared at another location. Other system variables do have to be declared in the "PUBLIC VARS" section of the script.

Variables that do need to be declared are indicated with 'decl.' in the last column of the table. Variables that do not need to be declared again are indicated with ex (exists).

1 General

Variable name	Description	Type	Unit	Write access	Decl.
`Timegap`	Time past since last calculation step	Single	Seconds		ex
`NightTex`	Map wide variable for the control of night textures etc.	Integer	-		ex
`EnvirBrightness`	Brightness of environment	Single	0..1		ex
`DistrictLight`	State of the linked lighting district. Is no district linkes, the result will be 1.0 everytime.	Single			ex
`TimeOfDay`	Time of day	Single	0 = 0:00, 0.5 = 12:00, 1 = 24:00		decl.
`Date`	Date and Time in days since 30.12.1899, 00:00. Attention! Without Time!	Single	1 = one day		decl.
`Hint`	Hint text. Set this variable to a SpeechData-ID so the corresponding text is shown in the hint screen in LOTUS. You can use this to show the user, when not correctly operating the vehicle, why it is not possible. Convention is that user defined Speech-IDs are made up as follows: "[Vehicle name].Hint.[ShortText]" For example: "GT6N.Hint.ReverserNotSet" You then need to create your own SpeechData where every id (in the left column) is mapped to the corresponding text (in the chosen language) in the right column. By using multiple SpeechData files you can achieve hints in multiple languages.	String	-	X	decl.
`Mouse_X` & `Mouse_Y`	Movement of the mouse pointer since the last simulation step	Single	Pixel		decl
`RealisticElecSupply`	Indicator for the user setting "Realistic electricity supply"	Boolean	-		decl
`InitReadyForMovement`	Indicator for the user setting "Place Set Up Grade" 0 = Cold & Dark (e.g. Reverser at 0, pantograph lowered, main switch off, transformer off) 1 = Set up (e.g. Reverser at I or *, pantograph raised, main switch on, transformer on) 2 = Running (e.g. reverser in Forward)	Integer	0..2		decl
`InitPosInTrain`	Position of the wagon in the train immediately after placing the train ( 0 = front car).	Integer			decl
`InitCarIsReversed`	Indicates the direction of the wagon in the train after placing the train. False = wagon against the direction of the train, True = wagon along the direction of the train.	Boolean			decl
`InitUserPlaced`	Was the user placed in this car the first time? If the car is subsequently left or coupled, etc., this variable will still not change.	Integer	0 = no 1 = front 2 = back		decl
`DeadMansSwitch`	Indicator for the user setting "Simulate Dead Man's switch"	Boolean			decl
`mirrortex_{i}`	If mirrors (or similar) are defined, LOTUS stores the respective texture indices in the variables of this name (i = index of the mirror, starting at 0), so that they can be accessed in the material properties.	Integer	0...		decl

2 Remote-Control (AI-/Multiplayer, Stationary train)

The following variables are used for communication between Multiplayer and AI vehicles and the user vehicle (train). If a vehicle is the user vehicle then "RC_Active" is false. Then the variables can be set. This is also called "Sending mode", If the vehicle is not the user vehicle, e.g. a multiplayer or AI vehicle or a vehicle placed by the user, then "RC_Active" is true. The variables can then only be read; the vehicle is in "Receiving mode".

Variable name	Description	Type	Unit	Write access	Decl.
`RC_Active`	Train is in receiving/remote control mode. This indicates that at the moment this vehicle is not operated by a user. The vehicle is now a vehicle operated by another player (in Multiplayer) or an AI or stationary vehicle. If the variable is false the vehicle is a user vehicle and is in sending mode.	Boolean	-		decl
`RC_DirLeaver`	The sending vehicle can use this variable to indicate what wagon in a train is the "Master" (obviously when the reverser is moved out of the off position) and from which cabin this action was performed. Do note that this does not indicate what direction is set: - If the reverser is operated from the front cabin (or main controls) this variable must be set to 1, even if the reverser is set to reverse. - If the reverser is operated from the rear cabin (or auxiliary reverse driving console) this variable must be set to -1, even if the reverser is set to forward. If this variable is set nowhere in the entire train then: - for certain following variables (RC_Belling, RC_Cockpitlight) the position of the user in the sending vehicle is used. - all wagons receive 0 as variable value. If multiple wagons in a train set this variable then only the first (in the ordering of the train) is used. Other values are ignored.	Integer	1 = set in front cabin 0 = not set -1 = set in rear cabin (set means reverser in forward, reverse or neutral, NOT in off)	[if sending]	decl
`RC_Throttle`	Used for communicating the throttle setting in absolute value, that is, without considering the direction. Of the individual values in the wagons in the sending train the maximum is found and communicated for the entire train. This value is not used in the driving physics (the receiving train will anyway move in the same way as the sending vehicle). It is used for a correct simulation of especially sounds, but also animations and lights that vary based on the power.	Single	0..1	[if sending]	decl
`RC_Brake`	Used for communicating the brake setting. Use in the same way as RC_Throttle. Normalized to 0..1.	Single	0..1	[if sending]	decl
`RC_IndR`, `RC_IndL`	Indicator right/left. This variable shows whether the right and/or left indicator/turn signal is active. If both variables are true then the hazard indicators are on. Special about these variables is that single vehicles send and receive this variable taking into account their direction. As an example: In a train there are 2 vehicles running back to back. If the right indicators (in running direction) should turn on then in the forwards facing train the RC_IndR variable is set to true. In the backwards facing train RC_IndL is set to true. In sending mode it is sufficient for one vehicle to set the respective variable to true, the entire train is then interpreted as indicating. In receiving mode the variables of all vehicles are set.	Boolean	-	[if sending]	decl
`RC_FrontLight_Front` `RC_FrontLight_Back`	This variable is only transferred for the first and last part of a train and there only for the uncoupled end. In receiving mode the variable stays at 0 for the coupled ends.	Integer	0 = off 1 = daytime running lights 2 = dipped beam 3 = main beam	[if sending]	decl
`RC_OtherLights_Front` `RC_OtherLights_Back`	These variables can be used to set additional light at the front and back ends, like rear light, braking lights and fog lights. These variables are only transferred for the first and last part of a train and there only for the uncoupled end. In receiving mode the variables stay at 0 for the coupled ends.	Integer	Bit-Flags: +1 = Tail lights +2 = Braking lights +4 = Reversing lights +8 = Fog lights +16 = Rear fog lights +32 = free +64 = free +128 = free	[if sending]	decl
`RC_Belling`	State of the bell. In sending mode it is irrelevant what vehicle is sending the bell state. In receiving mode only the vehicle in which the reverser was set (or where the sending user is located) will get the new bell state. All others only receive 0.	Integer		[if sending]	decl
`RC_Sanding`	State of the sander. When at least one vehicle in a train is sanding then this state is transferred to the entire receiving train.	Boolean		[if sending]	decl
`RC_DoorsOpen_Left`, `RC_DoorsOpen_Right`	These variables are used to communicate the state of the doors. Each door is represented bitwise in an Integer for the left and right doors. For more about this see the Bit-Flags article. It is recommended to convey the "Goal" of the door movements. Not following this leads to the following issue: if you use as open state the formula "DoorOpen >0.5" then the closing for the multiplayer colleagues will only start when the doors for the player are already halfway closed. Especially with warnings before the closing of the doors this can lead to considerable delays. Important: To let this variable work correctly you must indicate the number of doors in the "Object settings" in the Content-Tool! This number refers to the number of doors per side, where the highest number is chosen: Value = Maximum( Doors on left side, Doors on right side).	Integer	Bit-Flags	[if sending]	decl
`RC_CockpitLight`	The user vehicle (or the vehicle with set reverser) in a sending train can indicate the setting of the lighting in the driving cabin.	Boolean		[if sending]	decl
`RC_CabinLight`	This variable uses Bit-Flags to allow for multiple (passenger) cabin lights (like upper and lower deck). When sending the state of a specific light source, it only needs to be set in one wagon. Then that light will turn on in the entire train (Bitwise OR). Max 8 bit.	Integer	Bit-Flags	[if sending]	decl
`RC_PantographApplied`	State of the pantographs of the vehicle.	Integer	Bit-Flags	[if sending]	decl
`RC_Wiper`	Setting of the wiper. Only read and written in the vehicle where the reverser is set (or where the user is located).		0: Off 1: Interval 2: Normal 3: Quick 4: Cleaning liquid 5 and bove: User defined		decl
`RC_PIS_Line`	Serves to transmit the described line number (0 to 65535), the special character code (0 to 4095) and offers still place for a freely usable value (0 to 15, see below table). Here a special coding takes place, which combines both values when sending and separates them again when receiving: Send: RC_PIS_Line := ( {specchar} and $FFF) + ( {line} and $FFFF) shl 12 + ( {free value} and $F) shl 28; Receive: {specchar} := RC_PIS_Line and $FFF; {line} := (RC_PIS_Line shr 12) and $FFFF; {free value} := RC_PIS_Line shr 28; Attention: In timetables the special character is not stored; this leads to the fact that in AI vehicles the value {specchar} is not contained in this variable (= 0). In this case, the special character must be fetched using the `PIS_GetRouteSpecialCharCode` function via the route information.	Integer		[if sending]	decl
`RC_PIS_Terminus`	Serves to transmit the internal index of the displayed terminus (corresponds to "TERMINUS_LISTINDEX" of the standard modules of the base content vehicles, -1 if no valid route) and offers still place for a freely usable value (0 to 65535, see below table). If no free value is to be used, only the destination index must be transferred 1:1. Otherwise a special coding is done, which combines both values when sending and separates them again when receiving: Send: RC_PIS_Terminus := ( {Zielindex} and $FFFF) + ( {freier Wert} and $FFFF) shl 16; Receive: {terminusindex} := RC_PIS_Terminus - (RC_PIS_Terminus and $FFFF0000); {freevalue} := RC_PIS_Terminus shr 16; Attention: In the case of AI vehicles, it is usually the case that the number 65535 (or $FFFF) is transferred as the terminus index! In this case the AI would like that the terminus is to be taken by FIS file from line and route! Since the destination is dependent on the current stop, the RC variable RC_PIS_StopSeq is to be used, even if this is not yet written by the AI.	Integer		[if sending]	decl
`RC_PIS_Route`	Serves to transmit the internal index of the selected route (corresponds to "ROUTE_LISTINDEX" of the standard modules of the BaseContent vehicles, -1 if no valid route) and offers still place for a freely usable value (0 to 65535, see below table). If no free value is to be used, only the route index must be transferred 1:1. Otherwise a special coding is done, which combines both values when sending and separates them again when receiving: Send: RC_PIS_Route := ( {routeindex} and $FFFF) + ( {freevalue} and $FFFF) shl 16; Receive: {routeindex} := RC_PIS_Route - (RC_PIS_Route and $FFFF0000); {freevalue} := RC_PIS_Route shr 16;	Integer		[if sending]	decl
`RC_PIS_StopSeq`	Serves to transmit the index of the current stop within the selected route (corresponds to "STOP_SEQ" of the standard modules of the BaseContent vehicles, -1 if no valid route or stop) and still offers space for a freely usable value (0 to 65535, see below table). If no free value is to be used, only the stop index must be transferred 1:1. Otherwise a special coding is done, which combines both values when sending and separates them again when receiving: Send: RC_PIS_StopSeq:= ( {stopseq} and $FFFF) + ( {freevalue} and $FFFF) shl 16; Receive: {stopseq} := RC_PIS_StopSeq- (RC_PIS_StopSeqand $FFFF0000); {freevalue} := RC_PIS_StopSeq shr 16;	Integer		[if sending]	decl

2.1 About the RC_PIS variables

Like all other RC variables, they have a dual role, which is particularly important here: On the one hand, they serve to transmit the PIS state between the multiplayer vehicles, i.e. the user vehicle sends its PIS state to the server and the server distributes this information to the vehicles of the other players; on the other hand, they serve to communicate between the AI controller, the visual vehicle and - depending on the variable - also the passengers. For this reason, there is the division into a fixed value and a free value described in more detail above. The free value is used to transmit optional state values that go beyond the scope of those in the fixed value. Nevertheless, it must not be forgotten that the AI does not supply these optional state values! I.e. an AI vehicle receives only the fixed values, the free values are always 0. Nevertheless, also in this case must be described sensibly! Conversely, the passengers expect valid values among the fixed values! They cannot process the optional values. However, at the moment - and probably also in the future - the passengers are limited to the variable RC_PIS_Terminus.

Vehicles

2.2 General

Variable name	Description	Type	Unit	Write access	Decl.
`v_ground`	Speed in the direction along the vehicle	Single	Meters per second		decl
`a_ground`	Acceleration in the direction along the vehicle	Single	Meters per square second		decl
`panto_voltage_{a}`	Catenary voltage available at the pantograph with index `{a}`. Trolley: trolley is connected with a catenary wire and this wire is powered. Pantograph: The lowest catenary wire (the height if which is passed through) is powered. Whether the pantograph itself is raised must be checked by the script.	boolean	-		decl
`panto_{a}`	Height of the lowest catenary wire reachable by the (single or double) pantograph with index `{a}`. The result is represented in the coordinate system of the vehicle object plus the movement state of the associated animation.	Single	m		decl
`trolley_angle_{a}_hori, trolley_angle_{a}_vert`	Displacement of the trolley rod with index `{a}` horizontally compared to the middle position (_hori) or vertically compared to the horizon (_vert) of the vehicle object plus the movement state of the associated animation. You can only write as long at the trolley rod is connected to the wire. You can use this to implement protection mechanisms against the derailment of the trolley rod.	Single	Degrees(°)	[X]	decl
`trolley_free_{a}`	Trolley with index `{a}` is free: it is not connected to a trolley wire nor is it being moved by a user.	Boolean	-		decl
`trolley_online_{a}`	Trolley with index `{a}` is connected to the trolley wire.	Boolean	-		decl
`TextureRaindropSet_{x}`	Texture index of the rain drop window with index `{x}` (0 based).	Integer	-		ex
`coupled_{a}`	Coupled at the front (a = 0) or rear (a = 1). Is true when another vehicle is coupled and the coupling is secure.	Boolean	-		ex
`couplingState_{a}`	Coupling state: 0: Coupler deactivated, when attempting to couple nothing happens, "only buffers" 1: Coupler ready, when driving up coupling will take place - Automatic coupler 2: Coupled Front: a = 0, Rear: a = 1.	Integer	-	[X]	ex
`couplingOffsetY_{a}`	Temporarily move the coupler in the Y direction. E.g. on the GT6N when the couplers are being retracted. Front: a = 0, rear: a = 1.	Single	-	[X]	decl

2.3 Rail

Variable name	Description	Type	Unit	Write access	Decl.
`M_Axle_N_{b}_{a}`	Traction force of the wheel at the point of contact with the rail. This also includes forces from the electronic brake. `{b}` = Index of the bogie, `{a}` = Index of the axle, all 0 based.	Single	Newton	X	decl
`MBrake_Axle_N_{b}_{a}`	Braking force of the wheel at the point of contact with the rail. Only positive values; these work against the driving direction and are able to stop and hold a train on a gradient. `{b}` = Index of the bogie, `{a}` = Index of the axle, all 0 based.	Single	Newton	X	decl
`sanding_{b}_{a}`	Sanding. When set to true this axles is being sanded. `{b}` = Index of the bogie, `{a}` = Index of the axle, all 0 based.	Boolean	-	X	decl
`F_RailBrake_Bogie_N_{b}`	Contact force of a rail brake on bogie number `{b}` (0 based). The effect depends on the current coefficient of friction of the rails. Always works against the direction of travel and able to stop and hold the train on a gradient.	Single	Newton	X	decl
`v_Axle_mps_{b}_{a}`	Speed of the wheel at point of contact with the rails. If the wheel is not blocking or spinning this is equal to the speed of the vehicle. `{b}` = Index of the bogie, `{a}` = Index of the axle, 0 based.	Single	Meters per second		ex
`alpha_Axle_deg_{b}_{a}`	Angle or rotation of the axle. `{b}` = Index of the bogie, `{a}` = Index of the axle, 0 based.	Single	Degrees (°)		ex
`spring_Axle_m_{b}_{a}`	Actual deflection of the axle suspension (primary suspension) from the zero position. The zero position if the position of the spring when the wagon stands quietly on a horizontal track without load. `{b}` = Index of the bogie, `{a}` = Index of the axle, 0 based.	Single	Meter		ex
`loadforce_Axle_N_{b}_{a}`	Actual contact force of an axle on the rails. `{b}` = Index of the bogie, `{a}` = Index of the axle, 0 based.	Single	Newton		decl
`invradius_abs_max`	Maximal curvature of the track section underneath the axles of this vehicle. The curvature is the reciprocal of the radius: 200m radius = 0.005 curvature, 100m radius = 0.01 curvature	Single	1 / m		decl
`invradius_{b}_{a}`	Current curvature of the track section under an axle. `{b}` = Index of the bogie, `{a}` = Index of the axle, 0 based.	Single	1 / m		decl
`railquality_{b}_{a}`	Track alignment and quality under the axle: ( `{b}` = index of the bogie, `{a}` = index of the axle, each based on 0) 0 = Even profile 1 = uneven profile 2 = with frogs, even 3 = with frogs, uneven 4 = Flat groove 5 = Very uniform profile (e.g. high-speed line) 6 = Dirty with even profile 7 = Dirty with uneven profile	Integer	-		decl
`surfacetype_{b}_{a}`	Surface type underneath the track (`{b}` = Index of the bogie, `{a}` = Index of the axle, 0 based). 0 = Normal (Gravel) 1 = Street 2 = Grass	Integer	-		decl
`V_ThirdRailCollector_{b}_{L/R}`	It is checked whether there is a third rail next to the bogie with the index `{b}` on the side `L` and/or `R` and what voltage is present there.	Single	-1.0: next to the bogie is no third rail -0.5: next to the bogie is partial a third rail 0: Third rail next to bogie, no voltage 1: Third rail next to bogie, normal voltage		decl

Note: when replacing the indices in the variable names you also remove the accolades! Example: loadforce_Axle_N_{b}_{a} on the first bogie, second axle is loadforce_Axle_N_0_1.

2.4 Street

Variablenname	Beschreibung	Typ	Einheit	Schreibzugriff	Dekl.
Steering	Steering angle, related to the maximum steering angle	Single	-1 (full L) ... +1 (full R)	X	decl
M_Axle_N_{a}	Traction force of the wheels of an axle at the contact point with the road. This includes the forces of the engine and/or gearbox brake. `{a}` = Index of the axle, 0 based.	Single	Newton	X	decl
MBrake_Wheel_N_{a}_{s}	Braking force of a wheel of an axle at the contact surface with the road. Only positive values; these always act against the direction of travel and have the ability to hold the vehicle on a gradient. `{a}` =Index of the axle, 0 based, `{s}` = side, 0 = L, 1 = R	Single	Newton	X	decl
v_Wheel_mps_{a}_{s}	Speed of the wheel at its contact with the road. If the wheel is neither locked nor spinning, this speed is the vehicle speed. `{a}` = Index of the axle, 0 based, `{s}` = side, 0 = L, 1 = R	Single	Meter per second		ex
alpha_Wheel_deg_{a}_{s}	Rotation angle of the wheel. `{a}` = Index of the axle, 0 based, 0-basiert, `{s}` = side, 0 = L, 1 = R	Single	Degrees (°)		ex
spring_Wheel_m_{a}_{s}	Current deflection of the wheel suspension from the zero position. The zero position is the position in which the spring is when the car is fully raised so that the wheel no longer touches the ground. `{a}` = Index of the axle, 0 based, `{s}` = side, 0 = L, 1 = R	Single	Meter		ex
steering_Wheel_m_{a}_{s}	Angle of rotation of the wheel due to the steering angle around the vertical axis. `{a}` = Index of the axle, 0 based, `{s}` = side, 0 = L, 1 = R	Single	Degrees (°), >0 = R		ex

Note: when replacing the indices in the variable names you also remove the accolades! Example: MBrake_Wheel_N_{b}_{a} on the first axle, right side is MBrake_Wheel_N_0_1.

3 Scenery Objects

Variable name	Description	Type	Unit	Write access	Decl.
`trafficlight_phase`	Current phase of the traffic light system and direction: 0..2 = three different red phases 3..5 = three different yellow phases for red to green 6..8 = three different green phases 9..11 = three different yellow phases for green to red. 12 = traffic light disabled for the primary (priority) direction 13 = traffic light disabled for the secondary (yield priority) direction 14..16 = three different phases for other purposes	Integer	-		decl

4 System Events

The underlying system for the System Events is understandable as follow: There are certain internal LOTUS events that should be triggered from within the vehicle. These triggers should not only be triggered by a keyboard shortcut but also by using mouse click hotspots in the vehicles. At the moment System Events are not listed when you want to assign a mouse event to a vehicle mesh. Instead System Events have to be typed in manually.

Event-Name	Function
`TrolleyRerail_{a}`	Used to attaching (again) the trolley rod to the overhead wires. For this the marked click hotspot is clicked, the mouse button is held down and moved to turn and raise/lower the trolley rod. At the wanted position the mouse button is released.

5 System Send Events

A script can also trigger certain events in LOTUS. For this there is procedure SendEvent(self: integer, id: string, value: integer). The first parameter must always be the Public Var "Self" (declared automatically by LOTUS). The following IDs can be used:

Event-ID	Function
`TrolleyDerail`	Derails the trolley rod "on purpose". For value fill out the index of the current collector that should be derailed.