9. Further Open Rails Rolling Stock Features

For a full list of parameters, see Developing OR Content - Parameters and Tokens

9.1. Train Engine Lights

OR supports the whole set of lights accepted by MSTS, MSTS-bin, and adds many new options to enhance the variety and complexity of lighting systems that can be recreated.

9.1.1. Lights with multiple conditions

In the original MSTS light implementation, each light could only have one set of activation conditions. If the same light were to be activated in multiple situations, (for example, a light which should turn on for both the front and rear units) the entire light would need to be included twice, just with different conditions.

Open Rails now allows for a single light to have multiple Conditions () blocks. If any one set of conditions is fulfilled, the light will be enabled. If no conditions are specified, the light will be assumed to be on always. An example of how this can be used to simplify Lights implementation is included below:

Light   (
        comment( Nose light bright )
        Conditions      (
                Headlight ( 3 )
                Unit ( 2 )
        )
        FadeIn  ( 0.5 )
        FadeOut ( 0.5 )
        States  (       1
                State   (
                        LightColour ( FFffffe6 )
                        Radius ( 0.6 )
                        Position ( 0.0 4.12 6.55 )
                )
        )
)
Light   (
        comment( Nose light bright DPU )
        Conditions      (
                Headlight ( 3 )
                Unit ( 4 )
        )
        FadeIn  ( 0.5 )
        FadeOut ( 0.5 )
        States  (       1
                State   (
                        LightColour ( FFffffe6 )
                        Radius ( 0.6 )
                        Position ( 0.0 4.12 6.55 )
                )
        )
)

This set of two lights can be simplified to one light like this:

Light   (
        comment( Nose light bright )
        Conditions      (
                Headlight ( 3 )
                Unit ( 2 )
        )
        Conditions      (
                Headlight ( 3 )
                Unit ( 4 )
        )
        FadeIn  ( 0.5 )
        FadeOut ( 0.5 )
        States  (       1
                State   (
                        LightColour ( FFffffe6 )
                        Radius ( 0.6 )
                        Position ( 0.0 4.12 6.55 )
                )
        )
)

Both of these snippets produce the same result: a light that turns on when the headlights are bright and the unit is first, or the last unit reversed (ie: distributed power). However, by specifying multiple conditions, the second implementation takes up much less space and guarentees that both modes of the light have the exact same States. There is no hard limit on the number of conditions a light can have.

9.1.2. Lights attached to shape sub-objects

The standard lighting configuration attaches all lights to the main body of the locomotive or wagon. While this allows lights to move and rotate as the vehicle itself moves, the approach has proven insufficient for more complicated rail vehicles such as articulated steam locomotives.

To facilitate lighting on such locomotives and wagons, Open Rails now allows for attachment of lights to any sub-object of the shape file. With the ShapeHierarchy token placed in a Light () block, the object the light will rotate and translate with can be defined using the hierarchy name of said object. Tools such as Shape Viewer can be used to determine the hierarchy name of a particular object in the shape file. For example, “BOGIE1” is the standard name for the frontmost bogie. A light attached to this bogie could be created like so:

Light   (
        comment( CNDR Side Front Truck Light )
        ShapeHierarchy ( "BOGIE1" )
        States  (       1
                State   (
                        LightColour ( 91fedf91 )
                        Position ( -1.427 0.583 -0.330 )
                        Azimuth ( -90 -90 -90 )
                        Radius ( 0.2 )
                )
        )
)

Be aware that the Position of a light is measured relative to the center of the object to which the light is attached, not to the center of the locomotive itself. Furthermore, the naming of shape parts is not consistent between all shape files. If the shape name entered in ShapeHierarchy is invalid, a warning will be produced in the log file and the light will attach to the main body of the locomotive or wagon.

If ShapeHierarchy is not specified in a light, the light will attach to the main body of the locomotive or wagon by default.

9.1.3. Open Rails specific lighting conditions

Open Rails also adds a set of new lighting conditions which offer additional flexibility in creating detailed light behaviors. Note that each of these must be inside the Conditions () block of a Light () in the .eng/.wag file to function. All conditions are optional and can be mixed and matched as needed, though only one of each condition can be included per conditions block!

9.1.3.1. Battery

The light condition ORTSBattery allows a light to respond to the state of the battery subsystem. The valid settings and associated conditions for the light to turn on are as follows:

  • ORTSBattery ( 0 ) Battery state is ignored (default)

  • ORTSBattery ( 1 ) Battery switch must be on

  • ORTSBattery ( 2 ) Battery switch must be off

9.1.3.2. Friction Brakes

The Brake condition can be used to create brake indicator lights which turn on or off when the friction brakes are applied. Dynamic brakes have no effect.

  • Brake ( 0 ) Brake application/release is ignored (default)

  • Brake ( 1 ) Brakes must be released

  • Brake ( 2 ) Brakes must be applied

9.1.3.3. Reverser

Reverser is a very powerful condition that gives lights the ability to be enabled by the selected direction of travel. Note that a flipped locomotive or wagon will automatically flip the sensed reverser setting to ensure lights shine in the correct direction. Also, steam locomotive cutoff values between -10% and 10% will be detected as ‘neutral’.

  • Reverser ( 0 ) Reverser direction is ignored (default)

  • Reverser ( 1 ) Reverser direction must be forward

  • Reverser ( 2 ) Reverser direction must be reverse

  • Reverser ( 3 ) Reverser direction must be neutral

  • Reverser ( 4 ) Reverser direction must be forward or reverse

  • Reverser ( 5 ) Reverser direction must be forward or neutral

  • Reverser ( 6 ) Reverser direction must be reverse or neutral

9.1.3.4. Passenger Doors

Many pieces of passenger rolling stock have indicator lights to inform the crew passenger doors are open. The Doors condition is suited to this type of lighting.

  • Doors ( 0 ) Passenger doors are ignored (default)

  • Doors ( 1 ) Passenger doors must all be closed

  • Doors ( 2 ) Passenger doors on the left must be open

  • Doors ( 3 ) Passenger doors on the right must be open

  • Doors ( 4 ) Passenger doors on both sides must be open

  • Doors ( 5 ) Passenger doors on either the left or right must be open

9.1.3.5. Horn (Automatic Flashing Ditch Lights)

Open Rails now supports the ability to configure flashing ditch lights (or any other type of horn activated auxiliary lighting) with the Horn light condition. When the horn is sounded, lights with the horn condition will (de)activate, and remain (de)activated for a time after the horn stops sounding. The standard timer is 30 seconds, but can be changed by placing a ORTSHornLightsTimer token in the engine() section of the locomotive with flashing lights. If ORTSHornLightsTimer( 0s ) is set, the lights will only activate while the horn is sounding and immediately stop afterward.

  • Horn ( 0 ) Horn state is ignored (default)

  • Horn ( 1 ) Horn must not have been sounded recently

  • Horn ( 2 ) Horn must have been sounded recently

Note that the solid ditch lights state should use Horn(1) to prevent these lights overlapping the flashing state. An example implementation of a flashing ditch light’s conditions (many other details removed for clarity) is provided below:

Light   (
        comment( Right ditch light )
        Conditions      (
                Headlight ( 3 )
                Unit ( 2 )
                Horn ( 1 )
        )
        States  (       1
                State   (
                        LightColour ( FFFFFFFF )
                        Radius ( r )
                        Position ( x y z )
                )
        )
)
Light   (
        comment( Right ditch light Flashing )
        Conditions      (
                Headlight ( 3 )
                Unit ( 2 )
                Horn ( 2 )
        )
        States  (       2
                State   (
                        LightColour ( FFFFFFFF )
                        Radius ( r )
                        Transition ( 1 )
                        Duration ( 0.5 )
                        Position ( x y z )
                )
                State   (
                        LightColour ( FFFFFFFF )
                        Radius ( r )
                        Transition ( 1 )
                        Duration ( 0.5 )
                        Position ( x y z )
                )
        )
)

9.1.3.6. Bell (Automatic Flashing Ditch Lights)

