Scenarios

Introduction

The Post T / Stellwerk Simulation Series applications contain a powerful system for specifying and configuring simulations. Scenarios can be written to specify any number of and in any combination, the following:

Initial Panel State (switch positions, danger labels, switchkey positions)
Trains that already exist in a yard
Trains that will enter the yard at a future time
Expert Option overrides
Engineering Works – track possessions and earthing of catenary
Panel defects

In addition, support for custom timetables is included. This allows for a large degree of customizability as not only train schedules be defined, but train composition and physics can be specified as well.

The scenario system is by no means complete – there are some limitations but many situations can be modeled for a variety of goals.

Editor

A decent text editor is recommended for creating and editing scenario files. We recommend Notepad++.

File Structure

Each scenario is defined in a file named scenario.xml. This file is placed in a folder, which is placed in the user's scenarios folder. Additional materials are normally referenced via an html file which acts as an index of additional resources. It is this file that is launched when the user presses the “View Additional Resources” button in the scenario launcher window. The directory structure is summarized below:

scenarios

MyScenario

scenario.xml
<myAdditional_info_en.html>
<myAdditional_info_nl.html>
<myAdditional_info_de.html>
< other files >

The scenario.xml file is obviously mandatory – the others are not. The additional info html files would normally reference any other files – PDFs, movies, etc. Since the simulation supports three languages; scenario.xml optionally points to three html files which can be used for English, Dutch and German speakers.

Scenario Structure

A scenario is completely defined in a single XML file.

File Header

Each scenario begins with the following statement:

<?xml version="1.0" encoding="ISO-8859-1"?>

This defines helps the XML parser to parse the file, as it knows the version and encoding format of the file.

For scenarios that use umlauts or other unusual characters, you may encode the scenario file using utf-8. It is highly recommended that you avoid encoding scenario files with byte order marks (BOM). When using utf-8, the declaration looks like:

<?xml version="1.0" encoding="utf-8"?>

If you're using Notepad++, you can toggle between encodings using the Encoding menu.

Comments

Comments are allowed and recommended within XML documents. The following is an example of a comment:

Comments are used in this document to further document what some parts of a scenario are doing.

Scenario

The entire contents of the scenario is contained within the Scenario tag:

 <Scenario app="Post T Amsterdam CS" description="MyScenario" startDate="1965-10-30" startTime="08:10:15">
    <!-- Scenario contents go here -->
 </Scenario>

The scenario tag has three mandatory attributes:

description : The name of the scenario. See below, if you wish to have localised names for your scenario.
startDate : The date that at which the scenario begins. Times used in this scenario are relative to this date. The format of the date is always the same: YYYY-MM-DD, where January 1st, 1965 is represented as 1965-01-01.
startTime : This is the time at which the scenario begins. The format of the time is always the same: HH:MM:SS, where HH is 24-hour time. If the scenario is to start at 9:53:25 PM, then the time is represented as 21:53:25.

The scenario tag has several; optional attributes:

app : When specified, applications with a product name other than this name will ignore the scenario completely (that is, it will not appear in the list of scenarios to choose from). When omitted, the application tries to load it anyways. It will restrict loading of scenarios to ONLY the "Product Name" simulation
descriptionEN : same as description but is used when application is running in English mode.
descriptionNL : same as description but is used when application is running in Dutch mode.
descriptionDE : same as description but is used when application is running in German mode.
descriptionFR : same as description but is used when application is running in French mode.
panelPosition : integer value that indicates the horizontal pixel value used to scroll the panel to the right. Example: value of 100 would scroll the panel 100 pixels to the right. Used only for the GRS-NX panels (ie, Amsterdam, Hengelo).

Instructions

The instructions portion of a scenario defines what the user must do to successfully play the scenario. All the instructions are contained within an Instructions tag:

 <Scenario app="ProductName" description="MyScenario" startDate="1965-01-01" startTime="00:00:00" >
    <Instructions>
        <!-- Instructions contents go here -->
    </Instructions>
 </Scenario>

Three sets of tags define the content of the instruction. These tags are ShortText, MainText, and AdditionalInstructions. Each tag has a mandatory attribute called language. This allows each tag to define three different sets of instructions, one in each language.

More information: Example of a complete set of scenario instructions

