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.

9.2 Tilting trains

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

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

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.

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 species 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 species (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 setin 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 inWtext 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.

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

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

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 )

)

)

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

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

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.

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

Some loading configurations are shown in following picture:

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

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:

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 includeWagon 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 theWorld 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.

Container Station (including container crane) shape file developing rules

• The shape file must have its Z Axis aligned with the track where thewagons 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.

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.

Parameters of extension .w file related to the crane and its animations

• ORTSPickingSurfaceYOset ( 0.0 ) : the Y offset of the lower face of the grabbers (the one which gets in contact with the upper face of the container) when YAXIS is equal to 0

• ORTSPickingSurfaceRelativeTopStartPosition ( 0 11.7 0 ) : the values of XAXIS, YAXIS and ZAXIS at game start (should be centered on the Z axis, above the rails and at top height)

• ORTSGrabberArmsParts ( 4 ) : is 4 if there are all four GRABBER01, GRABBER02, GRABBER01_02 and GRABBER02_02 animations; is 2 if there is only GRABBER01 and GRABBER02

• ORTSCraneSound ( “ContainerCrane.sms” ) : name and path of the crane sound file; the path is based on the SOUND folder of the route; if the file is not found there, the path becomes based on the SOUND folder of TRAIN SIMULATOR. The specific discrete sound triggers available are listed here.

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.

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 that is provided with passenger viewpoint.

Such additional passenger viewpoints are 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 )

)

)

)

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 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 theWAG 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.8 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 orWAG file:

ORTSDoors (

ClosingDelay ( 5s )

OpeningDelay ( 1s )

)

9.9 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-specic fields in the .eng file.

Table 1: Currently scriptable locomotive systems

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

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.

4. Finally, open the Build Configuration Manager and set the new script project not to build for both the Debug and Release configurations.

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.

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

9.9.2 Brake controller

The brake controller script customizes the behavior of the train’s brakes, allowing for much greater systems delity 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.9.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. “Automatic” and “Manual” load the generic OR circuit breaker implementation, so do not use these names for your own script.

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

9.9.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. “Automatic” and “Manual” load the generic OR traction cut-off relay implementation, so do not use these names for your own script.

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

9.9.5 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" )

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.

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.9.6 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.9.7 Train Control System

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

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;

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

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.

9.9.8 Helper classes

3 helper classes are available in the Orts.Scripting.Api namespace:

• A timer class

• An odometer class

• A blinker class

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.

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.

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.