Hello World, Setting Up An Asset Script. - Revision history

Danny252: /* Next Tutorial */ Add navigation links

2020-12-28T14:37:56Z

Next Tutorial: Add navigation links

← Older revision		Revision as of 14:37, 28 December 2020
Line 112:		Line 112:
	</gallery>		</gallery>

	== ~~Next Tutorial~~ ==		== Navigation ==

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

Danny252: /* Original Tutorial */ Add links to Init() docs

2020-12-28T14:33:43Z

Original Tutorial: Add links to Init() docs

← Older revision		Revision as of 14:33, 28 December 2020
Line 31:		Line 31:
	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.)		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 Init(void) {'''''<br>		'''''[[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.)		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.)

Danny252: Add links to reference docs

2020-12-28T13:36:45Z

Add links to reference docs

← Older revision		Revision as of 13:36, 28 December 2020
Line 25:		Line 25:
	I've kept comments separate from the code to start with to keep the code more legible.		I've kept comments separate from the code to start with to keep the code more legible.

	'''''include "MapObject.gs"'''''<br>		'''''[[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.		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 {'''''<br>		'''''[[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 ''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.)		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.)

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

Line 39:		Line 39:
	* ''(void)'' means that the method does not need any parameter information to be passed in when it is called.		* ''(void)'' means that the method does not need any parameter information to be passed in when it is called.

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

Danny252: Add TRS19 example of displaying messages - improvements/simplifications welcome!

2020-12-28T12:54:36Z

Add TRS19 example of displaying messages - improvements/simplifications welcome!

@@ Line 1: / Line 1: @@
-'''''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)'''''
+__FORCETOC__
 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.
@@ Line 59: / Line 64: @@
 [[Image:HelloWorld.jpg]]
-<br><br>
-Next Tutorial: [[Getting Information From the Game, Writing Your Own Methods.]]<br>
+== Trainz 2019 Example ==

Pcas1986: Warning that tutorial doesn't work as expected.

2020-09-10T05:40:53Z

Warning that tutorial doesn't work as expected.

← Older revision		Revision as of 05:40, 10 September 2020
Line 1:		Line 1:
			'''''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.		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.

Pcas1986: Method ShowHelpPopup() was misspelled.

2016-10-15T23:04:56Z

Method ShowHelpPopup() was misspelled.

← Older revision		Revision as of 23:04, 15 October 2016
Line 9:		Line 9:
	public void Init(void) {		public void Init(void) {
	inherited();		inherited();
	Interface.~~ShowPopupHelp~~("Hello World",GetAsset(),Interface.GetTimeStamp());		Interface.ShowHelpPopup("Hello World",GetAsset(),Interface.GetTimeStamp());
	//Exception("Hello World\n\n"); // use this instead of ~~ShowPopupHelp~~ in old builds		//Exception("Hello World\n\n"); // use this instead of ShowHelpPopup in old builds
	}		}

Line 34:		Line 34:
	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.		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.~~ShowPopupHelp~~("Hello World",GetAsset(),Interface.GetTimeStamp());'''''<br>		'''''Interface.ShowHelpPopup("Hello World",GetAsset(),Interface.GetTimeStamp());'''''<br>
	This prints out the message to the screen.		This prints out the message to the screen.

Andi06 at 23:06, 24 April 2013

2013-04-24T23:06:08Z

← Older revision		Revision as of 23:06, 24 April 2013
Line 1:		Line 1:
	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 ~~Exception~~ browser to show our results. This will produce a message box in the middle of the screen ~~headed ''A non fatal script error has occurred''. Don't worry about the error message or the text below it, we are just using this message box to print out a result~~.		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:		This is an asset script which will do this:
Line 9:		Line 9:
	public void Init(void) {		public void Init(void) {
	inherited();		inherited();
	Exception("Hello World\n\n");		Interface.ShowPopupHelp("Hello World",GetAsset(),Interface.GetTimeStamp());
			//Exception("Hello World\n\n"); // use this instead of ShowPopupHelp in old builds
	}		}

Line 33:		Line 34:
	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.		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.

	'''''~~Exception~~("Hello World~~\n\n~~");'''''<br>		'''''Interface.ShowPopupHelp("Hello World",GetAsset(),Interface.GetTimeStamp());'''''<br>
	This prints out the message to the screen~~. ''\n\n'' simply adds a couple of carriage returns to the end of the message to make it easier to see~~.		This prints out the message to the screen.

	'''''}''''' and '''''};'''''<br>		'''''}''''' and '''''};'''''<br>
Line 51:		Line 52:
	* If you see this then you have successfully created your first asset script:		* If you see this then you have successfully created your first asset script:

	* '''Note: ~~In TS2009~~'''~~, the exception message will not appear on the screen. Instead~~, you will ~~notice a red button appear in the lower right corner of your screen. Click the red button~~ to ~~display the~~ exception ~~dialog, then click the '''''More''''' button~~ to ~~view~~ your ~~"Hello World" message~~.		* '''Note: Before TS2012''', you will need to use an exception to display your text. Refer to old versions of these pages for details.

Windwalkr: 1 revision

2010-02-03T13:59:01Z

1 revision

← Older revision	Revision as of 13:59, 3 February 2010
(No difference)

imported>John259: Various attempts to make it clearer for beginners

2009-11-24T17:38:58Z

Various attempts to make it clearer for beginners

New page

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 Exception browser to show our results. This will produce a message box in the middle of the screen headed ''A non fatal script error has occurred''. Don't worry about the error message or the text below it, we are just using this message box to print out a result.

This is an asset script which will do this:

include "MapObject.gs"

class Tutorial isclass MapObject {

public void Init(void) {
inherited();
Exception("Hello World\n\n");
}

};

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.

'''''Exception("Hello World\n\n");''''' 
This prints out the message to the screen. ''\n\n'' simply adds a couple of carriage returns to the end of the message to make it easier to see.

'''''}''''' 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: In TS2009''', the exception message will not appear on the screen. Instead, you will notice a red button appear in the lower right corner of your screen. Click the red button to display the exception dialog, then click the '''''More''''' button to view your "Hello World" message.

[[Image:HelloWorld.jpg]]
 
Next Tutorial: [[Getting Information From the Game, Writing Your Own Methods.]]