Settings

The simulation settings can and should be overridden, depending on the goals of the scenario. A prime example: When creating a scenario that requires the player to cooperate with an engineering manager who is earthing a catenary, and the player is to manually disable catenary, then the catenary expert option must be enabled.

The instructions portion of a scenario defines what the user must do to successfully play the scenario. All the instructions are contained within an Instructions tag:

 <Scenario app="ProductName" description="MyScenario" startDate="1965-01-01" startTime="00:00:00" >
    <Settings>
        <!-- Settings go here -->
    </Settings>
 </Scenario>

There are some options that are not normally overridden: the use of the alternative ring tone option, or the 'Are you sure?' you want to delete movement orders dialog option can be ignored – the user has already chosen their preferences. When a scenario overrides a setting, the setting is not saved, that is to say, when the player starts a new simulation after having started and ended a scenario, their original setting is preserved.

More information: Example of scenario settings

Some of the setting overrides are almost always useful: StabledTrainsExpert set to false will prevent conflicts when the scenario defines stabled trains (the tag ExistingConsist is used to define such trains.) Each of the application settings can be overridden this way. Care should be taken, as not all settings need to be overridden, especially the player's user interface settings. Thorough testing should be performed on each scenario to ensure that the overridden settings cause the scenario to run as intended.

Consists

It is possible to create a scenario that does not have any trains, either existing in the yard, or in the timetable. Trains can be created (spawned) at the boundaries of the yard from the timetable, and optionally, from an explicit definition. Additionally, trains can be placed at precise locations in the yard. All scenario-defined trains, either spawning or stabled, are defined within a set of Consists tags:

 <Scenario app="ProductName" description="MyScenario" startDate="1965-01-01" startTime="00:00:00" >
    <Consists loadFromTimetable="true">
        <!-- scenario-defined trains go here -->
    </Consists>
 </Scenario>

To load trains from the timetable defined for this scenario, set the mandatory attribute loadFromTimetable to true. To specify a scenario with no timetable trains, set loadFromTimetable to false.

Trains may also be excluded during specific times or by cancelling trains from the timetable completely.

Startup Options

When a scenario starts, there are a few options that can be set.

Alarm Acknowledgement

When true, will acknowledge alarms and buzzers triggered as a result of the scenario conditions.

 <StartupOptions acknowledgeAlarms="true" />

Dispatcher Notes

If you wish to manually enter notes in the dispatcher's notebook, you can do so:

 <StartupOptions acknowledgeAlarms="true">
  <Note time="13:54:12">
   <Message lang="en">Message in English</Message>   <!-- First entry becomes the default text if there is otherwise no language match -->
   <Message lang="nl">Message in Dutch</Message>
   <Message lang="de">Message in German</Message>
   <Message lang="fr">Message in French</Message>
  </Note>
  <Note time="13:57:12">
   <Message lang="en">Another message in English</Message> 
   <Message lang="nl">Another message in Dutch</Message>
   <Message lang="de">Another message in German</Message>
   <Message lang="fr">Another message in French</Message>
  </Note>
</StartupOptions>

If a time is later than the sim start time, the time is interpreted as being the previous day.

Engineering Works

Engineering works defined explicitly in a scenario will override the engineering works settings value. For example, if you have defined an Engineering Works value of, say 72%, and you also explicitly specify a track possession, then the 72% chance of engineering works is ignored. This is to prevent the situation where the system randomly creates engineering works that would cause scheduling conflicts. As such, you can either override the Engineering Works setting (described in the Settings section, above) or you can explicitly define works, as shown here:

 <EngineeringWorks>
    <TrackPossession startTime="08:12:02" endTime="08:20:00" track="250AT" />
    <CatenaryEarthing startTime="08:12:07" endTime="08:15:00" track="A202T" />
 </EngineeringWorks>

Note: The start time can be prior to the simulation start time. Verify that the possessions and earthings occur as scheduled.

Temporary Speed Restrictions

Simplified temporary speed restrictions are available. These simply reduce a particular track's maximum allowed speed during a given time period.

The startTime and endTime attribute are optional. When omitted, the start and end times are unbounded. Track speed is an integer in km/h.

   <TemporarySpeedRestriction startTime="00:05:17" endTime="00:10:33" speed="15" track="04AT" />

