TRAINZSCRIPT TUTORIAL

Introduction

Welcome to the first TrainzScript tutorial. TrainzScript is the scripting language developed for Auran Trainz. This document will teach you how to create a very simple scenario -- it does not aim to teach you how to program, or teach you programming concepts. TrainzScript may be used from Version 1 Service Pack 3 onward to create scenario content. If you do not understand programming concepts, you may need to read further tutorials before trying to create Scenarios for Trainz. We will be releasing a user-friendly interface for compiling powerful scripts in a later version.

Please take the time to follow the steps of this document from start to finish. The tutorial is presented in an informal (non text book) manner. More help can be found by visiting the Scenarios forum.

Where do I find TrainzScript

TrainzScript is a scripting language used to drive the scenarios. Each scenario will have one or more TrainzScript files (*.GS) located in its directory in the ...\Trainz\World\Custom\Scenarios folder. The supporting TrainzScript files are found in the ...\Scripts folder. The script files in this folder give you all of the supported functions required to control Trainz. Over time, you will learn most of the functions provided in these files. The TrainzScript compiler (gsc.EXE) is located in the ...\Bin folder.

Go to the ...\Bin folder in your DOS prompt, and run the compiler with the -d fag as follows.

gsc -d > reference.TXT

This will copy the TrainzScript documentation to the file reference.TXT. Consult this document as a reference manual for the TrainzScript language.

Creating A Scenario

Lets create our very first scenario. This will teach you how to use the TrainzScript compiler and guide you through the process required to make a simple scenario that just loads a map.

Launch Trainz, and create a new map in Surveyor. Lay a small track loop, and place a track mark named 'START' somewhere on your track. Make sure you name the track mark using UPPERCASE, as all named object in TrainzScript are case-sensitive. Place a lever somewhere on the track so we have something for the camera to focus on. Save your map and call it 'Tutorial1'.
Before exiting out of Surveyor, select the 'Export Scenario TSO' from the Trainz Main Menu, and type in 'Tutorial1'.
Quit out of Trainz go to your ..\Trainz\World folder. Locate the config.TXT file in the folder ...\Trainz\World\Custom\Maps\Tutorial1.
Open the config.TXT file of your Tutorial1 map. It should look something like the following.

kuid <KUID:-2:2023211879> kind map username Tutorial1 workingscale 0 workingunits 0 water <KUID:-1:110015> region Australia

Note the KUID for your new layout. In this case, it is -2:2023211879.

Now go to the ...\Trainz\World\Custom\Scenarios\Tutorial1\ folder and open the conflg.TXT file of your Tutorial1 Scenario. It should look something like the following.

kind activity username Tutorial1 scriptlibrary Tutorial1 scriptclass MyTutorial1 kuid <KUID:-2:2023211880> kuid-table { tutorial1 <KUID:-2:2023211879> } description "Tutorial1"

A few notes on this. The kuid-table is a name-KUID translation table used by the scenario. All objects loaded by the scenario must be entered in this table. The scenario will reference the KUID by name, which is case-sensitive. For example, when the script loads the map, it will reference it by the name "Tutorial1", which will be looked up in the kuid-table, and found as KUID:-2:2023211879. Trains and rolling stock, etc. are referenced in the same manner. You will also notice that the scenario has its own unique KUID. The description text is displayed in the scenario selection screen.

Next, we will begin editing the TrainzScript file. Open the Tutorial1.GS file with your desired programming editor. This file is created from the template.GST file in the ...\scripts\ folder when you export the TSO. The syntax of the following script is explained in the compiler documentation, but if you have a read through it, it is pretty self-explanatory. The file looks like this.

include "trainz.GS"
// // class MyTutorial1 // brief This is the scenario class. Modify this class with // your own gameplay. // game class MyTutorial1 isclass Scenario { Train myConsist; bool scenarioDone = false;
// // Load will be called by Trainz to load the scenario map, and when the user presses Ctrl-L // param data is the save game data if loading a saved game. // bool Load( string data) {     if(data and data.size())     {       Interface. Load(data);     }
    // load the map     if(! World.LoadMap(World.FindKUID(" Tutorial1")))     {       Interface.Log(" Error loading scenario map" );       return false;     }
    return true; }
// // Save will be called by Trainz when the user presses Ctrl-S. // return the save game string, such that load will be able to restore the save game // from the last save check point.
// string Save( ) {      return Interface. Save( ); }
// // TrainDerailed will be called by Trainz when a train derails // void TrainDerailed(int trainId) {     if(! scenarioDone)     {       World.EndScenario(10);       scenarioDone = true;     } }
// // TrainCollided will be called by Trainz when a train collides // void TrainCollided(int trainId) {     if(! scenarioDone)     {        World.EndScenario(10);        scenarioDone = true;     } }
// // TrainSpeedingFine( ) is called by Trainz every second your trains speed exceeds the floating limit // void TrainSpeedingFine( ) {      // Interface.AdjustScore(-10); }
// // TrainBadCouple( ) is called by Trainz when vehicles couple greater than 8KPH. // void TrainBadCouple(int vehicleId) {      // Interface.AdjustScore(-200); }
// // // main thread // brief main is executed automatically after Load( ) is called. edit
// main to contain your scenarios gameplay. // //
thread void main(void) {      // Start the monitor thread to monitor speeding, derailing etc.      Monitor( );
     //      // create consist specs      //
     //      // create consists      //
     //      // gameplay      //
     scenarioDone = true; } } ;

The final step is to compile the scenario. Copy the makescript.BAT file from ...\Scripts\Docs folder into your ...\Trainz\World\Custom\Scenarios\Tutorial1 folder. Run this batch file and make sure no errors are reported (consult the forum for assistance). Notice that this batch file uses the TrainzScript compiler (gsc.EXE) to create the Tutorial1.GSL file.
You are now ready to launch your very first scenario. The scenario should load your Tutorial1 map. You will notice that the camera is focused on the junction we placed on the map. Had we not placed that junction, the map would not be visible, as Trainz has nowhere to focus the camera.

You have now successfully created your very first scenario. Study the Highland Valley scenarios and the script.GS files for further TrainzScript information. Scripting questions may also be asked on the forums.

Good luck, and we hope you will enjoy your scripting efforts.