Hello World, Setting Up An Asset Script.

Revision as of 15:40, 10 September 2020

Warning: This tutorial appears to be faulty for TRS19 and perhaps TANE. The message that should display in the "ShowHelp" message box is unreadable perhaps because of background colour changes. My intention is to rewrite the tutorial so it will output messages to the screen while in driver and/or write messages to the logs. This achieves the original aim and provides a useful debugging tool. (pcas1986)

It's traditional for your first script to print Hello World to the screen. Trainz doesn't actually make this very easy because there isn't a straightforward way of writing to the user interface, especially in Surveyor. So we will have to use the PopupHelp browser to show our results. This will produce a message box in the middle of the screen.

This is an asset script which will do this:

include "MapObject.gs"

class Tutorial isclass MapObject {

   public void Init(void) {
      inherited();
      Interface.ShowHelpPopup("Hello World",GetAsset(),Interface.GetTimeStamp());
      //Exception("Hello World\n\n"); // use this instead of ShowHelpPopup in old builds
   }

};

I've kept comments separate from the code to start with to keep the code more legible.

include "MapObject.gs"
We are going to be using MapObject as a base for the script. In order to do this we need to include a copy of the code for that class, this is achieved by using the keyword include followed by the name of the appropriate Trainz script file. Note that this statement is unusual in that it doesn't have a semi-colon on the end.

class Tutorial isclass MapObject {
This is the prototype or header for the script, it specifies that the name of the script class is going to be Tutorial and that it will subclass (inherit) all of the capabilities of the MapObject base class. (In simple terms a class is a set of related functions. The word inherit means that the new Tutorial class will have access to all the functions of the standard MapObject class.)

public void Init(void) {
Except in a TRS2004 scenario, Trainz scripts are incapable of doing anything of their own account. It is crucial that this is fully understood. They must always be instructed by the game. The mechanism that scripts use to accept instructions is the provision of standardised methods that will be called by the game engine. The most basic of these is Init() which is called whenever an object is first placed, or when it is already included in a map loaded by the game. (In simple terms a method is another name for a function.)

This is the header for the Init() function, a method which all asset scripts must contain.

• public means that the method is available to be called from elsewhere in Trainz.
• void means that the method does not return any value to the caller.
• (void) means that the method does not need any parameter information to be passed in when it is called.

inherited();
This should always be the first call in an Init() method. It ensures that any initialisation required by the parent class, in this case MapObject, will be undertaken before the script's own code is processed.

Interface.ShowHelpPopup("Hello World",GetAsset(),Interface.GetTimeStamp());
This prints out the message to the screen.

} and };
inform the compiler that the Init() method and the class definition, respectively, have finished.

To test this out:

• Find a simple unscripted asset, say a tree or a building, of kind scenery.
• Open its folder and create a plain text file called Tutorial.gs
• Copy and paste the script code in the box above into the text file.
• Open the asset's config.txt file and add these two tags:
• script Tutorial
• class Tutorial
• Trainzscript is case sensitive, make sure you capitalise the tags correctly.
• Commit the asset, start TRS, and open a map in Surveyor.
• Find the asset and place a copy on the map
• If you see this then you have successfully created your first asset script:

• Note: Before TS2012, you will need to use an exception to display your text. Refer to old versions of these pages for details.

Next Tutorial: Getting Information From the Game, Writing Your Own Methods.