Trainz/Scenarios (Scripted Activities)


 * Trainz-scenarios will be an unsupported type in Trainz/Trainz: A New Era (TANE) (post-TS12 64 bit release of Beta 'Community Edition' by download December 2014, Standard Edition (also a Beta) arrived May 2015; 1st Service Pack improvements expected end of Summer 2015.

Scenario Introduction
A scenario in fiction has a well understood connotation as the circumstances consisting of a backstory and a situation which a protagonist must somehow deal. This broad definition while applicable in the same broad sense in Trainz, actually has two mechanisms of presenting the game-play aspect of Trainz, that is the Gameplay in the software suite: a task which an operator is supposed to perform in a Driver session, a Goal, or Problem. In short a quest with a mission to master. A well written one presents aome kind of scoring of 'Points' to measure your performing self against both a standard, and your own high score. Also well written ones present a clear outline of the task, its end conditions, and assumes the Driver (Us) knows nothing of the Route/Layout ahead of time. Most fail that criteria. Further, well written ones allow one to reopen the instructions and refresh the memory and compare the names (sometimes odd to the ear) to the minimap labels. They also present situational modifiers, it was an unforgettable experience to once drive a Freight to a Schedule only to realize a misidentification of where the consist was (resulting in backing down speed considerably for about four or five minutes) required the Driver to play catch-up&mdash;but whilst careful to stay below the posted speed limit, the Session writer didn't bother to tell us the rules in that country automatically decrement at certain ranges of speed, meaning a Freight had to stay 10, 15 or 25 mph under the speed posted limit when and if it fell into those range brackets. Like many such problem missions, this one deducted points for speeding. Would you ever forget the experience of bringing the Freight into the final couple of stops on time, completing it and finding your final score was -384 (down from 800+ when last noticed/checked!) The older of these game-play quest sequences was in fact called a scenario by Auran in 2001-2002 (hereafter called a 'Trainz-scenario'), while the newer mode is called a session. From the standpoint of game-play to the Driver in Trainz there is virtually no difference save one: They show up differently in the Driver menu. From the standpoint of creation of one or the other, the difference is vast.
 * The first Game-play in Trainz

Trainz-Scenarios are interactive scripted activities for a user to operate in the Trainz Driver GUI module&mdash;the most game-like of the varied kinds of entertainment offered by the software system. They invariably have targeted completion goal or state, and many are written to provide scoring allowing a Driver an opportunity to compete with others or best her previous best score. They vary in nature considerably, some providing step-by-step instructions for each stage of an operation (e.g. Tutorials on how to run Trainz), others merely displaying the details of an objective and leaving it to user to devise a method of achieving it. 'Shunting puzzle scenarios', perhaps the most realistic Trainz Driver 'quest' or 'problems' model 'typical Railroad operations'  tend to adopt the latter style. Some 'schedule keeping challenges' follow the terse mode, presenting a single schedule at the start up of a driver situation. A wide variety of different events can be triggered within a Trainz-Scenario. It is possible to display HTML text and images, and to play sounds, add trains 'out of the blue' as traffic (not visible on the map just moments before), or change load states of rolling stock. In the earliest Trainz, Trainz-Scenarios which are written using TrainzScript.exe, a separate utility no longer shipped as part of releases beginning with TRS2006, the based scenario was necessary for filling coal cars or other such loads 'off camera' and so were well suited to mirror the reality of many shortline or yard engine 'switching' operations where the locomotive engines pick up and drop off cars at various locations and return the loaded or unloaded rolling stock to a collection yard or sorting yard where it is appropriately shunted into or taken from a longer regional train. But TRS2004 also introduced interactive industries (in 2003) and the Session editor and driver rules improvements, while still fully supporting the Trainz-Scenario. Versions since might be best considered as 'read-only' implementations where a downloaded Trainz-Scenario can still be played, but not written.

Trainz-Scenarios were introduced with the release of to the original Trainz release as well as in Trainz UTC, and are one of the main improvements that make many veteran Trainzers consider that Trainz 1.3 version a second separate major release. Scenarios were fully supported in TRS2004, as an alternative back-compatible mode of scripting activities … even as the release introduced the new more generalized Sessions'. They are only partially supported in TRS2006 and Trainz Classics through the newest Trainz Trainz 2012, meaning existing sessions will (usually) still run if imported or downloaded, but the TrainzScript software utility has neither been updated and has not been bundled as part of those newer releases because the 'Session' is more flexible, and can do everything the older Trainz-Scenario technology could do. In other words (compare above vs scenario): " Trainz-Sessions are interactive scripted activities for a user to operate in the Trainz Driver GUI module&mdash;the most game-like of the varied kinds of entertainment offered by the software system".

Some Methods Of Creating Scenarios

 * TRS2004 owners can use the built-in method of creating the initial structure of a scenario, then using a text editor program to write the necessary coding. This method involves programming in GameScript, which is a "C"-like language with numerous extensions.
 * Both TRS2004 and TRS2006 owners can use the SCS (Scenario Creation System) program which is offered as freeware by the Trainz Pro Routes third-party Trainz fansite. There are separate versions of SCS for TRS2004 and TRS2006. SCS aims to make the scenario creation process as straightforward as possible but even then some considerable effort will be required. Full manuals are available for SCS.

An Overview Of TRS2004 Scenario Creation
The GameScript API (Application Programming Interface) documentation can be found in the "Trainz Railroad Simulator 2004 " which can be downloaded from Auran's web site. Some familiarity with the concepts and individual functions listed in this document is vital.

The following is a highly simplified overview of what is inherently quite a complicated procedure. To keep things as simple as possible, it omits many details.

Open the relevant layout in Surveyor.

Add any desired trackmarks, triggers and other trackside objects. Trains can be created at trackmarks. Events will be triggered when trains enter triggers. Do not save the changes to the layout.

In the Surveyor menu, invoke the "Export Scene Data" option and choose a suitable name for the new scenario.

Close Surveyor. Once again, do not save the changes to the layout.

A new folder will have been created in C:\Program Files\Auran\TRS2004\World\Custom\scenarios folder with the name that you specified in Surveyor. This newly created folder will contain the files which form the basis for the scenario.

The TSO (trackside object) file contains the details of the modifications to the layout which are individual to this scenario, for example the additional trackmarks and triggers that you added in Surveyor.

Using a text editor, open the scenario's config.txt file. The kuid-table will already include the layout. You need to add the rolling stock assets that the scenario uses, for example: (How!!!)

If you wish, also embellish the description text.

Using a text editor, open the gs (GameScript) file. By default this file contains a daunting amount of coding, almost all of which should be left unmodified. You need to add additional sections of code in the correct places.

In the "create consist specs" section, add coding to specify the rolling stock which makes up each train when it is initially placed on the layout. The following example has one train consisting of an AN830 Class loco pulling one QLX louvre wagon:

In the "create consists" section, add coding to place the trains at trackmarks. The following example places a train made up of the "PlayerTrainKuids" consist specification at a trackmark named TM01:

In the "gameplay" section, above the "scenarioDone = true;" line, add coding to set some initial parameters and perform the scenario's actions. The following is a very simple example which merely allows the user to drive the PlayerTrain and nothing else.

In the above example the "while" loop will wait forever until the user exits the scenario. A real scenario would normally complete properly and shut down without user intervention being required.

No compilation is required. Once the gs file is correctly created, the scenario can be run. In practice, there is usually a need for numerous iterations around the editing and testing cycle.

Comparisons to programming languages

 * Some Comments Regarding &  for people familiar only with traditional BASIC or Visual BASIC, and no other high level computer languages:

In Trainz, objects internally pass messages between themselves. These internal messages are not seen by the user. GameScript coding can generate internal messages and also detect and receive internal messages. Each internal message has four properties: its source, its destination, its major (i.e. its major message type) and its minor (i.e. its minor message type). While this message passing concept can be ignored by the beginner, it is often featured in the Auran documentation and therefore worthy of mention here.

One final vital piece of advice: start with something really, really simple. Making a train appear on a track is in itself a very considerable achievement for someone starting to learn GameScript.

Example #1: IF Statement Example #2: FOR Loop Example #3: WHILE Loop Example #4: Variable declaration and initialisation Example #5: Declare an array Example #6: Define a user-defined function