Irregularities

Irregularities can be explicitly defined. The following irregularities can be defined:

Occupancy Light Failure
Switch Out Of Control
Signal Failures
Axle Counter Failures

Occupancy Light Failure

An 'Occupancy Light Failure' means that a certain defined track section is indicated as being occupied within the defined time span.

 <Irregularities>
    <OccupancyLight track="250AT" startTime="08:12:00" endTime="08:17:40" />
</Irregularities>

Note that the start time and end time must be after the scenario start time.

Switch Out Of Control

Defining a switch being out of control means that the position of the specified switch can not be changed within the specified time. Additionally, the switch is not locked when a route is set over the switch

 <Irregularities>
    <SwitchOOC switch="253" startTime="08:16:05" endTime="08:17:00" />
 </Irregularities>

Note that the start time and end time must be after the scenario start time.

Signal Failures

Simulating signal failures is a little more complicated, as there are several options for controlling the behaviour of damaged infrastructure.

 <Irregularities>
    <SignalFailure signal="12" aspect="STOP" canRepair="false" />
 </Irregularities>

For details, see signal failures.

Axle Counter Failures

In simulation with axle counters, axle counter failures can be simulated using the name of a track, together with the start and end time. For details see axle counter failures.

 <Irregularities>
    <AxleCounterFailure track="4AT" startTime="10:30:00" endTime="11:00:00"/>
 </Irregularities>

Train Splits

Sometimes trains can become decoupled by accident. This failure happens when a specific train reaches a specific track, where a specific coupler

In the example below, train 12345 will experience a break at coupler 12 (where the first coupler is 0) when the train reaches track 1AT.

 <Irregularities>
  <SplitTrain id="12345" track="1AT" splitPoint="12" />
 </Irregularities>

Infrastructure Irregularities

type: Possible values:

SwitchObstruction
SwitchDefectiveEndContact
TrackOccupationSpontaneous
TrackOccupationAfterTrain

location: Switch or track name where the failure will occur.; In the case of TrackOccupationAfterTrain, the value is semicolon-delimited - the first value is the train ID and the second value is the track name, for example "12345;16AT".

startTime: Time at which the failure may begin to occur. Failure will not occur prior to this time.; (optional)

endTime: Time after which the failure will not occur.; (optional)

options: Delimited series of options. Delimiters can be commas, semi-colons, or pipes (, ; |)

SwitchObstruction

Available options:

normal
reverse

An example SwitchObstruction is defined below:


<InfraIrregularities>
    <InfraIrregularity type="SwitchObstruction" location="3" options="normal,reverse"/>   <!-- Switch obstruction will occur at switch "3" beginning when the simulation starts. -->
</InfraIrregularities>

SwitchDefectiveEndContact

Available options:

normal
reverse

An example SwitchObstruction is defined below:


<InfraIrregularities>
    <InfraIrregularity type="SwitchDefectiveEndContact" location="3" options="normal,reverse"/>   <!-- Switch end contact defect will occur at switch "3" beginning when the simulation starts. -->
</InfraIrregularities>

TrackOccupationSpontaneous

The options attribute here is used to specify the length of time, in seconds, the occupation will last.

An example is defined below:


<InfraIrregularities>

    <!-- track 001AT detects an occupation beginning when the simulation starts and lasts 10 seconds -->
    <InfraIrregularity type="TrackOccupationSpontaneous" location="001AT" options="10"/>  

</InfraIrregularities>

Here's a different example:


<InfraIrregularities>

    <!-- track 001AT detects an occupation at 17:35 and lasts a bit more than 5 minutes -->
    <InfraIrregularity type="TrackOccupationSpontaneous" location="001AT" options="316" startTime="17:35:12"/> 

</InfraIrregularities>

If you absolutely insist on specifying an end time, you can omit the options and instead specify an endTime:


<InfraIrregularities>

    <InfraIrregularity type="TrackOccupationSpontaneous" location="001AT" startTime="17:35:12" endTime="17:35:47"/> 

</InfraIrregularities>

If you want the occupation to happen before the sim begins, leave out the startTime completely:


<InfraIrregularities>

    <InfraIrregularity type="TrackOccupationSpontaneous" location="001AT" endTime="17:35:47"/> 

