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.

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.

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. This is not localised on purpose, as everyone should refer to a scenario using the same name.
• 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 an optional attribute:

• 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

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