Similar to Horn, the Bell condition is useful for replicating systems with flashing lights activated by the bell, though this is less common than using the horn. Like with the horn, a timer can be set to keep the lights activated for a time after the bell starts ringing. Unlike with the horn, this timer is set to 0 seconds by default, meaning the lights will only remain (de)activated while the bell is currently ringing. If a timer is desired, engine(ORTSBellLightsTimer can be used in the locomotive’s .eng file.

  • Bell ( 0 ) Bell state is ignored (default)

  • Bell ( 1 ) Bell must not have been ringing recently

  • Bell ( 2 ) Bell must have been ringing recently or is ringing now

9.1.3.7. Multiple Unit Configuration (Locomotives Only)

Some MU systems send headlight signals through the wires connecting locomotives, but do not or cannot send these signals through wagons/coaches to remote locomotives (eg: distributed power, banking locomotives, etc.). The MU light condition allows for some flexibility in adjusting light behavior depending on a locomotive’s physical connection to the lead locomotive (or lack thereof). While meant for locomotives only, wagons are always treated as remote locomotives for the purposes of calculation.

  • MU ( 0 ) Locomotives’s connection to the lead locomotive is ignored (default)

  • MU ( 1 ) Locomotive must be the lead locomotive itself

  • MU ( 2 ) Locomotive must be in the same group of locomotives as the lead locomotive
    • This condition will also be fulfilled for the lead locomotive itself.

  • MU ( 3 ) Locomotive must be in a different group to the lead locomotive

9.1.4. Multiple type locomotive light glows

9.1.4.1. Introduction

As a default all OR (and MSTS) locomotives use the same texture to reproduce the glow of their lights. This however doesn’t allow to easily implement non-round or LED array lights, neither to provide special glowing effects.

This feature allows to specifiy customized light glow textures for the locomotives. If nothing is specified, the standard light glow texture is used. Moreover in the Content folder, two light glow textures are present: the “historical” one, and a new one, more realistic. As a default the “historical” light glow texture is used, for backwards compatibility; however adding a line to the Lights block in the .eng file the “new” light glow texture is taken. Customized light glow textures can be either used for all lights of a loco, or only for a subset of them. Different lights in the same locomotive may have different customized light glow textures.

9.1.4.2. Detailed spec

  1. In the Content folder there is the default LightGlow.png, which is displayed if no changes are done to the .eng file.

  2. In such folder there is also an ORTSLightGlow.png, which is maybe more realistic.

  3. adding a line within the .eng file it is possible to select either ORTSLightGlow.png or any other picture with extension .png, .jpg, bmp, .gif, .ace, or .dds.

    Here an example for the legacy Acela loco:

    Lights  ( 17
            ORTSGraphic ( "ORTSLightGlow.png" )
                  Light     (
                          comment( Sphere of light )
                          Type      ( 1 )
                          Conditions        (...
    

The code first searches for the .png file by building its directory starting from the directory of the .eng file; in this case the line could be e.g.:

ORTSGraphic ( "ORTSAcelaLightGlow.png" )
  1. The ORTSGraphic line can be added also for one or more Light() blocks. In that case the .png file is used only for the related Light block. Here an example:

    Light       (
                        comment( Head light outer right bright )
                        Type            ( 0 )
                        Conditions      (
                                Headlight ( 3 )
                                Unit ( 2 )
                                )
                        FadeIn  ( 0.5 )
                        FadeOut ( 0.5 )
                        Cycle   ( 0 )
                        States  (       1
                                State   (
                                        Duration ( 0.0 )
                                        LightColour ( ffffffff )
                                        Position ( -0.5922 2.4037 9.63208 )
                                        Azimuth ( 0.0 0.0 0.0 )
                                        Transition ( 0 )
                                        Radius ( 0.60 )
                                        Elevation ( -50 -50 -50 )
                                        )
                                )
                        ORTSGraphic (BigLightGlow.png)
    )
    

OR searches for the file as it does for the general file for all lights, as explained above. If the ORTSGraphic line is present both at the top of the Lights() and also in some Light() subblock, the line present in the subblock prevails. So it is possible to have an .eng-specific graphic for all the lights, except the ones that have an own ORTSGraphic line.

9.2. Tilting trains

OR supports tilting trains. A train tilts when its .con file name contains the tilted string: e.g. ETR460_tilted.con.

_images/features-tilting.png

9.3. Freight animations and pickups

9.3.1. OR implementation of MSTS freight animations and pickups

OR supports the freight animations as MSTS does (refueling of water, coal and diesel); when refueling from a water column the animation of the column arm is supported; coal level in the tender of the player loco decreases with consumption and increases when refueling.

The following pickup parameters are taken into consideration by OR for the MSTS animations:

  • Pickup type

  • Speed range

  • Anim length

The pickup animation frame rate is computed as the ratio between the number of frames defined in the .s file, divided by the Anim length.

As in MSTS, Freight Animations are treated differently for tenders than for other vehicles.

Tenders:

  • First numeric parameter: shape vertical position when full, relative to its origin, in meters

  • Second numeric parameter: shape vertical position when empty, relative to its origin, in meters.

  • Third numeric parameter: set to any positive value, or omitted, causes the shape to drop - see below.

    • As long as the second parameter is lower than the first and the third parameter is either omitted or has a non-zero value, the shape will drop, based on fuel consumption.

    • If the second parameter is not lower than the first, no movement will take place irrespective of the 3rd parameter.

Other Vehicles:

  • The numeric parameters are not used.

9.3.2. OR specific freight animations and pickups

9.3.2.1. General

In addition to the support of the MSTS freight animations, Open Rails provides a large extension for freight animations (called OR freightanims below) and pickups.

Following are the native features Open Rails offers:

  • two types of OR freightanims: continuous and static

  • continuous OR freightanims are related to commodity loads, like coal, or stones: the load level in the trainset varies accordingly to the amount of load

  • static OR freightanims are in fact additional shapes that can be attached to the main trainset shape. Such shapes may also include an animation (independent from train behaviour);

  • both types of OR freightanims can be present in the same trainset, and can coexist with original MSTS freight animations

  • both types of OR freightanims can be related to locomotives or wagons

  • more than one static OR freightanim can be present in a single trainset

  • a wagon can be loaded with different commodities in different moments

  • commodities can be loaded (in pickup stations) and unloaded (in unloading stations).

  • wagons supporting continuous OR freightanims may be provided with a physical animation that is triggered when unloading the wagon (like opening its bottom or fully rotating)

  • OR freightanims are defined with an ORTSFreightAnims () block within the .wag or within the wagon section of an .eng file. It is suggested that this block be defined within an include file as described here.

9.3.2.2. Continuous OR Freightanims

A description of this feature is best achieved by showing an example of an include file, (in this case named AECX1636.wag and located in an Openrails subfolder within the wagon’s folder). Note that the first line of the file must be blank.:

include ( ../AECX1636.wag )

Wagon (
    ORTSFreightAnims
    (
        MSTSFreightAnimEnabled (0)
        WagonEmptyWeight(22t)
        IsGondola(1)
        UnloadingStartDelay (7)
        FreightAnimContinuous
        (
            IntakePoint ( 0.0 6.0 FreightCoal )
            Shape(Coal.s)
            MaxHeight(0.3)
            MinHeight(-2.0)
            FreightWeightWhenFull(99t)
            FullAtStart(0)
        )
        FreightAnimContinuous
        (
            IntakePoint ( 0.0 6.0 FuelCoal )
            Shape(Coal.s)
            MaxHeight(0.3)
            MinHeight(-2.0)
            FreightWeightWhenFull(99t)
            FullAtStart(0)
        )
    )
)

The ORTSFreightAnims block is composed by a set of general parameters followed by the description of the OR freightanims. Here below the general parameters are described:

  • MSTSFreightAnimEnabled specifies if eventual MSTS freight animations within the trainset are enabled (1) or not (0). This is useful if one wants to use a wagon where the load is already shown with a (static) MSTS freight animation. In such a case the MSTS freight animation must be disabled, to use the OR freightanim, that allows to modify the vertical position of the freight shape.

  • WagonEmptyWeight defines the mass of the wagon when empty. If the parameter is missing, the weight of the load is not considered and the weight of the wagon is always the value present in the root .eng file.

  • IsGondola specifies (in case it is set to 1) if the load has to be rotated during unloading, as happens in a gondola wagon. If absent the parameter is set to 0.

  • UnloadingStartDelay specifies, if present, after how many seconds after pressing of the T key the unloading starts. This is due to the fact that some seconds may be needed before the wagon is set in a unloading layout. For example, a gondola must rotate more than a certain number of degrees before the load begins to fall down.

There may be more than one FreightAnimContinuous subblock, one for each possible load type. The parameters of the subblock are described below:

  • IntakePoint has the same format and the same meaning of the IntakePoint line within the standard MSTS freight animations. Following types of loads are accepted: FreightGrain, FreightCoal, FreightGravel, FreightSand, FuelWater, FuelCoal, FuelDiesel, FuelWood, FuelSand, FreightGeneral, FreightLivestock, FreightFuel, FreightMilk, SpecialMail. All these types of loads can be defined. Some of the pickup types (to right of FuelDiesel) need to be coded in W text files.

  • Shape defines the path of the shape to be displayed for the load

  • MaxHeight defines the height of the shape over its 0 position at full load

  • MinHeight defines the height of the shape over its 0 position at zero load

  • FreightWeightWhenFull defines the mass of the freight when the wagon is full; the mass of the wagon is computed by adding the mass of the empty wagon to the actual mass of the freight

  • FullAtStart defines wether the wagon is fully loaded (1) or is empty at game start; if there are more continuous OR freightanims that have FullAtStart set to 1, only the first one is considered.

As already outlined, the wagon may have a physical animation linked with the unload operation.

In a gondola this could be used to rotate the whole wagon, while in a hopper it could be used to open the bottom of the wagon.

The base matrix within the wagon shape that has to be animated must have a name that starts with UNLOADINGPARTS. There may be more than one, like UNLOADINGPARTS1, UNLOADINGPARTS2 and so on. Its frame rate is fixed, and is 1 frame per second as for the other types of OR trainset animations.

To define a pickup point as an unload point, its shape must be inserted in the .ref file of the route as a pickup object . Here is an example of the .ref block:

Pickup (
    FileName ( rotary_dump.s )
    Shadow ( DYNAMIC )
    Class ( "Track Objects" )
    PickupType ( _FUEL_COAL_ )
    Description ( "Rotary dumper" )
)

When laying it down in the route with the MSTS Route Editor, its fill rate must be set to a negative value.

Such a pickup (which in reality is an unloader) may be animated too. The base matrix within the wagon shape that has to be animated must have a name that starts with ANIMATED_PARTS. There may be more than one, like ANIMATED_PARTS1, ANIMATED_PARTS2 and so on. As for the MSTS standard pickups, the pickup animation frame rate is computed as the ratio between the number of frames defined in the .s file, divided by the Anim length.

By combining a physical animation of the wagon with an unloader animation effects like that of a wagon within a rotary dumper may be achieved, as seen in the picture below.

_images/features-freightanim.png

Loading and unloading a trainset is triggered by pressing the <T> key when the trainset is at the pickup/unloader location.

9.3.2.3. Static OR Freightanims

Only the two general parameters shown below are used for static OR freightanims:

MSTSFreightAnimEnabled (0)
WagonEmptyWeight(22t)

The subblock (to be inserted within the ORTSFreightAnims block) has the following format:

FreightAnimStatic
(
    SubType(Default)
    Shape(xxshape.s)
    Offset(XOffset, YOffset, ZOffset)
    FreightWeight(weight)
    Flip()
    Visibility ( "Outside,Cab2D,Cab3D" )
)

Where:

  • SubType is not currently used

  • Shape is the path of the shape file.

  • XOffset, YOffset and ZOffset are the offsets of the shape with respect to its zero position, and are useful to place the shape precisely.

  • FreightWeight is the weight of the specific load. This weight is added to the WagonEmptyWeight value (if present) to provide the total weight of the wagon. If more static OR freightanims are present, each of their weights is added to define the total weight of the wagon.

  • Flip(), if present, flips the shape around its pivot point.

  • Visibility, if present, changes the default visibility of the static freightanim. Default is visible only from outside cameras and from any inside camera of locomotives different from the one hosting the static freightanim. If substring Outside is present, the static freightanim is visible from outside cameras and from any inside camera of locomotives different from the one hosting the static freightanim; if Cab2D is present, the static freightanim is visible from the 2D cabview camera of loco hosting the freightanim; if Cab3D is present, the static freightanim is visible from the 3D cabview camera of loco hosting the freightanim. 1, 2 or 3 of such substrings may be inserted in the Visibility line allowing for any combination of visibility.

Because more static OR freightanims may be defined for a wagon, in the case of a container wagon that is able to carry more than one container, even as a double stack, it is possible to use a static OR freightanim for each container, defining its position within the wagon.

9.3.3. Physics Variation with Loads

9.3.3.1. Variable Loads (Continuous Freight Animation)

Open Rails supports the variation of key physics parameters in the wagon as the load varies within the wagon. The parameters which can be changed are:

  • Mass

  • Brake and handbrake force

  • Friction (general and wind)

  • Centre of Gravity (impacts on curve performance)

  • Drive wheel weight (impacts upon locomotive adhesve weight)

Locomotives and tenders that are also configured will have their loads, and the above physics parameters adjusted as coal and water is used. The adhesive weight (Drive wheel weight) will also be adjusted as the load changes.

To support the correct operation of this feature a known physics starting and finishing point is required, ie the state of these parameters under empty conditions, and the state of these parameters when the wagon or locomotive is full.

To configure the stock correctly the following empty and full parameters need to be included in the ORTSFreightAnims file. Empty values are included in the first block, and full values are included in the second code block. A sample code block is shown below:

  ORTSFreightAnims
  (
    MSTSFreightAnimEnabled (0)
    WagonEmptyWeight(10.0t-uk)
    EmptyMaxBrakeForce ( 29.892kN )
    EmptyMaxHandbrakeForce ( 9.964kN )
    EmptyORTSDavis_A ( 580.71 )
    EmptyORTSDavis_B ( 5.0148 )
    EmptyORTSDavis_C ( 0.694782 )
    EmptyORTSWagonFrontalArea ( 10.0m )
    EmptyORTSDavisDragConstant ( 0.0003 )
    EmptyCentreOfGravity_Y ( 1.41 )
    IsGondola(0)
    UnloadingStartDelay (5)

  FreightAnimContinuous
   (
    IntakePoint ( 0.0 6.0 FreightCoal )
    Shape(H_Coal.s)
    MaxHeight(0.1)
    MinHeight(-0.85)
    FreightWeightWhenFull(26.0t-uk)
    FullAtStart( 0 )
    FullMaxBrakeForce ( 89.676kN )
    FullMaxHandbrakeForce ( 9.964kN )
    FullORTSDavis_A ( 748.61 )
    FullORTSDavis_B ( 18.0157 )
    FullORTSDavis_C ( 0.838530 )
    FullORTSWagonFrontalArea ( 15.0m )
    FullORTSDavisDragConstant ( 0.005 )
    FullCentreOfGravity_Y ( 1.8 )
   )
)

For some rolling stock, it may be more realistic to handle variations in load/empty brake force by changing the brake cylinder pressure developed, rather than changing the brake force directly. In such cases, the empty/load relay valve parameters work best. Unlike other freight physics parameters, the relay valve ratio will not change continuously as freight is loaded. Instead, when the freight load is above 25% capacity, the loaded relay valve ratio is used, otherwise the empty ratio (or the ratio defined in the main .wag file) is used. The level of brake cylinder in-shot can also be changed depending on the load level as is often the case on load proportioning equipment. The standard behavior of these parameters is defined in more detail in the air brakes physics section.

Here is an example of a gondola with a 50% load/empty valve:

ORTSMaxBrakeShoeForce ( 31300lb )
MaxHandbrakeForce ( 32000lb )

ORTSFreightAnims (
    MSTSFreightAnimEnabled ( 0 )
    WagonEmptyWeight( 28.9t-us )

    EmptyBrakeRelayValveRatio ( 0.5 )
    EmptyBrakeRelayValveInshot ( -15psi )

    ORTSDavis_A ( 87.35lbf )
    ORTSDavis_B ( 0.289lbf/mph )
    ORTSDavis_C ( 0.144lbf/mph^2 )
    ORTSWagonFrontalArea ( 120ft^2 )
    ORTSDavisDragConstant ( 0.0012 )
    EmptyCentreOfGravity_Y ( 1.377 )
    IsGondola( 1 )
    UnloadingStartDelay ( 5 )

    FreightAnimContinuous (
        IntakePoint ( 0.0 6.0 FreightCoal )
        Shape ( COAL_LOAD.s )
        MaxHeight ( 0.0 )
        MinHeight ( -2.2 )
        FreightWeightWhenFull ( 114.1t-us )
        FullAtStart ( 0 )

        FullBrakeRelayValveRatio ( 1.0 )
        FullBrakeRelayValveInshot ( 0psi )

        FullORTSDavis_A ( 258.5lbf )
        FullORTSDavis_B ( 1.43lbf/mph )
        FullORTSDavis_C ( 0.0504lbf/mph^2 )
        ORTSWagonFrontalArea ( 120ft^2 )
        ORTSDavisDragConstant ( 0.00042 )
        FullCentreOfGravity_Y ( 2.251 )
    )
)

Note for enclosed wagons, such as covered vans, the freight animation shape may not be required, and therefore the parameters Shape, MaxHeight, and MinHeight can be left out of the file.

The IntakePoint statement is necessary to ensure satisfactory operation of the feature.

Open Rails supports the following freight or fuel load types:

  • FreightGrain = 1,

  • FreightCoal = 2,

  • FreightGravel = 3,

  • FreightSand = 4,

  • FuelWater = 5,

  • FuelCoal = 6,

  • FuelDiesel = 7,

  • FuelWood = 8,

  • FuelSand = 9,

  • FreightGeneral = 10,

  • FreightLivestock = 11,

  • FreightFuel = 12,

  • FreightMilk = 13,

  • SpecialMail = 14

The key word, e.g. FreightMilk, is used to define the freight type in the IntakePoint statement, whilst the number is used to define the pickup point in the route (Replaces the first number in the PickupType ( 1 0 ) statement).

For load variation in a locomotive, a similar configuration is used in regard to the full and empty parameters, but as the IntakePoint statement is normally included elsewhere in the ENG file or tender (or auxiliary tender) WAG file these statements can be left out of the freight animation section.

For example, the following code block would apply to a steam locomotive (note the absence of the IntakePoint statement):

ORTSFreightAnims
(
    WagonEmptyWeight(76.35t-uk)
    EmptyMaxBrakeForce ( 29.892kN )
    EmptyMaxHandbrakeForce ( 9.964kN )
    EmptyORTSDavis_A ( 580.71 )
    EmptyORTSDavis_B ( 5.0148 )
    EmptyORTSDavis_C ( 0.694782 )
    EmptyCentreOfGravity_Y ( 1.41 )

  FreightAnimContinuous
   (
    FreightWeightWhenFull(10.34t-uk)
    FullMaxBrakeForce ( 89.676kN )
    FullMaxHandbrakeForce ( 9.964kN )
    FullORTSDavis_A ( 748.61 )
    FullORTSDavis_B ( 18.0157 )
    FullORTSDavis_C ( 0.838530 )

    FullCentreOfGravity_Y ( 1.8 )
   )
)

Notes:

  • Intake points should be defined within the root WAG file

  • Intake points, freight animations should not be defined within the INCLUDE file

  • Empty weight of tender will be the full mass minus coal and water weight

  • FreightWeightWhenFull will be the sum of the coal and water weight.

  • Full physics values will be those values for the combined weight of the tender, water and coal.

  • The parameters for wind resistance ( ORTSWagonFrontalArea and ORTSDavisDragConstant ) can be left out if the area and drag does not change between the full and empty states.

9.3.3.2. Static wagons (Static Freight Animations)

Static wagons can be defined with a full and empty state, however only one freight animation should have full values assigned to it,as OR cannot then calculate the known full state.

A typical configuration code block will be as follows:

ORTSFreightAnims
(
  MSTSFreightAnimEnabled (0)
  WagonEmptyWeight(6.5t-uk)

FreightAnimStatic
(
  SubType(Default)
  Shape( 15ft_3p_HumpSheet2.s )
  Offset( 0, 0, 0)
  FreightWeight( 9.0t-uk )
  FullMaxBrakeForce ( 19.43kN )
  FullMaxHandbrakeForce ( 6.477kN )
  FullORTSDavis_A ( 358.37 )
  FullORTSDavis_B ( 7.7739 )
  FullORTSDavis_C ( 0.718740 )
  FullORTSWagonFrontalArea ( 15.0m )
  FullORTSDavisDragConstant ( 0.005 )
  FullCentreOfGravity_Y ( 1.8 )
 )
)

The empty values for the wagon will be read from the normal base WAG file paramaters.

9.4. Container management

9.4.1. General

With this feature containers are not static objects laying on earth or on wagons, but may be loaded from a container station onto a wagon, or unloaded from a wagon and laid on a container station. The load/unload operations are performed through a crane, which is the heart of the container station.

_images/features-container.png

The other component of the container station is the set of stack locations, that is the locations where containers may lay. Containers of same length can be stacked one above the other.

Wagons may be empty at game start, or partially or totally pre-loaded with containers, by inserting the related data either in the consist (.con) file or in the .wag files.

Also container stations may be empty at game start, or partially or totally populated with containers, inserting the related data in the activity (.act) file.

The loading and unloading operations are started by the player, by pressing the key <T> for loading, and the key <Shift-T> . The operation is performed on the first wagon (starting from the locomotive) which is within the container crane displacement range and which fulfills the required conditions (e.g. loading space available for loading, container present for unloading).

Double stack wagons are managed.

From a point of view of internal code structure, Open Rails handles container stations as special pickups.

9.4.2. How to define container data

Container shape files (.s) must be located in subfolders (or sub-subfolders) of the Trainset folder. Containers that can be managed must be provided with a Json .load-or file. The .load-or files must be located in a subfolder of the Trainset folder. It is warmly advised to keep all .load-or file in a single folder: Common.ContainerData is suggested. It is also advised to name the .load-or files in a consistent way: 40HCtriton.load-or is suggested, where 40HC is the container type and triton the brand painted on the container.

9.4.2.1. Format of the .load-or file

Here below a sample of a .load-or file:

{
      "Container":
      {
              "Name" : "triton",
              "Shape" : "COMMON_Container_3d\\Cont_40ftHC\\container-40ftHC_Triton.s",
              "ContainerType" : "C40ftHC",
              "IntrinsicShapeOffset": [0,1.175,0],
              "EmptyMassKG": 2100.,
                "MaxMassWhenLoadedKG": 28000.,
        }
}
  • “Container” is a fixed keyword.

  • “Name” has as value a string used by Open Rails when the container must be indentified in a message to the player.

  • “Shape” has as value the path of the container shape, having Trainset as base.

  • “ContainerType” identifies the container type, which may be one of the following ones:

    * C20ft
    * C40ft
    * C40ftHC
    * C45ft
    * C45ftHC
    * C48ft
    * C53ft
    

    C48ft and C53ft have a HC height (2.90m)

  • “IntrinsicShapeOffset” has as value the offset in meters of the center of the bottom rectangle of the container with respect to the container shape file coordinates. Unfortunately often such offset is not [0,0,0], which would be advisable for newly produced containers. A simple way to state such offset is to use the Show Bounding Info of Shape Viewer.

  • “EmptyMassKG” is an optional parameter that defines the tare (weight when empty) of the container. If the parameter is not present, OR uses a default parameter, specific for that ContainerType.

  • “MaxMassWhenLoadedKG” is an optional parameter that defines the sum of the tare plus the maximum allowed payload. As above, if the parameter is not present, OR uses a default parameter, specific for that ContainerType.

9.4.3. Pre-setting a .wag file to accommodate containers

As a minimum following block must be present in the .wag file for a double stacker:

ORTSFreightAnims (
              WagonEmptyWeight ( 12.575t )
              LoadingAreaLength ( 12.20 )
              AboveLoadingAreaLength ( 12.20 )
              DoubleStacker ()
              Offset( 0 0.34 0 )
              IntakePoint ( 0 6.0 Container)
              )
  • WagonEmptyWeight is the weight of the wagon, when it has neither containers nor other weighing freight animations on board

  • LoadingAreaLength is the length in meters of the loading area available for containers

  • AboveLoadingAreaLength is the length in meters of the above loading area available for containers (parameter not needed if not double stacker)

  • DoubleStacker must be present if the wagon allows double stacking

  • Offset is the offset of the center of the rectangle of the loading area with respect to the shape file of the wagon.

  • The first and the third IntakePoint parameters have the same meanings than the ones used for generic pickups. The first parameter must be equal to the Z value of the offset. Container is mandatory.

This ORTSFreightAnims block can include also static freight animations as described in the related paragraph.

9.4.4. Allocation of the containers on the wagons

A container may have following positions within the loading area of the wagon: Rear, CenterRear, Center, CenterFront, Front and Above. Following picture shows where the first five positions are located on the wagon, while Above is the above position in dual-stack configurations. The Above position is always centered.

_images/features-loading-positions.png

Some loading configurations are shown in following picture:

_images/features-loading-configurations.png

From left to right the loading configurations are present (locomotive on the left):

  • CenterFront, CenterRear, Above

  • Center

  • Front, Rear

  • Front, Center, Rear

  • Front, Rear

  • Front, CenterFront, CenterRear, Rear.

The real rules to allocate double-stacked containers must be respected:

  • no 20ft stacked above

  • only one container above

  • at least 40ft of containers below.

9.4.5. How to allocate containers on wagons at start of game

The containers may be allocated either by editing the .con file, or by editing the .wag file, or in a mixed mode (some wagons in one mode, some others in another mode).

9.4.5.1. Allocation through .con file

This allocation mode is the recommended one, as it is more flexible and provides easier visibility.

A wagon entry complete with the data about the containers loaded at startup is shown here:

Wagon (
          WagonData ( DTTX_620040_A ATW.DTTX_620040 )
          LoadData ( 20cmacgm common.containerdata CenterFront Empty)
          LoadData ( 20hamburgsud common.containerdata CenterRear Loaded)
          LoadData ( 40msc common.containerdata Above Random)
          UiD ( 11 )
)

As can be seen, for each container loaded at startup a LoadData entry must be present. The meaning of the parameters is as follows:

  • The first parameter is the name of the .load-or file

  • The second parameter is the path (having Trainset as base path) where the .load-or file resides

  • The third parameter indicates where the container is allocated on the wagon

  • The fourth parameter, which is optional, defines the load state of the related container, which is used to derive the weight of the container. If Empty is present, the weight of the empty container is used as actual weight; if Loaded is present, the maximum weight (tare + payload) of the container is used; if Random is present, the weight is computed as follows: a random number between 0 and 100 is generated. If the number is below 31, the container is considered empty; else the number is used as percentage of the maximum weight of the container (tare + payload). The weight of the containers are added to the empty weight of the wagon, to compute the total weight of the wagon. If the parameter is not present, the Random value is assumed.

The entry for the container allocated Above must be the last one.

CenterFront and CenterRear entries must be entered after Front or Rear entries.

The advantage of this type of allocation is that, for a single .wag file (in the example DTTX_620040_A.wag) more possible container configurations are possible, sparing the time of creating many .wag files that differ only on the containers loaded.

Here below a picture with a sample entry in the .con file:

_images/features-sample-load-entry.png

9.4.5.2. Allocation through .wag file

Content creators might prefer to provide packs of pre-loaded wagons. Therefore it is also possible to set in .wag file the containers to be loaded at startup.

A minimum FreightAnimations entry in a .wag file to have the same pre-loaded container set as in the previous paragraph is as follows:

ORTSFreightAnims (
              WagonEmptyWeight ( 12.575t )
              LoadingAreaLength ( 14.6 )
              AboveLoadingAreaLength ( 16.15 )
              DoubleStacker ()
              Offset( 0 0.34 0 )
              IntakePoint ( 0 6.0 Container)
              LoadData ( 20cmacgm common.containerdata CenterFront Empty)
              LoadData ( 20hamburgsud common.containerdata CenterRear Loaded)
              LoadData ( 40msc common.containerdata Above Random)
            )

As can be seen, the syntax of the LoadData entries is the same as in the case of the .con file. Also here the fourth parameter is optional.

Obviously, using .wag files for this type of info, a different .wag file must be created for every desired pre-loaded set of containers.

A single .con file can include Wagon entries for both types of allocation definition.

9.4.6. Container Station

The Container Station is composed by a container crane and a container stack area.

To insert a Container Station in a route, its object must be present in the .ref file as a Pickup object. A .ref file entry sample is as follows:

Pickup (
  Class                   ( "Animated loader" )
  Filename                ( RMG_45.s )
  PickupType              ( _FUEL_COAL_ )
  Description             ( "Animated container crane" )
)

PickupType is set to _FUEL_COAL, but this will be overwritten by the data inserted in the extension .w file (see here) within the Openrails sufolder of the World folder.

Such extension .w file is formed by a general part, a container crane related part, and a stack locations related part, as per following example (parts separated by blank lines)

SIMISA@@@@@@@@@@JINX0w0t______

Tr_Worldfile (
              Pickup (
                      UiD ( 21 )
                      PickupType ( 15 1 )

                      ORTSPickingSurfaceYOffset ( 2.25 )
                      ORTSPickingSurfaceRelativeTopStartPosition ( 0 6.75 0 )
                      ORTSGrabberArmsParts ( 2 )
                      ORTSCraneSound ( "ContainerCrane.sms" )

                      ORTSMaxStackedContainers ( 2 )
                      ORTSStackLocationsLength ( 12.19 )
                      ORTSStackLocations ( 12
                              StackLocation (
                                      Position ( -10 0 26 )
                                      Length ( 16.15 )
                                      )
                              StackLocation (
                                      Position ( -10 0 26 )
                                      MaxStackedContainers ( 1 )
                                      Flipped ( 1 )
                                      )
                              StackLocation (
                                      Position ( -10 0 0 )
                                      MaxStackedContainers ( 2 )
                                      )
                              StackLocation (
                                      Position ( -10 0 0 )
                                      Flipped ( 1 )
                                      )
                              StackLocation (
                                      Position ( -10 0 -26 )
                                      )
                              StackLocation (
                                      Position ( -10 0 -26 )
                                      Flipped ( 1 )
                                      Length ( 16.15 )
                                      )
                              StackLocation (
                                      Position ( -7 0 26 )
                                      Length ( 16.15 )
                                      )
                              StackLocation (
                                      Position ( -7 0 26 )
                                      Flipped ( 1 )
                                      )
                              StackLocation (
                                      Position ( -7 0 0 )
                                      )
                              StackLocation (
                                      Position ( -7 0 0 )
                                      Flipped ( 1 )
                                      )
                              StackLocation (
                                      Position ( -7 0 -26 )
                                      )
                              StackLocation (
                                      Position ( -7 0 -26 )
                                      Flipped ( 1 )
                                      Length ( 16.15 )
                                      )
                              )
              )
)
  • The UiD number must correspond to the uiD number that the pickup has in the main .w file.

  • PickupType ( 15 1 ) identifies this pickup as being a container station.

More than a Pickup() block can be present in such extension file, one for every container station present in the route.

The container crane and stack location related data are described at a convenient point below.

9.4.6.1. Container Station (including container crane) shape file developing rules

  • The shape file must have its Z Axis aligned with the track where the wagons to be loaded or unloaded stay.

  • The Z-zero of the shape file must be in the middle of the segment that the crane can cover in its motion (e.g. the crane Z-span could be -30 meters to 30 meters).

  • The animation of the part of the crane moving along the Z axis must be called ZAXIS.

  • The animation of the part of the crane moving transversally along the X axis must be called XAXIS, and must be hierarchically dependent from ZAXIS.

  • The animation of the part of the crane moving vertically along the Y axis must be called YAXIS, and must be hierarchically dependent from XAXIS.

  • The grabbers are the extensible arms that pick the container. In the simplest case there are two sections, one extending towards positive Z for longer containers, and one extending towards negative Z. The first one must be called GRABBER01 and the second one GRABBER02. Both must be hierarchically dependent from YAXIS. In the most complex case each of the two “arms” is composed by two parts, which move like a telescope. Such second couple of arms must be called GRABBER01_O2 and GRABBER02_02. They must be hierarchically dependent from GRABBER01 and GRABBER02. The spans of GRABBER01 and GRABBER02 must be symmetric, and the same applies for the other couple of spans. Moreover the spans of GRABBER01 and GRABBER01_02 must be equal (and symmetrically also the other couple).

  • The names of the cable parts that have a partially autonomous motion along the Y axis (to simulate cable winding and unwinding) must start with CABLE and must be hierarchically dependent from YAXIS.

The following diagram, taken from Shape Viewer, sums up the above rules.

_images/features-hierarchy.png

Following are the significant animation entries of a crane’s shape file:

animations ( 1
              animation ( 2 30
                      anim_nodes ( 30
                              anim_node MAIN (
                                      controllers ( 0 )
                              )
              ...
                              anim_node ZAXIS (
                                      controllers ( 1
                                              linear_pos ( 3
                                                      linear_key ( 0 0 0 -139.5 )
                                                      linear_key ( 12 0 0 139.5 )
                                                      linear_key ( 24 0 0 -139.5 )
                                              )
                                      )
                              )
                              anim_node XAXIS (
                                      controllers ( 1
                                              linear_pos ( 3
                                                      linear_key ( 0 0 0 0 )
                                                      linear_key ( 3 26.4 0 0 )
                                                      linear_key ( 6 0 0 0 )
                                              )
                                      )
                              )
              ...
                              anim_node YAXIS (
                                      controllers ( 1
                                              linear_pos ( 3
                                                      linear_key ( 0 0 11.7 0 )
                                                      linear_key ( 2 0 0 0 )
                                                      linear_key ( 4 0 11.7 0 )
                                              )
                                      )
                              )
                              anim_node GRABBER02 (
                                      controllers ( 1
                                              linear_pos ( 3
                                                      linear_key ( 0 0 0 -2.515 )
                                                      linear_key ( 1 0 0 0 )
                                                      linear_key ( 2 0 0 -2.515 )
                                              )
                                      )
                              )
                              anim_node GRABBER02_02 (
                                      controllers ( 1
                                              linear_pos ( 3
                                                      linear_key ( 0 0 0 -2.513 )
                                                      linear_key ( 1 0 0 0 )
                                                      linear_key ( 2 0 0 -2.513 )
                                              )
                                      )
                              )
                              anim_node GRABBER01 (
                                      controllers ( 1
                                              linear_pos ( 3
                                                      linear_key ( 0 0 0 2.515 )
                                                      linear_key ( 1 0 0 0 )
                                                      linear_key ( 2 0 0 2.515 )
                                              )
                                      )
                              )
                              anim_node GRABBER01_02 (
                                      controllers ( 1
                                              linear_pos ( 3
                                                      linear_key ( 0 0 0 2.513 )
                                                      linear_key ( 1 0 0 0 )
                                                      linear_key ( 2 0 0 2.513 )
                                              )
                                      )
                              )
              ...
                              anim_node CABLE02 (
                                      controllers ( 1
                                              linear_pos ( 3
                                                      linear_key ( 0 0 22.32 0 )
                                                      linear_key ( 1 0 15.72 0 )
                                                      linear_key ( 2 0 22.32 0 )
                                              )
                                      )
                              )
                              ...
                      )
              )
      )

It can be noted that the frame count is different for different animation nodes, e.g. the ZAXIS has 0, 12, 24. This permits to scale down the motion speed along that axis to a realistic value.

9.4.6.3. Stack Locations

Within the area that can be reached by the container crane (rails area apart) stack locations where the containers can be laid down can be defined in the extension .w file.

The stack locations are defined by following parameters:

  • Position: the coordinates of the center point of one of the short sides of the stack location; if no Flipped ( 1 ) line is present, the location area extends towards the increasing Z axis; if instead such line is present, the location area extends towards the decreasing Z axis. If two stack locations have the same position, and one is flipped and the other isn’t, the containers will be laid back-to-back, optimizing space used.

  • Length: the maximum length of the containers that can be laid down on that stack location

  • MaxStackedContainers: The maximum number of containers that can be stacked one above the other on that stack location

The Length and MaxStackedContainers parameters are optional and, when present, override the default values present in the ORTSStackLocationsLength and ORTSMaxStackedContainers.

If ORTSStackLocationsLength is greater or equal to 12.20m, which is twice the length of a 20ft container, Open Rails applies a space optimization strategy: for each stack location (let’s call it the mother stack location), another one (let’s call it the child stack location) is created on a position with a Z value which is 6.095m greater than the mother stack location (if the latter is flipped the Z value is 6.095m smaller). This child stack location can be occupied by a 20ft container only, and only if the mother stack location is empty or occupied by a 20ft container too. The child stack location has an index which is equal to the mother stack location index plus the total number of mother stack locations. Once both the mother and the child stack locations are empty, the mother stack location is again available for any type of container of suitable length.

A further example of a stack locations allocation code and of its physical counterpart in the container station follows. It can be noted that stack location 0 has a 20ft container on it, and so has its child stack location 10. Same applies to stack location 3 and its child stack location 13.

_images/features-stack-locations-code.png _images/features-stack-locations.png

9.4.6.4. Population of container stations at game start

Container stations may be populated at game start. This occurs by inserting a .load-stations-loads-or file in the Openrails subfolder of the “Activities” folder of the route, and inserting the following line at the bottom of the Tr_Activity_Header in .act files

ORTSLoadStationsPopulation ( BigContainerStationPopulation )

where BigContainerStationPopulation is the name of the .load-stations-loads-or file. At the moment population at game start is possible only in Activity mode.

The .load-stations-loads-or file is a Json file. An example is shown here below

      "ContainerStationsPopulation": [
              {
                      "LoadStationID" : { "wfile" : "w-005354+014849.w", "UiD" :  21, },
                      "LoadData" : [
                              { "File" : "40HCcai", "Folder" : "common.containerdata", "StackLocation" : 0, "LoadState" : "Empty"},
                              { "File" : "40HCcai", "Folder" : "common.containerdata", "StackLocation" : 0, "LoadState" : "Loaded"},
                              { "File" : "20cmacgm", "Folder" : "common.containerdata", "StackLocation" : 2, "LoadState" : "Random"},
                              { "File" : "20kline", "Folder" : "common.containerdata", "StackLocation" : 2, },
                              { "File" : "45HCtriton", "Folder" : "common.containerdata", "StackLocation" : 5, },
                              { "File" : "45HCtriton", "Folder" : "common.containerdata", "StackLocation" : 5, },
                              { "File" : "48emp", "Folder" : "common.containerdata", "StackLocation" : 6, },
                              { "File" : "20maersk", "Folder" : "common.containerdata", "StackLocation" : 14, },
                              { "File" : "20maersk3", "Folder" : "common.containerdata", "StackLocation" : 14, },
                      ]
              },
              {
                      "LoadStationID" : { "wfile" : "w-005354+014849.w", "UiD" :  210, },
                      "LoadData" : [
                      ...
                      ]
              },
              ...
      ]
}

The file can define the population at startup of many container stations.

  • The LoadStationID contains the info needed to identify the container station.

  • The LoadData array contains the data to populate the container station.

  • The value of File is the name of the .load-or file identifying the container.

  • The value of Folder is the path where the .load-or can be found, starting from the TRAINSET.

  • The value of StackLocation is the index of the Stack Location. If the index is equal or higher than the number of stack locations defined in the extension .w file, the index refers to a child stack location.

  • If more than a container is defined for a stack location, they are stacked one above the other.

  • The LoadState parameter is optional, and has the same meaning and values as the parameter of the same name which can be present in .con or .wag files.

The container station population file must be written taking into account the constraints of the stack locations (container length must be smaller than stack location lenght, stacked containers can’t exceed the allowed number, a stack location must contain containers of same length).

9.5. Multiple passenger viewpoints

Additional passenger viewpoints may be added within a carriage or locomotive that is provided with passenger viewpoint.

Such additional passenger viewpoints may be defined within an include file with the format shown in following example for the legacy oebarcar.wag (located in the 380 folder) MSTS wagon:

include ( ../oebarcar.wag )

Wagon (
      ORTSAlternatePassengerViewPoints (
              ORTSAlternatePassengerViewPoint (
                      PassengerCabinHeadPos ( -0.0 2.85801 -6.091 )
                      RotationLimit ( 50 270 0 )
                      StartDirection ( 0 0 0 )
              )
              ORTSAlternatePassengerViewPoint (
                      PassengerCabinHeadPos ( -0.5 2.35801 -1.791 )
                      RotationLimit ( 50 270 0 )
                      StartDirection ( 0 0 0 )
              )
              ORTSAlternatePassengerViewPoint (
                      PassengerCabinHeadPos ( 0.9 2.35801 -1.791 )
                      RotationLimit ( 50 270 0 )
                      StartDirection ( -5 -90 0 )
              )
      )
)

If the passenger viewpoints are defined in the base .wag or .eng file, they must be defined below the Inside () block.

At runtime, when in passenger view, the player may pass from one viewpoint to the other by pressing Shift-5.

9.6. Bell animation

Open Rails supports bell animation. The bell animation matrix must be named ORTSBELL within the engine’s .s file. Its default frame rate is 8 frames per second. The default frame rate may be modified through the optional parameter ESD_ORTSBellAnimationFPS (n), to be inserted within the .sd file related to the .s file. n defines the animation FPS. It is advisable that the related sound stream within the .sms file is synchronized with the visible animation. To accomplish this the .wav file should contain two bell strokes, which time interval is equal to the time interval of a bell swing from an oscillation end point to the opposite end point. As the first bell stroke should not start immediately, but when the bell is about at the maximum of the swing, the first stroke within the .wav file should be at the time distance equivalent to the oscillation from center point to an oscillation end point. The file should have one cue point at its beginning and one after the time interval of a complete bell swing forward and backward, and should have a final fadeoff for best result.

9.7. Brake Equipment Animations

Open Rails now supports animation of brake rigging components driven by the brake system simulation.

9.7.1. Brake Cylinder Animation

On engines and wagons with advanced brake cylinder parameters ORTSBrakeCylinderDiameter and ORTSBrakeCylinderPistonTravel defined, Open Rails will simulate the motion of the brake cylinders and brake rigging. This simulation can be used to drive animations of brake cylinders using animation matricies with names that start with ORTSBRAKECYLINDER. This animation type should NOT be used for any brake equipment that can be actuated by the brake cylinder and the handbrakes. See the section on brake rigging animation for details.

Unlike other animation types, the keyframes for brake cylinders do not represent time, and cannot be set to arbitrary values. Instead, the key value represents the level of brake cylinder extension. A keyframe value of 8 represents the state where the brake cylinder has taken up the slack in the brake rigging, 10 represents the level of brake cylinder extension at 50 psi/3.5 bar, and the maximum value of cylinder extension is 16, which should not be possible in normal operation. These values are the same regardless of the settings used in the engine or wagon file. NOTE: Brake animations should at minimum have 2 animation frames, one at keyframe 0 and the second at keyframe 8. Other keyframes are optional and may be included to fine-tune the animation.

Note that the advanced brake cylinder calculations are only run on air brake systems on the player train to save computing power. As such, brake cylinder animations on AI trains or brake systems other than air brakes behave in a simplified manner.

9.7.2. Handbrake Animation

Handbrake wheels and levers can also be animated using the same process as two-state animations such as mirrors, and the keyframe values will represent time in seconds like other animations. The matrix name for animated handbrakes must begin with ORTSHANDBRAKE.

9.7.3. Brake Rigging and Brake Shoe Animation

For any brake equipment that is actuated by both the handbrake and the brake cylinders (typically, this includes brake rigging and brake shoes, but sometimes also includes brake cylinders themselves), use animations with a matrix name starting with ORTSBRAKERIGGING. For this type of animation, the animation state will respond to the brake cylinder travel or the handbrake, whichever input is greater.

The same keyframe rules as brake cylinder animations apply here. A key value of 8 should represent the state where the brake shoes have made contact with the friction surface, and no further motion of brake shoes should occur after 8, though the brake levers may still animate beyond this point. Applying the handbrake will also drive the animation to keyframe 10 (ie: same as 50 psi/3.5 bar application).

9.8. Coupler and Airhose Animation

Open Rails supports animation of couplers and air hoses. Coupler animation will move the couplers and air hoses as the train moves and the coupler slack increases or decreases. Couplers will also rotate as the train travels around a curve.

To implement this separate models need to be provided for the couplers and air hoses. A separate model for the coupled and uncoupled state is suggested.

To enable coupler animation the following parameters need to be included in the coupler code section of the WAG file:

FrontCouplerAnim - Coupler shape to be displayed at the front of the car when it is coupled. FrontCouplerOpenAnim - Coupler shape to be displayed at the front of the car when it is uncoupled. RearCouplerAnim - Coupler shape to be displayed at the rear of the car when it is coupled. RearCouplerOpenAnim - Coupler shape to be displayed at the rear of the car when it is uncoupled

All four of the above will have the following format:

CouplerAnimation ( couplershape.s, x, y, z ) where the coupler shape file name is included along with x, y, z values that offset the coupler in the three axis.

For the airhose animation the following parameters must be included in the coupler code section of the WAG file:

FrontAirHoseAnim - Air hose shape to be displayed at the front of the car when it is coupled. FrontAirHoseDisconnectedAnim - Air hose shape to be displayed at the front of the car when it is uncoupled. RearAirHoseAnim - Air hose shape to be displayed at the rear of the car when it is coupled. RearAirHoseDisconnectedAnim - Air hose shape to be displayed at the rear of the car when it is uncoupled.

Each of these parameters will have the same format as indicated above for the coupler shapes.

Open rails uses some defaults to calculate the required movement and angles for coupler and air hose shape movement, however for greater accuracy the modeler can add specific values such as ORTSLengthAirHose. In addition the length values suggested in the Derailment Coefficient should also be added.

9.9. Passenger doors

Passenger doors are opened and closed (by default) using the <Q> and <Shift+Q> keys. It is possible to add opening and closing delays, which can be useful to delay the indication of “Doors closed” until all doors are fully closed. The delays can be added inserting the following block in the wagon section of any ENG or WAG file:

ORTSDoors (
  ClosingDelay ( 5s )
  OpeningDelay ( 1s )
)

9.10. Trainset windows

Left and right 2D- or 3D-cab windows can be animated, showing the animation both in cabview and in external views. For locomotives also two windows for the rear cab can be defined.

The external sounds and the track sound are reproduced unattenuated with open window. To have a volume difference, two lines as follows must be added to the wagon section of the .eng or .wag file:

ORTSExternalSoundPassedThroughPercent ( 30 )
ORTSTrackSoundPassedThroughPercent ( 25 )

Numbers in parenthesis may vary from 0 (no sound heard internally) to 100 (sound heard unattenuated). Note that, if these two lines aren’t added, but audio option “% of external sound heard internally” is set to a value lower than 100, the above effect will be still available with external sounds, but not with the track sound.

Keyboard commands to toggle window state are listed here .

Names of the animations are as follows.

Names for the windows animations as seen from the external camera views (the ones to be inserted in the .s file of the trainset) must start with following strings:

LEFTWINDOWFRONT
RIGHTWINDOWFRONT
LEFTWINDOWREAR
RIGHTWINDOWREAR

In case of carriages, only the first two apply.

Names for the windows animations as seen from within a 2D cab (same names are valid for front and rear cab); left and right are considered as seen from the related cab:

ORTS_2DEXTERNALLEFTWINDOW
ORTS_2DEXTERNALRIGHTTWINDOW

Note that in general the lateral windows will be located in the side views of the 2D cab. Therefore the related control blocks in the .cvf file will have to be located as described here .

Names for the window animations as seen from within a 3D cab (the ones to be inserted in the .s file of the 3D cab); Left and right are considered as seen in the forward direction of the first cab. The convention difference between 2D and 3D cabs is due to the difference in the handling of the cabs. NOTE: these 4 controls are not needed in the .cvf file (same applies also for wipers, doors and so on as seen from within a 3D cab):

ORTS_EXTERNALLEFTWINDOWFRONT
ORTS_EXTERNALRIGHTWINDOWFRONT
ORTS_EXTERNALLEFTWINDOWREAR
ORTS_EXTERNALRIGHTWINDOWREAR

ORTS_LEFTWINDOW and ORTS_RIGHTWINDOW are the names of the controls that can be inserted in the .cvf file and in the 3Dcab .s file to command the state change with the mouse.

Here is an example of the animation of the left window in a 2D cab:

ORTSCabViewControls
( 1
                ORTSAnimatedDisplay  (
                Type ( ORTS_2DEXTERNALLEFTWINDOW MULTI_STATE_DISPLAY )
                Position ( 101 69 235 365 )
                Graphic ( ../../Common.Cab/CabE464/FinestraSX.ace )
                ORTSCycleTime ( 0.6 )
                        States ( 16 4 4
                        State (
                                Style ( 0 )
                                SwitchVal ( 0 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.0625 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.125 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.1875 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.25 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.3125 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.375 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.4375 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.5 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.5625 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.625 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.6875 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.75 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.825 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.88 )
                        )
                        State (
                                Style ( 0 )
                                SwitchVal ( 0.94 )
                        )
                )
                ORTSCabviewpoint ( 1 )
        )
)

FinestraSX.ace contains the various frames, from window fully close to window fully open. ORTSCycleTime means that the opening/closing time of the window is 0.6 seconds. If one wants to use higher times, more frames are needed to get a smooth animation. Note that, as explained above, the control is within the ORTSCabviewControls block, which is skipped by MSTS and older OR versions to avoid error messages, and note that the ORTSCabviewpoint ( 1 ) line specifies that that animation is in the left cabview.

A simple control block to move a window by clicking the mouse can be as follows:

TwoState (
                Type ( ORTS_LEFTWINDOW TWO_STATE )
                Position ( 120 425 30 21 )
                Graphic ( cab.ace )
                NumFrames ( 2 2 1 )
                Style ( ONOFF )
                MouseControl ( 1 )
                )

If there is no specific window control in the real cab, you can locate this control on the window itself, using a transparent graphic. So, clicking on the window, you change its state. This can be applied both to 2D and 3D cabs.

Sound triggers for windows animation are listed here .

9.10.1. Specifics for carriage window animations

One window to the left and one window to the right of the carriage may be animated. They can be opened and closed only via keyboard (Ctrl-Q for left window and Ctrl-Shift-Q for right window, as for locomotives).

Note that the carriage must have only the main shape file (no passenger view shape file). This main shape file can include also the inside structure of the carriage; note that when a .wag or .eng file has an Inside block defined, and such block doesn’t include a line specifying the .s file, OR will use the main shape file to display the inside. So such shape file will display the window animation both with the passenger camera (inside view) and with the external cameras (outside views).

9.11. C# engine scripting

To simulate especially complex behavior, Open Rails provides a C# scripting interface for a number of systems on the player locomotive. Like the Open Rails program itself, these scripts are written in .cs files containing C# classes, but they are compiled and linked at runtime, so they don’t depend on changes in the core program itself and can be distributed with rolling stock content. Scripts will run if referenced by OR-specific fields in the .eng file.

Currently scriptable locomotive systems

System

C# class

.eng block

Train brake controller

ORTS.Scripting.Api.BrakeController

Engine ( ORTSTrainBrakeController ( "DemoBrakes.cs" ) )

Engine brake controller

ORTS.Scripting.Api.BrakeController

Engine ( ORTSEngineBrakeController ( "DemoBrakes.cs" ) )

Circuit breaker

ORTS.Scripting.Api.CircuitBreaker

Engine ( ORTSCircuitBreaker ( "DemoBreaker.cs" ) )

Traction cut-off relay

ORTS.Scripting.Api.TractionCutOffRelay

Engine ( ORTSTractionCutOffRelay ( "DemoRelay.cs" ) )

Diesel power supply

ORTS.Scripting.Api.DieselPowerSupply

Engine ( ORTSPowerSupply ( "DemoPower.cs" ) )

Electric power supply

ORTS.Scripting.Api.ElectricPowerSupply

Engine ( ORTSPowerSupply ( "DemoPower.cs" ) )

Passenger car power supply

ORTS.Scripting.Api.PassengerCarPowerSupply

Wagon ( ORTSPowerSupply ( "DemoPower.cs" ) )

Pantograph selector

ORTS.Scripting.Api.PantographSelector

Engine ( ORTSPantographSelector ( Script ( "DemoPantographSelector.cs" ) ) )

Voltage selector

ORTS.Scripting.Api.VoltageSelector

Engine ( ORTSVoltageSelector ( Script ( "DemoVoltageSelector.cs" ) ) )

Power limitation selector

ORTS.Scripting.Api.PowerLimitationSelector

Engine ( ORTSPantographSelector ( Script ( "DemoPowerLimitator.cs" ) ) )

Train Control System

ORTS.Scripting.Api.TrainControlSystem

Engine ( ORTSTrainControlSystem ( "DemoTCS.cs" ) )

Scripts reside in a Script subfolder within the engine’s folder and must contain a class named after the script’s own filename. For example, if the script’s filename is AmtrakTCS.cs, OR will search for a single class named AmtrakTCS. (It is also possible to place the script in another location, such as a Common.Script folder in the TRAINSET folder, by prepending the appropriate amount of parent directory tokens ..\ relative to the engine’s Script folder.) The script’s code runs on the UpdaterProcess thread. This example, which would need to be placed in a file named DemoTCS.cs, illustrates the minimum code required for a Train Control System script:

using System;
using ORTS.Scripting.Api;

namespace ORTS.Scripting.Script
{
    class DemoTCS : TrainControlSystem
    {
        public override void HandleEvent(TCSEvent evt, string message) {}
        public override void Initialize()
        {
            Console.WriteLine("TCS activated!");
        }
        public override void SetEmergency(bool emergency) {}
        public override void Update() {}
    }
}

Observe that the script’s class must reside in the ORTS.Scripting.Script namespace and that it subclasses the abstract class of the desired system. It also references external assemblies with using directives. OR makes the following .NET assemblies available to scripts:

  • System

  • System.Core

  • ORTS.Common

  • Orts.Simulation

Scripts communicate with the simulator by invoking methods in the base class. For example, this script might invoke the TrainLengthM() method of the TrainControlSystem class, which returns the length of the player train. More methods are available in the ORTS.Scripting.Api.AbstractScriptClass class, which TrainControlSystem is itself a subclass of.

Finally, if a script contains a syntax or typing error, OR will log an exception during the loading process and run the simulation without it.

9.11.1. Developing scripts with Visual Studio

While it is certainly possible to develop scripts with a plain text editor, the code completion and debugging aids available in an IDE like Visual Studio make for a vastly more comfortable programming experience. If you have a development environment set up to build Open Rails, you can use Visual Studio to edit your scripts with these creature comforts. What follows is a suggested workflow:

  1. First, in your copy of the OR source code, make a copy of your Source\ORTS.sln file. Keep it in the Source\ folder, but give it a novel name like ORTS_Scripts.sln. (You could also modify the original ORTS solution, but then you’d have to remember not to check it in to source control.) Add a new project to the solution and select the empty .NET project.

  2. In the configuration dialog, set the new project to be added to the existing solution, set its location to be the folder of the engine you’re scripting, and set its name to “Script”. (For now, you must use “Script”, but you can rename the project after it’s created.) You can leave the .NET framework version set to its default. Then, create the project.

    _images/features-scripting1.png
  3. The new project folder becomes the very Script subfolder that OR will search for scripts. Add references to the ORTS.Common and Orts.Simulation assemblies, which will enable IntelliSense features inside your editor when you edit scripts. You may now rename the project as you like (which will not rename the folder) and delete the pregenerated App.config file.

    _images/features-scripting2.png
  4. Finally, open the Build Configuration Manager and set the new script project not to build for both the Debug and Release configurations.

    _images/features-scripting3.png

With this setup, Visual Studio will type-check your scripts and make suggestions when you use the Open Rails API. You can also set breakpoints within your script, which will be caught by RunActivity.exe if run inside Visual Studio.

_images/features-scripting4.png

Note that Visual Studio uses relative paths, so if you ever move any folders, you’ll need to fix the references by hand.

9.11.2. Brake controller

The brake controller script customizes the behavior of the train’s brakes, allowing for much greater systems fidelity compared to what is possible with the model inherited from MSTS. For this purpose, the script can read the state of the brake controls and set the air pressures of the brake reservoirs.

Use the following .eng parameter to load a brake controller script:

Engine (
    ORTSTrainBrakeController ( "YourBrakes.cs" )
)

or:

Engine (
    ORTSEngineBrakeController ( "YourBrakes.cs" )
)

The .cs extension is optional. “MSTS” loads the default MSTS-compatible implementation, so do not use this name for your own script.

9.11.3. Circuit breaker

Available for electric locomotives only. The circuit breaker script controls the behavior of the locomotive’s circuit breaker.

Use the following .eng parameter to load a circuit breaker script:

Engine (
    ORTSCircuitBreaker ( "YourCB.cs" )
    ORTSCircuitBreakerClosingDelay ( 2s )
)

ORTSCircuitBreaker refers to the circuit breaker script in the engine’s Script subfolder. For this field, the .cs extension is optional. Alternatively, there are several built-in OR circuit breaker implementations:

  • “Automatic”: no driver intervention required, circuit breaker is closed when conditions are met.

  • “Manual”: a circuit breaker switch with open and closed positions.

  • “PushButtons”: a circuit breaker with dedicated open and close buttons.

  • “TwoStage”: circuit breaker closing is authorized by a switch. If the switch is off, the circuit breaker is kept open. Once the switch is activated, it is required to use a second button to order the closing.

Please do not use these names for your own script, since the generic implementation will be loaded instead.

ORTSCircuitBreakerClosingDelay refers to the delay between the closing command of the circuit breaker and the effective closing of the circuit breaker.

9.11.4. Traction cut-off relay

Available for diesel locomotives only. The traction cut-off relay script controls the behavior of the locomotive’s traction cut-off relay.

Use the following .eng parameter to load a traction cut-off relay script:

Engine (
    ORTSTractionCutOffRelay ( "YourTCOR.cs" )
    ORTSTractionCutOffRelayClosingDelay ( 2s )
)

ORTSTractionCutOffRelay refers to the traction cut-off relay script in the engine’s Script subfolder. For this field, the .cs extension is optional. Alternatively, there are several built-in OR traction cut-off relay implementations:

  • “Automatic”: no driver intervention required, circuit breaker is closed when conditions are met.

  • “Manual”: a traction cut-off switch with open and closed positions.

  • “PushButtons”: a traction cut-off relay with dedicated open and close buttons.

Please do not use these names for your own script, since the generic implementation will be loaded instead.

ORTSTractionCutOffRelayClosingDelay refers to the delay between the closing command of the traction cut-off relay and the effective closing of the relay.

9.11.5. Pantograph, voltage and power limitation selectors

Available for electric locomotives only. The scripts control the behavior of the locomotive’s pantograph selector, voltage selector and power limitation selector respectively.

Use the following .eng parameters to load power selector scripts:

Engine (
    ORTSPantographSelector (
      Script ( "YourPSScript.cs" )
      SelectorPositions ( ... )
    )
    ORTSVoltageSelector (
      Script ( "YourVSScript.cs" )
      SelectorPositions ( ... )
    )
    ORTSPowerLimitationSelector (
      Script ( "YourPLSScript.cs" )
      SelectorPositions ( ... )
    )
)

Script refers to the circuit breaker script in the engine’s Script subfolder. For this field, the .cs extension is optional. Alternatively, there are several built-in OR selector implementations which can be used if custom features such as interlocking with other devices are not required:

  • “Default”: a selector with sequential positions.

  • “Circular”: same as above, but the first position follows again after the last one.

Please do not use these names for your own script, since the generic implementation will be loaded instead.

9.11.6. Diesel and electric power supply

Available for diesel and electric locomotives only. The power supply script determines whether or not the locomotive is serviceable (see also the description of the diesel power supply and the electric power supply) given the current line voltage, pantograph position, circuit breaker state, etc. It is also capable of forbidding some operations related to the power supply if some conditions are not met.

Use the following .eng parameter to load a power supply script:

Engine (
    ORTSPowerSupply ( "YourEPS.cs" )
    ORTSPowerSupplyParameters ( "YourEPS.ini" )
    ORTSPowerOnDelay ( 5s )
    ORTSAuxPowerOnDelay ( 10s )
)

ORTSPowerSupply refers to the power supply script in the engine’s Script subfolder. For this field, the .cs extension is optional. “Default” will load the generic OR power supply implementation, so do not use this name for your own script.

ORTSPowerSupplyParameters, an optional field, refers to an .ini file, also in the Script subfolder, whose parameters will be made available to the power supply script through the GetBoolParameter(), GetIntParameter(), GetFloatParameter(), and GetStringParameter() methods. This .ini file provides for easy customization of the behavior of the power supply script by end users.

ORTSPowerOnDelay refers to the delay between the closing of the circuit breaker or the traction cut-off relay and the availability of the power for traction.

ORTSAuxPowerOnDelay refers to the delay between the closing of the circuit breaker or the traction cut-off relay and the availability of the power for auxiliary systems.

9.11.7. Passenger car power supply

Available for passenger cars using electric heating. The power supply script determines whether or not the systems of the cars have power and calculates the power consumption on the Electric Train Supply.

If the locomotive is a diesel locomotive, the power consumed by the cars is no longer available for traction.

Use the following .wag parameter to load a power supply script:

Wagon (
    ORTSPowerSupply ( "YourEPS.cs" )
    ORTSPowerOnDelay ( 5s )
    ORTSPowerSupplyContinuousPower ( 500W )
    ORTSPowerSupplyHeatingPower ( 2kW )
    ORTSPowerSupplyAirConditioningPower ( 3kW )
    ORTSPowerSupplyAirConditioningYield ( 0.9 )
    ORTSHeatingCompartmentTemperatureSet ( 20degC )
)

ORTSPowerSupply refers to the power supply script in the wagon’s Script subfolder. For this field, the .cs extension is optional. “Default” will load the generic OR power supply implementation, so do not use this name for your own script.

ORTSPowerOnDelay refers to the delay between the availability of the power on the Electric Train Supply cable and the availability of the power for the systems (for example, start-up of the static power converter).

ORTSPowerSupplyContinuousPower refers to the power which is consumed continuously (for example, battery chargers, lights, etc.).

ORTSPowerSupplyHeatingPower refers to the power which is consumed when the heating is active.

ORTSPowerSupplyAirConditioningPower refers to the power which is consumed when the air conditioning (cooling) is active.

ORTSPowerSupplyAirConditioningYield refers to the yield of the air conditioning (ratio of the heat flow rate by the electric power of the air conditioning system).

ORTSHeatingCompartmentTemperatureSet refers to the desired temperature inside the car.

9.11.8. Train Control System

9.11.8.1. General

The Train Control System, or TCS, script is intended to model train safety and cab signalling systems. It can manipulate the locomotive’s controls and speed limit displays, impose penalty brake applications, read upcoming signal aspects and speed limits, and play warning sounds.

Use the following .eng parameters to load a TCS script:

Engine (
    ORTSTrainControlSystem ( "YourTCS.cs" )
    ORTSTrainControlSystemParameters ( "YourTCS.ini" )
    ORTSTrainControlSystemSound ( "YourTCSSounds.sms" )
)

ORTSTrainControlSystem refers to the TCS script in the engine’s Script subfolder. For this field, the .cs extension is optional.

ORTSTrainControlSystemParameters, an optional field, refers to an .ini file, also in the Script subfolder, whose parameters will be made available to the TCS script through the GetBoolParameter(), GetIntParameter(), GetFloatParameter(), and GetStringParameter() methods of the TrainControlSystem class. This .ini file provides for easy customization of the behavior of the TCS script by end users.

This is an excerpt from an .ini file:

[General]
AWSMonitor=true
EmergencyStopMonitor=false
VigilanceMonitor=true
OverspeedMonitor=false
DoesBrakeCutPower=true
BrakeCutsPowerAtBrakeCylinderPressureBar=
[AWS]
Inhibited=false
WarningTimerDelayS=3
BrakeImmediately=false
TrainStopBeforeRelease=false
ActivationOnSpeedLimitReduction=true
SpeedLimitReductionForActivationMpS=11.176
BeaconDistanceToPostM=1186
AppliesCutsPower=true

As can be seen, the .ini file is divided in subgroups. As an example, parameter [AWS]Inhibited would be read by following line of code in the script :

AWSInhibited = GetBoolParameter("AWS", "Inhibited", false);

where the final false is the default value, if the parameter can’t be found.

ORTSTrainControlSystemSound, an optional field, refers to a .sms file either in the engine’s SOUND folder or in the global SOUND folder. If provided, OR will load this sound library alongside the locomotive’s standard cab sounds. The TCS script can play back sounds using any of the TriggerSound... methods of the base class, which in turn activate the TCS-related discrete triggers numbered from 109 through 118.

8 further generic discrete sound triggers are available, named GenericEvent1 to GenericEvent8 and accessible to the script by lines like following one:

SignalEvent(Event.GenericEvent1);

9.11.8.2. Access to the Simulation methods and variables

The abstract class for the TCS scripts provides a significant amount of methods to access variables of interest for the TCS: as an example:

public Func<int, Aspect> NextSignalAspect;

might be called within the script as follows:

var nextSignalAspect = NextSignalAspect(1);

which would return the aspect of the second normal signal in front of the player train.

However it is quite impossible to foresee all needs that a TCS script has and to provide a method for everyone of these needs. For this reason following method is available:

public Func<MSTSLocomotive> Locomotive;

which returns a handle for the player locomotive instance of the MSTSLocomotive class. Through such handle all public classes, methods and variables of the OR Simulation environment can be accessed within the script.

The Train Control System class provides the ETCSStatus field, which controls the information to be displayed in the ETCS DMI. For example, the following block orders the DMI to show the circular speed gauge in yellow colour as the train approaches a speed restriction:

ETCSStatus.CurrentMonitor = Monitor.TargetSpeed;
ETCSStatus.CurrentSupervisionStatus = SupervisionStatus.Indication;
ETCSStatus.TargetDistanceM = 1234.5f;
ETCSStatus.AllowedSpeedMpS = 50;
ETCSStatus.InterventionSpeedMpS = 52.5f;
ETCSStatus.TargetSpeedMpS = 25;

9.11.8.3. Emergency braking triggered by the simulator

The emergency brakings triggered by the simulator are always sent to the TCS script.

Two functions are used to transmit this information:

public override void HandleEvent(TCSEvent evt, string message)

The events sent are EmergencyBrakingRequestedBySimulator, EmergencyBrakingReleasedBySimulator and ManualResetOutOfControlMode. For the first event, the reason of the emergency braking is also sent:

  • SPAD: The train has passed a signal at danger at the front of the train

  • SPAD_REAR: The train has passed a signal at danger at the rear of the train

  • MISALIGNED_SWITCH: The train has trailed a misaligned switch

  • OUT_OF_AUTHORITY: The train has passed the limit of authority

  • OUT_OF_PATH: The train has ran off its allocated path

  • SLIPPED_INTO_PATH: The train has slipped back into the path of another train

  • SLIPPED_TO_ENDOFTRACK: The train has slipped off the end of the track

  • OUT_OF_TRACK: The train has moved off the track

  • OTHER_TRAIN_IN_PATH: Another train has entered the train’s path

  • SLIPPED_INTO_TURNTABLE: The train has entered a misaligned turntable

  • TRAIN_ON_MOVING_TURNTABLE: The train has started moving on a moving turntable

public override void SetEmergency(bool emergency)

This function is deprecated and will be deleted in a future version. The parameter indicates if the emergency braking is requested (true) or released (false).

9.11.8.4. Generic cabview controls

Often Train Control Systems have a quite sophisticated DMI (driver-machine interface), which can include a (touch screen) display and buttons. Being the display fields and icons and the buttons specific of every TCS, a set of generic cabview controls are available, which can be customized within the TCS script. Generic cabview controls, named ORTS_TCS1, ORTS_TCS2, and so on are available. All of them may be used as two state or multistate controls, like e.g.:

MultiStateDisplay (
                    Type ( ORTS_TCS13 MULTI_STATE_DISPLAY )
                    Position ( 405 282.3 36.3 20.8 )
                    Graphic ( ../../Common.Cab/Cruscotto_SCMT/Ripetizioni_estese.ace )
                    States ( 6 3 2
                            State (
                                    Style ( 0 )
                                    SwitchVal ( 0 )
                            )
                            State (
                                    Style ( 0 )
                                    SwitchVal ( 1 )
                            )
                            State (
                                    Style ( 0 )
                                    SwitchVal ( 2 )
                            )
                            State (
                                    Style ( 0 )
                                    SwitchVal ( 3 )
                            )
                            State (
                                    Style ( 0 )
                                    SwitchVal ( 4 )
                            )
                            State (
                                    Style ( 0 )
                                    SwitchVal ( 5 )
                            )
  )
)

They can be also used as Two-state commands/displays, like e.g.:

TwoState (
        Type ( ORTS_TCS7 TWO_STATE )
        Position ( 377 298 9 7.8 )
        Graphic ( ../../Common.Cab/Cruscotto_SCMT/Button_SR.ace )
        NumFrames ( 2 2 1 )
        Style ( PRESSED )
        MouseControl ( 1 )
)

The commands are received asynchronously by the script through this method:

public override void HandleEvent(TCSEvent evt, string message)

Where evt may be TCSEvent.GenericTCSButtonPressed or TCSEvent.GenericTCSButtonReleased and message is a string representing the control number with zero-base indexing (e.g. “5” corresponds to ORTS_TCS6). The commands may only be triggered by the mouse, except the first two which may also be triggered by key combinations Ctrl, (comma) and Ctrl. (period). Here’s a code excerpt from the script which manages the commands:

public override void HandleEvent(TCSEvent evt, string message)
{
    if (message == String.Empty)
    {
        switch (evt)
        {
            case ...
                                        ...
                break;

            case ...
                                        ...
                break;
         }
    }
    else
    {
        var commandEvent = TCSCommandEvent.None;
        var messageIndex = 0;
        if (Int32.TryParse(message, out messageIndex))
        {
            commandEvent = (TCSCommandEvent)(messageIndex + 1);
            switch (evt)
            {
                case TCSEvent.GenericTCSButtonPressed:
                    TCSButtonPressed[(int)commandEvent] = true;
                    break;
                case TCSEvent.GenericTCSButtonReleased:
                    TCSButtonPressed[(int)commandEvent] = false;
                    TCSButtonReleased[(int)commandEvent] = true;
                    break;
            }
        }
    }
}

Within the Update method of the script TCSButtonPressed and TCSButtonReleased may be tested, e.g.:

if (TCSButtonPressed[(int)(TCSCommandEvent.Button_Ric)])

After having tested it, TCSButtonPressed should be set to false by the script code.

You can also use TCSEvent.GenericTCSSwitchOff and TCSEvent.GenericTCSSwitchOn for a cabview control representing a switch (style ONOFF instead of PRESSED in the CVF file).

To request a display of a cabview control, method:

public Action<int, float> SetCabDisplayControl;

has to be used, where int is the index of the cab control (starting from 0 which corresponds to ORTS_TCS1), and float is the value to be used to select among frames.

When the player moves the mouse over the cabview controls linked to commands, the name of such control shortly appears on the display, like e.g. “speedometer”, as a reminder to the player. In case of these generic commands, strings like “ORTS_TCS1” or “ORTS_TCS32” would appear, which aren’t mnemonic at all. Therefore following method is available:

public Action<int, string> SetCustomizedCabviewControlName;

which may be used this way within the script:

// Initialize customized TCS cabview control names
SetCustomizedCabviewControlName(0, "AWS acknowledge"); // Sets the name "AWS acknowledge" for the cabview control ORTS_TCS1

so that, instead of ORTS_TCSnn the related mnemonic string is displayed.

Generic cabview controls are also available for the Power Supply subsystem. They are named ORTS_POWER_SUPPLY1, ORTS_POWER_SUPPLY2 and so on in the cabview file. Their usage is the same as for the TCS controls.

Events related to power supply controls are made available to power supply scripts via TCSEvent.GenericTCSButtonPressed, TCSEvent.GenericTCSButtonReleased, TCSEvent.GenericTCSSwitchOff and TCSEvent.GenericTCSSwitchOn events, received asynchronously by script through the method:

public override void HandleEvent(PowerSupplyEvent evt, string message)

As for the TCS buttons, message is a string representing the control number with zero-base indexing (e.g. “5” corresponds to ORTS_POWER_SUPPLY6).

SetCabDisplayControl and SetCustomizedCabviewControlName methods, which work in the same way as their TCS counterparts, are accessible from all power supply scripts.

9.11.9. Helper classes

3 helper classes are available in the Orts.Scripting.Api namespace:
  • A timer class

  • An odometer class

  • A blinker class

9.11.9.1. Timer

The timer can be used to execute some code after a time has elapsed. In order to use the timer, you have to create a property in your script class in order to store the object.

public Timer MyTimer;

In the constructor of your script class, you have to instanciate the object and set the delay of the timer.

MyTimer = new Timer(this);
MyTimer.Setup(5f); // Sets the timer's delay to 5 seconds

Then, when you want to start the timer, use the Start function.

MyTimer.Start();

If you want to reset the timer, use the Stop function.

MyTimer.Stop();

When the delay has been reached, the Triggered property of the timer will become true.

if (MyTimer.Triggered)
{
    // Do something
}

Please note that, when the timer is stopped, the Triggered property is false.

9.11.9.2. Odometer

The odometer can be used to execute some code after a distance has been traveled by the train. In order to use the odometer, you have to create a property in your script class in order to store the object.

public Odometer MyOdometer;

In the constructor of your script class, you have to instanciate the object and set the distance at which the odometer will be triggered.

MyOdometer = new Odometer(this);
MyOdometer.Setup(200f); // Sets the odometer's trigger value at 200 meters

Then, when you want to start the odometer, use the Start function.

MyOdometer.Start();

If you want to reset the odometer, use the Stop function.

MyOdometer.Stop();

When the distance has been reached, the Triggered property of the odometer will become true.

if (MyOdometer.Triggered)
{
    // Do something
}

Please note that, when the odometer is stopped, the Triggered property is false.

9.11.9.3. Blinker

The blinker can be used to make a cabview control blink. In order to use the blinker, you have to create a property in your script class in order to store the object.

public Blinker MyBlinker;

In the constructor of your script class, you have to instanciate the object and set the frequency at which the cabview control will blink.

MyBlinker = new Blinker(this);
MyBlinker.Setup(6f); // Sets the blinker frequency to 6 Hz

Then, when you want to start the blinker, use the Start function.

MyBlinker.Start();

If you want to reset the blinker, use the Stop function.

MyBlinker.Stop();

The blinker On property will alternate between true and false at the set frequency.

SetCabDisplayControl(0, MyBlinker.On ? 1 : 0);

Please note that, when the blinker is stopped, the On property is false.