</InfraIrregularities>

If you want the occupation to happen before the sim begins and never end:


<InfraIrregularities>

    <InfraIrregularity type="TrackOccupationSpontaneous" location="001AT"/> 

</InfraIrregularities>

TrackOccupationAfterTrain

The location attribute here is used to specify which train and which track will trigger the occupation. The value is semicolon-deliminted: the first value is the train ID, and the second value is the track. The irregularity will become triggered as soon as the following conditions are satisfied:

the time is between the startTime and endTime values (if omitted, startTime is the beginning of the simulation and endTime is infinity)
the train must exist in the simulation
the train must be occupying the track

An example is defined below.


<InfraIrregularities>

    <InfraIrregularity type="TrackOccupationAfterTrain" location="953;001AT"/> 

</InfraIrregularities>

In this example, the startTime and endTime are specified. The train must occupy the track during this time period in order for the irregularity to happen.


<InfraIrregularities>

    <InfraIrregularity type="TrackOccupationAfterTrain" location="953;001AT" startTime="17:00:00" endTime="17:30:00"/> 

</InfraIrregularities>

The length of time for which the occupation occurs is controlled using the options attribute.

Infinite Time

If options is left empty (or omitted) then the occupation will last forever until a technician resets the track circuit.

For example:

options=""

Fixed Time

To set the occupation time to a fixed time value, enter a single, positive integer value. For example, this occupation will last 500 seconds after it's triggered.

options="500"

Random Time

To set the occupation time to a random time value, enter two positive integer values separated by a comma, semicolon, or pipe. For example, this occupation will last somewhere between 250 and 1000 seconds after it's triggered.

options="250,1000"

Operational Irregularities

type: Possible values:

HotAxle
FullPowerLoss
PartialPowerLoss
DefectiveEmergencyBrake
PassengerEmergencyBrake

subject: Train ID of the train that is the subject of the failure.

location: Track name where the failure will occur.; (optional); If omitted, failure will occur as soon as train appears in the sim. Most of the time, this is not what you want, so a track name is usually a good idea.

start: Time at which the failure may begin to occur. Failure will not occur prior to this time.; (optional)

end: Failure will not occur after this time.; (optional)

The following is an example of a HotAxle failure that will happen for train 19852, when that train first appears:


<OperationalIrregularities>
    <OperationalIrregularity type="HotAxle" subject="19852" />
</OperationalIrregularities>

The following is an example of a HotAxle failure that will happen for train 19852, when that train reaches 13AT:


<OperationalIrregularities>
    <OperationalIrregularity type="HotAxle" subject="19852" location="13AT"/>
</OperationalIrregularities>

Danger Labels

It's possible the scenario designer requires that danger labels be placed when the scenario begins. A full example for switchkeys, and end buttons is given below:

 <DangerLabels>
    <SwitchKeys>
        <Label>23A</Label>
        <Label>25</Label>
        <Label>301</Label>
    </SwitchKeys>
    <EndButtons>
        <Label>202</Label>
        <Label>206</Label>
        <Label>210</Label>
        <Label>250</Label>
        <Hook>202</Hook>
        <Hook>206</Hook>
        <Hook>210</Hook>
        <Hook>250</Hook>
    </EndButtons>
    <StartButtons>
        <Label>202</Label>
    </StartButtons>
 </DangerLabels>

Switch keys are referenced by their linked switch. Refer to Appendix D, and E, for the names of all the switch keys, end buttons. Start button names are as they are printed on the panel.

Alternative Spawning

Used when trains normally spawning to a particular spawn track should be rerouted to a different spawn track.

SpawnTrack: defines the spawn track from which trains are rerouted. Trains normally spawning here will spawn elsewhere.
AltTrack: defines the spawn track where trains are routed to.

The following attributes are are optional:

startTime: the time from which the rerouting is active (if omitted, start time is the beginning of time)
endTime: the time until the rerouting is active (if omitted, ending time is the end of time)
delayMin: minimum time, in seconds, the train should be delayed. If omitted, value is 0.
delayMax: maximum time, in seconds, the train should be delayed. If omitted, value is 0.

    <AlternativeSpawning SpawnTrack="SPAWN_ORIGIN_0" AltTrack="SPAWN_TARGET_0" startTime="11:45:15" endTime="13:30:00" delayMin="120" delayMax="360"/>

