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:

<!-- This is 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.
• 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.

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.

Irregularities

Two types of irregularities can be explicitly defined:

 <Irregularities>
    <OccupancyLight track="250AT" startTime="08:12:00" endTime="08:17:40" />
    <OccupancyLight track="253T" startTime="08:16:00" endTime="08:17:20" />
    <SwitchOOC switch="253" startTime="08:16:05" endTime="08:17:00" />
 </Irregularities>

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

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.

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></nowiki>
    <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></nowiki>
    <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 magents

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

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.

---

Return to Information about adding to and extending our simulations