View source for Hello World, Setting Up An Asset Script.

__FORCETOC__

'''''Warning:  The original 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)'''''

An alternative version of the tutorial has been provided for TRS19, although it is currently significantly more complex.

== Original Tutorial ==

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.

'''''[[TrainzScript Keywords#include|include]] "MapObject.gs"'''''<br>
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.

'''''[[TrainzScript Keywords#class|class]] Tutorial isclass [[Class MapObject|MapObject]] {'''''<br>
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 ''[[Class MapObject|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.)

'''''[[TrainzScript Keywords#public|public]] void [[Class TrainzGameObject#Init|Init]](void) {'''''<br>
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.

'''''[[TrainzScript Keywords#inherited|inherited()]];'''''<br>
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.

'''''[[Class Interface|Interface]].ShowHelpPopup("Hello World",[[TrainzGameObject#GetAsset|GetAsset]](),Interface.[[Class Interface#GetTimeStamp|GetTimeStamp]]());'''''<br>
This prints out the message to the screen.

'''''}''''' and '''''};'''''<br>
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.


[[Image:HelloWorld.jpg]]

== Trainz 2019 Example ==

The following Trainz-2019-compatible example will display "Hello World!" in three ways:
* Writing a message to the Developer Log using ''Interface.Print''
* Writing a message to the Driver's Message Window, using the same ''Interface.Print''
* Displaying a browser window with a simple HTML page

<pre style="white-space: pre;">
include "MapObject.gs"

class MyFirstScript isclass MapObject {
    Browser browser;
    void HelloWorld(Message msg);
    public void Init() {
        inherited();
        // Wait 5s for UI to load - browser window will not display if we continue too early.
        // It is not possible to use Sleep() within an Init method.
        // 
        AddHandler(me,"HelloWorld","","HelloWorld");
        PostMessage(me,"HelloWorld","",5.0);
    }

    void HelloWorld(Message msg) {
        if (!browser) {
            browser = Constructors.NewBrowser();
        }
        browser.SetWindowPosition(0,0);
        browser.SetWindowStyle(browser.STYLE_DEFAULT);
        browser.SetWindowSize(200,500);
        browser.LoadHTMLString(GetAsset(), "<html><body>Hello World!</body></html>");

        // This log entry will be visible in Launcher > Developer > Show Logs,
        // and in the Driver messages
        Interface.Print("Hello World!");
        Interface.SetMessageWindowVisible(true);
    }
};
</pre>

Log output can be viewed (in Trainz 2019) via Launcher > Developer > Show Logs. It may be helpful to also use Clear Logs before opening the session in Driver.

<gallery>
File:TrainzHelloWorldBrowser.png|Hello World message - in-game browser
File:TrainzHelloWorldMessage.png|Hello World message - driver messages
File:TrainzHelloWorldLog.PNG|Hello World message - developer log
</gallery>

== Navigation ==

* Next Tutorial: [[Getting Information From the Game, Writing Your Own Methods.]]
* Back to [[Getting Started in TrainzScript]]