Collars

Switch Key Positions (NX panels)

Only applicable for NX panels.

Switch keys can be put into positions other than neutral. The name of the linked switch is required, as is the position (N = normal, R = reverse.)

 <SwitchKeyPositions>
    <Key name="251A" position="N" />
    <Key name="253" position="R" />
 </SwitchKeyPositions>

Switch Positions (Sp Dr S 60 panels)

Only applicable for Sp Dr S 60 panels.

Switches can be put into positions other than neutral. The name of the linked switch is required, as is the position (Normal or Reverse)

 <SwitchPositions>
    <Switch name="230" position="Reverse" />
    <Switch name="121" position="Normal" />
 </SwitchPositions>

Panel Magnets

Only applicable for Sp Dr S 60 panels. Sometimes it is necessary to place reminders directly on the panel to indicate various things worth remembering. A good example is indicating where engineering work is occurring or where wrong line working is active. The solution is panel magnets. These are magnetic labels that can be placed anywhere on the panel. The following XML-tags can be used to place panel magnets on the panel.

 <Magnets>
    <Magnet X="30.63124" Y="17.50357" type="MAGNET002" />
    <Magnet X="135.6526" Y="74.39016" type="MAGNET003" />
    <Magnet X="264.8763" Y="135.908" type="MAGNET005" />
 </Magnets>

The tiles on panel are all 95 x 60. The position of the magnet is relative to the upper left corner of the panel (=origin)

Example for all types of magnets

 <Magnets>
    <Magnet X="8572.564" Y="363.0197" type="MAGNET001" text="hello" color="-65536" />
    <Magnet X="8612.075" Y="441.1606" type="MAGNET002" />
    <Magnet X="8682.51" Y="503.7908" type="MAGNET003" />
    <Magnet X="8736.923" Y="565.8123" type="MAGNET004" /
    <Magnet X="8795.455" Y="624.3447" type="MAGNET005" /
    <Magnet X="8862.107" Y="687.1921" type="MAGNET006" />
    <Magnet X="8935.933" Y="745.3115" type="MAGNET007" />
    <Magnet X="9017.878" Y="796.0394" type="MAGNET008" />
    <Magnet X="9092.02" Y="850.6696" type="MAGNET009" />
    <Magnet X="9154.453" Y="897.4954" type="MAGNET010" />
    <Magnet X="9212.986" Y="952.1256" type="MAGNET011" />
 </Magnets>

Panel Magnet Types

To be translated / information needs to be proved to be correct

MAGNET001

There is one special magnet that initially looks completely black. However, it can be provided with a short amount of text. This can be any text, as long as it is fairly short – there’s not a lot of room to write on the magnets. You can also set the color of this type of magnet.

MAGNET002

OHLE Earthed/Switched Off

MAGNET003

Track In Possession (Gesperrtes Gleis)

MAGNET004

Wrong Line Working Active (Befahren des linken (falschen) Gleises)

MAGNET005

Section Clear Confirmation Required (Räumungsprüfung)

MAGNET006

Unexpected Track Occupation (Abschnittsprüfung)

MAGNET007

Maintenance Vehicle / Track Occupation Not guaranteed (Kleinwagenfahrt)

MAGNET008

Out-Of-Gauge Train (Lademassüberschreitender Zug)

MAGNET009

Do Not Run Against Sense Of Traffic (Nicht Links Fahren)

MAGNET010

Engineering Works (Arbeiten)

MAGNET011

Railway Crossing Defect (Bahnübergang)

Infrastructure Locking

Various infrastructure items can be manually locked.

Locked tracks, signals and switches must be enclosed in a LockedItems tag, like so:

   <LockedItems>

   <!-- Locked items go here -->

   </LockedItems>

Tracks

To lock a track:

   <LockedTrack name="12AT"/>

If the track has S600 capability, the syntax is slightly different:

   <LockedTrackS600 name="12AT"/>

Signals

Locking a signal is done like so:

   <LockedSignal name="2"/>

Switches

Locking a switch is done like so:

   <LockedSwitch name="17"/>

Example

Here's an example that includes several entries:

   <LockedItems>

      <LockedSwitch name="17"/>
      <LockedSwitch name="19"/>
      <LockedSignal name="2"/>
      <LockedTrack name="1AT"/>

       <!-- More entries as needed -->

   </LockedItems>

Spawn Point Locking

When the player calls a neighbour to request that no trains be sent via a certain track, the neighbour marks that track as 'unusable' until the player calls the neighbour to announce that the track is available again. To set a particular track as 'unusable' use the following:

 <SpawnPointLocking>
    <SpawnPointLock track="SPAWN_VP_0"/>
 </SpawnPointLocking>

Catenary System

It is possible to configure the catenary system differently than the way it is by default. If you are wanting to create a scenario that instructs, tests, or simply challenges the player to manage the system, then several things must be remembered:

The player can only operate the catenary system if the CatenaryExpert option is set to 'true.' When set to 'false,' scenario catenary system overrides are ignored.
Due to the way the catenary system is modeled, its necessary for the system to 'power up' as the simulation is loaded. It is possible, but not recommended, to define the system so that serial connectors will trip when the simulation is loaded. The player will hear a load “bang” as the simulation loads! A more likely situation is where parts of the system are off, and the player must re-power the catenary correctly.
The player would likely benefit from a diagram showing which connectors are on, and which are off. This can be provided in the additional instructions.

The catenary system is configured by a scenario such that only the differences, compared to the default system, are required to be specified. This prevents the scenario designer from having to completely specify the network. An fictitious example is shown below:

 <CatenarySystem>
    <CatenaryConnector description="AA" default="Open" />
    <CatenaryConnector description="BB" default="Open" danger="true" />
    <CatenaryConnector description="S" default="Open" danger="true" />
    <CatenaryConnector description="R4" default="Closed" />
 </CatenarySystem>

The description defines which connector is being overridden. These descriptors are identical to those found in the View > Catenary Controls window in the simulation. Note that the serial connectors are shown as – X – but the description is just X (the dashes are added for emphasis).

The 'default' attribute defines which state the connector is in when the simulation starts. If a danger cap is required, the state must be 'Open.' The optional attribute 'danger' is set to true to indicate that a red danger cap is placed over the connector.

Hot Axle Boxes

Some track layouts have track-side sensors that notify the dispatcher when there is a vehicle that passes that has an axle with a high temperature. This provides an early warning system for mechanical problems.

The scenario system supports changing where these sensors are located or adding new sensors that are not part of the layout.

clearDefault: (boolean); When true, clears all existing hot axle sensors.

 <HotAxleBoxes clearDefault="true" />

To add new boxes or change existing boxes without removing existing boxes:

 <HotAxleBoxes>
  <Box track="11AT" label="11" distance="50" />
  <Box track="13AT" label="13" distance="50" />
  <Box track="15AT" label="15a" distance="50" />
  <Box track="15AT" label="15b" distance="1950" />
 </HotAxleBoxes>

If the boxes exist, the distance will be overridden. If the boxes do not exist, they will be created anew.

track: Name of the track on which the sensor resides.

label: The label printed on the box.

distance: The distance, in metres, the sensor is from the left edge of the insulation joint.

Headed Towards Overrides

Each train has an (optionally) defined text entry that indicates where it's headed. If this 'headed-towards' entry does not match the headed-towards entry in a signal, then the simulation knows that the train is headed in the wrong direction, and simulates the driver stopping and calling in to the dispatcher to complain.

In some cases, it's necessary to disable this checking mechanism per signal and, optionally, within a defined time window.

Below is an example of four signals that have different time ranges defined. Note that startTime and endTime are optional. If a startTime is omitted, then the override begins at the beginning of time. Likewise, if the endTime is omitted, the override is active until the end of time. If both startTime and endtime are omitted, the override is active for all time, within the scenario.

 <HeadedTowardsDisable>
    <Signal name="765" startTime="11:45:00" endTime="11:50:00"/>
    <Signal name="123" startTime="11:58:00" />
    <Signal name="92"  endTime="11:55:00"/>
    <Signal name="96"  />
 </HeadedTowardsDisable>

Activated Signals

Sets up cover signals.

 <ActivatedSignals>
    <Signal name="123"/>
 </ActivatedSignals>