TrainzOnline - User contributions [en]

TrainzScript Message Reference

2020-12-30T11:02:56Z

Danny252: /* How to listen for Messages */ Add link to `wait` definition.

==What are Messages and how can they be used?==

Messages:
* Are internal communications between objects within Trainz.
* Are completely hidden from the normal user, who won't be aware of their existence.
* Provide notification of events within the Trainz script environment.
* Provide a means of opening direct communications between objects.
* Provide a means of sending instructions from one script to another.
* Provide a means of timing scripted actions.

Messages are managed by the ''Router'', a sort of internal post office, and can be exchanged between any objects which descend from ''[[GameObject]]'', this includes driver commands, rules and libraries as well as almost all mesh based scriptable objects.

Scripts can:
* Listen for messages and use them to take appropriate actions in response to events and instructions.
* Use the message to extract information about the object sending or receiving the message.
* Define and issue their own messages.
* Listen in to messages intended for other objects.
* Send messages to themselves, to arrive after a specified delay, as a 'reminder' to do something at a future time.

Messages are small data objects containing five pieces of information:
* ''msg.major'': A string identifying the message type.
* ''msg.minor'': A string containing the message subtype or additional information.
* ''msg.src'': A reference to the object that sent the message.
* ''msg.dst'': The intended recipient. May be null if the message was ''broadcast'' (legacy behavior, no longer supported).
* ''msg.paramSoup'': A Soup object containing extra data about the message (may be null).

==How to listen for Messages==

There are three techniques you can use:

* ''[[GameObject#AddHandler|AddHandler()]]'' This is the simplest listening device and is most useful when you know that you will always be interested in this type of message. ''[[GameObject#AddHandler|AddHandler()]]'' is usually set up in the ''Init()'' method of a script. Hint: omit any optional spaces in statements that include an AddHandler function, as including them causes the function to be ignored without notification in TRS2004 and perhaps other versions as well.
* A ''[[TrainzScript Keywords#wait|wait()]]'' loop. This needs to run in a separate thread and allows for a temporary arrangement where you want to know about messages for a shorter period or under a specified set of conditions.
* ''[[GameObject#Sniff|Sniff()]]''. This allows you to 'eavesdrop' on messages being sent to another object.

==When and how to send Messages==

You might consider issuing messages of your own under the following circumstances:

* When an event has taken place in your script and other objects might need to know about it.
* When you want to make your object available to other scripts to allow them to call your methods directly.
* When you need to issue instructions to another object to carry out a particular task and you know that the target object will be able to understand your message.
* When you want your own script to take an action at some time in the future, or at regular intervals.

There are three routines you can use to issue messages:

* [[GameObject#SendMessage|SendMessage()]] dispatches the message immediately.
* [[GameObject#PostMessage|PostMessage()]] dispatches the message via the Router with a specified delay (which can be zero). The message will be executed on the next Router update after the delay has elapsed.
* [[Class Router#PostMessage|Router.PostMessage()]] allows messages to be dispatched even if the object you are scripting doesn't have its own messaging capabilities.

If the message destination is entered as ''me'' (meaning the current object) the message will be sent to the object which owns the script. If the destination is ''null'' the message will be ''broadcast'' and therefore available to any object in the session. Message broadcasting is obsolete as of TRS19 however, and may result in script exceptions or silent failures (depending on the local players compatibility setting).

If you have a reference to the message target (or if you know its name or id) you should consider the following:

* If you know which methods to use it might be more appropriate to call the other script directly.
* You should always avoid broadcasting messages if it is possible to send them directly to the intended recipient.

==Never Assume Anything==

The messaging system contains many traps for the unwary. If you are working with a junction for instance you will receive an ''Object,Enter'' message whenever a train enters your object's trigger zone. It is not safe however to assume that a subsequent ''Object,Leave'' means that the train has crossed the junction and left on the other side. Any of the following would also produce ''Object,Leave'':
* The train might have stopped and reversed away from your object.
* An intervening junction might have been toggled so that the train is no longer visible to your object.
* The train might have coupled to another (and therefore ceased to exist) before reaching your object.
It is usually necessary to treat a message as an indication that the event you are interested in could have happened and to use other tests to confirm.

==Example==

Listening for messages and using message handler methods

include "MapObject.gs"

// script can be attached to any scenery object
// enable the message window to view the output in Driver mode
class Messenger isclass MapObject {

public void Init(void) {
inherited();
// listen for Junction and World,ModuleInit messages
AddHandler(me,"Junction","","ToggleHandler");
AddHandler(me,"World","ModuleInit","ModuleInitHandler");
}

thread void TriggerMonitor(void) {
// Trigger messages will be passed to us as a result of the
// Sniff() call in ModuleInitHandler
Message msg;
wait() {
// listen for Trigger,Enter, print a message when heard, continue listening
on "Trigger","Enter",msg: {
Interface.Print("A train has entered a trigger");
continue;
}
// listen for Trigger,Stopped, print a message when heard and then quit the thread
on "Trigger","Stopped",msg: {
Interface.Print("A train has stopped on a trigger");
Interface.Print("Trigger monitoring discontinued");
break;
}
}
}

void ToggleHandler(Message msg) {
// print a message whenever Junction,Toggled is broadcast
Interface.Print("A junction has been toggled");
}

void ModuleInitHandler(Message msg) {
if (World.GetCurrentModule() == World.DRIVER_MODULE) {
// attach a handler to the first train on the map instructing it
// to copy any Trigger messages to us
Sniff(World.GetTrainList()[0],"Trigger","",true);
// start monitoring Trigger messages
TriggerMonitor();
}
}

};

==See Also==
* [[List of Standard Messages]]
* [[Animation-Event Message]]
* [[Browser Messages]]
* [[Camera Messages]]
* [[Interface Messages]]
* [[MapObject Messages]]
* [[ModuleInit Message]]
* [[Object Messages]]
* [[pfx Message]]
* [[Signal Messages]]
* [[Train Messages]]
* [[Vehicle Messages]]
* [[GameObject]]

Class Asset

2020-12-29T11:32:19Z

Danny252: Add links between language reference pages

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]]
***Asset
 

The term ''Asset'' refers to an individual item of content for Trainz. All assets have a [[Class KUID|KUID]] which provides unique identification, a ''config.txt'' file which provides configuration data and an optional [[Class StringTable|StringTable]] which is a repository for indexed string values and a means of providing for foreign language translation.

An asset provides the information that TRS needs to place a new ''object'', also referred to as an ''instance'' of the asset, into the game environment.

Some of the methods in this class refer to the asset's ''kuid-table'', a container within ''config.txt'' which lists the kuids of other assets which are required for proper functioning. These assets are often listed using an integer index:
kuid-table {
0 <kuid:44179:60013>
1 <kuid:-3:10110>
}
The kuid-table is however in ''[[Class Soup|Soup]]'' format which allows descriptive labels to be used instead. This makes it easier for a script to refer to the [[Class KUID|KUID]] or the asset concerned:
kuid-table {
coal <kuid:44179:60013>
greencorona <kuid:-3:10110>
}

==FindAsset==
{{MethodHeader|public native Asset FindAsset(string kuidTableAssetName)}}
;Parameters
*'''kuidTableAssetName''' = Tag value referencing a dependency as entered in the ''kuid-table'' from the asset's ''config.txt''.
;Returned Value
*A reference to the asset represented by the ''kuid-table'' entry.
;Syntax
// kuid-table of this asset
kuid-table {
green <kuid:-3:10110>
}

Asset asset = GetAsset().FindAsset("green"); // returns a reference to the built-in green corona
;Notes
*Returns null if the kuid-table entry is invalid or if it does not exist.
*This method is the equivalent of ''[[Class World#FindAsset|World.FindAsset]]([[Class TrainzGameObject#GetAsset|GetAsset()]].[[#LookupKUIDTable|LookupKUIDTable]](kuidTableName))''
;See Also
*[[#LookupKUIDTable|LookupKUIDTable()]]
 

==GetConfigSoup==
{{MethodHeader|public native [[Class Soup|Soup]] GetConfigSoup(void)}}
;Parameters
*None
;Returned Value
*The contents of the ''config.txt'' file belonging to the scripted asset in [[Soup]] format.
;Syntax
Soup soup = [[Class TrainzGameObject#GetAsset|GetAsset()]].GetConfigSoup();
;Notes
*The Soup returned by this method will be read only.
*Sub containers within ''config.txt'' can be accessed as sub soups:
Soup meshTable = [[Class TrainzGameObject#GetAsset|GetAsset()]].GetConfigSoup().[[Class Soup#GetNamedSoup|GetNamedSoup]]("mesh-table");
 

==GetKUID==
{{MethodHeader|public native [[Class KUID|KUID]] GetKUID(void)}}
;Parameters
*None
;Returned Value
*[[Class KUID|KUID]] of current asset
;Syntax
KUID kuid = GetAsset().GetKUID();
;Notes
*Return format is <kuid:1234:5678> or <kuid2:1234:5678:9> as appropriate.
 

==GetLocalisedName==
{{MethodHeader|public native string GetLocalisedName(void)}}
;Parameters
*None
;Returned Value
*String representing the localised username of the asset.
*For English versions of the game this will be the contents of the ''config.txt'' tag ''username''
;Syntax
string username = [[Class TrainzGameObject#GetAsset|GetAsset()]].GetLocalisedName();
;Notes
*For other language versions the result will be the equivalent localised username, if it exists.
*For German, ''username-de''
*For Italian, ''username-it''
*If there is no localised tag, then the contents of ''username'' will be returned.
 

==GetStringTable==
{{MethodHeader|public native [[Class StringTable|StringTable]] GetStringTable(void)}}
;Parameters
*None
;Returned Value
*A reference to the asset's [[Class StringTable|StringTable]].
;Syntax
StringTable strings = GetAsset().GetStringTable();
;Notes
*Any asset can have a ''[[Class StringTable|StringTable]]'' in its configuration that consists of a collection of named string elements in ''Soup'' format.
*Foreign language versions will return a localised StringTable, using the ''config.txt'' container ''string-table-es'' for instance. This provides for translation of the user interface of an asset.
*The returned ''[[Class StringTable|StringTable]]'' object provides methods to easily access these strings.
 

==LookupKUIDTable==
{{MethodHeader|public native [[Class KUID|KUID]] LookupKUIDTable(string kuidTableAssetName)}}
;Parameters
*'''kuidTableAssetName''' = Name referencing a dependency KUID as entered in the ''kuid-table'' from the asset's ''config.txt''.
;Returned Value
*A reference to the [[KUID]] represented by the ''kuid-table'' entry.
;Syntax
// kuid-table of this asset
kuid-table {
green <kuid:-3:10110>
}

KUID kuid = [[Class TrainzGameObject#GetAsset|GetAsset()]].LookupKUIDTable("green"); // returns a reference to the built-in green corona
;Notes
*Returns null if the kuid-table entry is invalid or if it does not exist.
;See Also
*[[#FindAsset|FindAsset()]]
 

==Code Examples==

==Related Methods==

[[Class World#Find Asset|World.FindAsset()]]

[[Class TrainzGameObject#GetAsset|TrainzGameObject.GetAsset()]]

[[Class World#GetAssetList|World.GetAssetList()]]

==Categories==
[[Category:Script Class]]

HowTo/Search for objects in the world

2020-12-28T20:06:26Z

Danny252: /* Named Object Searches */ Correct example to wait for AsyncResult, not AsyncLoadComplete

Scripted asset may sometimes wish to search for other objects within the world, either in bulk lists, or for a specific single object. This page is intended to provide an overview of how this is achieved in the latest versions of Trainz. Details about certain legacy search methods and the best modern techniques to update them to are also provided in the final section of this page.

==Object Identification==
Scripted objects identified in script using several different methods, many of which have become obsolete as Trainz and the script environment has grown in complexity. As of trainz-build 4.5 (TANE SP2 and later) scripted objects should be identified using their GameObjectID, where present. This ID format has been designed to be future-proof/extensible, should the need arise, and supports various lookup and generic storage functions as per the legacy integer and string based IDs. For more information about legacy ID formats, see [[HowTo/Search_for_objects_in_the_world#Legacy_Search_Functions|here]].

The GameObjectID class is defined within GameObjectID.gs, which can be found in the Trainz core script folder (resources/scripts). For the most up to date and accurate usage instructions please see the comments within that file.

==Named Object Searches==
It is occasionally desirable for scripted assets to be able to search for objects within the world. Most commonly, this is a requirement of session rules, which frequently require a session creator to specify target trains, junctions, signals, etc, in order to perform some gameplay function. Occasionally, placable assets such as industries etc may also require this feature. One such example is the Interlocking Tower asset type, which performs complex management of track blocks using management of user defined signals, junctions and crossings.

As of trainz-build 4.5 (TANE SP2 and later) manual object searches are performed via the World.GetNamedObjectList() function. This function takes both a [[Category_List|category list]] and a partial name, allowing for very specific searches, or quite broad ones. Once called, this function returns an object of type AsyncObjectSearchResult, which is used to monitor for the search completion, and then to retrieve the results. For the most up to date and accurate information on how to use GetNamedObjectList and AsyncObjectSearchResult, please see their script comments. Both are currently defined in World.gs, which can be found in the Trainz core script folder (resources/scripts).

Usage example:

thread void SearchForTrains()
{
// Start a search for any traincars within the world
AsyncObjectSearchResult searchObj = World.GetNamedObjectList(AssetCategory.TrainCar, "");

// Sniff for search related messages, and then wait for either completion or failure
Sniff(searchObj, "ObjectSearch", "", true);
Message msg;
wait()
{
on "ObjectSearch", "Failure", msg:
if (msg.src == searchObj)
break;
continue;

on "ObjectSearch", "AsyncResult", msg:
if (msg.src == searchObj)
break;
continue;
};

// Check the results
int errCode = searchObj.GetSearchErrorCode();
if (errCode != AsyncObjectSearchResult.ERROR_NONE)
{
// TODO: Add any error handling here, such as waiting and reattempting the
// search later, showing an error message, throwing script exceptions, etc.
return;
}

// Get the search results
NamedObjectInfo[] results = searchObj.GetResults();

// TODO: Add any processing of the results here
}

==Storing References to Specific Objects==
As shown in the example above, named object searches return their results as an array of NamedObjectInfo objects. Currently, this class has 4 member variables:
* objectRef - A reference to the object, if it is currently loaded
* objectId - The GameObjectID for the object (see GameObjectID.gs)
* localisedUsername - The localised name of the object, for displaying to the player
* categoryString - A category string, usable to further determine the exact type and features of the object

Any script which wishes to save a reference to specific named object should /always/ do so via the GameObjectID. This is currently the /only/ safe and reliable way to store and later retrieve a specific object. If the object is currently loaded it is of course also safe to access and store a reference to the object itself, but note that Trainz may choose to unload the object at any time (if it is inactive, and sufficiently far enough away from the player, etc). Attempts to use an object which native code has unloaded may result in native call errors. To avoid this scripts should call Router.DoesGameObjectStillExist() before attempting to use any object reference that has been stored for some time.

Unlike the named object itself, a referenced GameObjectID will never be deleted by native code, and may be held by a script indefinitely. It can also be stored directly into a [[Soup]] database for storage and retrieval between runs of the game, over a network, etc. For details about saving a GameObjectID into a Soup database please see the comments in Soup.gs, located in the core Trainz script folder (resources/scripts).

In addition to Soup storage, a GameObjectID can be serialised to a string for *temporary* storage. This allows scripts to do thing like store the ID directly in a trainzhttp link, etc (provided it is also appropriately escaped). However, it is crucial to note that the format of this string is *not* guaranteed and may change between versions of the game. As such, no attempt should be made to machine parse it, save it between runs or send it over a network. To convert the string back into a GameObjectID, use Router.SerialiseGameObjectIDFromString().

It is also safe to cache and store the localised display name for an object, but it is important to remember that objects can be renamed, and that this object name may become out of date at any time. As such, scripts which store it should remember to update their cache whenever an opportunity arises (e.g. during any validation steps).

==Searching for Specific Objects by ID==
Several functions exist for looking up an object which has been saved via it's GameObjectID. Each of these serves a slightly different use-case, so it's important to understand them all before selecting the one that best suits the needs of a specific script.

Two functions exist to retrieve a loaded object via it's ID. These both behave identically, and will return a reference to a matching object *only* if that object exists and is currently loaded. In all other cases the functions will return null. There is no way to determine the cause of a null result using this function.

GameObject objectRef1 = World.GetGameObjectByIDIfLoaded(mySavedID);

GameObject objectRef2 = Router.GetGameObject(mySavedID);

Another function exists to allow scripts to search for objects which are not currently loaded, and to optionally request that they are loaded. Scripts should only request loading of objects when absolutely necessary, and scripts which abuse this feature may have their requests ignored by native code in order to maintain performance. As this function may take a considerable amount of time to run, it uses an AsyncObjectSearchResult, much like the named object list functions described above.

AsyncObjectSearchResult searchObj = World.GetGameObjectByID(mySavedID, false);

As with GetNamedObjectList(), calling scripts must Sniff the returned search object and wait for the appropriate result message(s) to be posted. To avoid the need for frequent code duplication another function also exists which allows threaded objects to perform this functionality in a pseudo-synchronous way.

GameObject loadedObjectRef = World.SynchronouslyLoadGameObjectByID(mySavedID);

This function will throw exceptions if used incorrectly (e.g. if called outside of a thread function) so be sure to read and understand the comments on the function itself, before attempting to use it.

==Script Library Lookups==
Script [[KIND_Library|library assets]] are unique within script in that they exist without any visual presence to the end player, and are shared across all scripts that access them. i.e. It is not possible to instantiate multiple instances of the same library asset within a single script context. This makes them extremely useful for managing, organising or communicating between other scripted asset types. For more information about library assets, see the [[KIND_Library]] page.

As libraries are added to the world by script, and the not the player or session creator, they require a script accessible function to create and load them. This function is TrainzScriptBase.GetLibrary(). When this function is called the library asset will be immediately loaded and returned by Trainz native code. Once loaded, the library will remain loaded in script, and any future calls to GetLibrary() will return the same instance.

Example usage:
public void Init(Asset asset)
{
inherited(asset);

// Load our shared library asset
KUID libraryKuid = asset.LookupKUIDTable("shared-library");
m_sharedLibrary = World.GetLibrary(libraryKuid);

// TODO: Add any library specific init, registration, etc code here
}

==Legacy Search Functions==
Prior to trainz-build 4.5 (TANE SP1 and earlier) all world objects were loaded on Route/Session load, and remained that way until the session was ended. As Routes grow larger and larger this technique becomes unmanageable, and it is thus necessary for Trainz (and it's scripted assets) to support the unloading of objects which are not currently gameplay relevant. As a result of this, numerous script functions have been declared obsolete, as they are incompatible with this concept. Below is a summary of these functions and a mention of their modern replacements.

=====GameObject.GetId()=====
All GameObject instances with a Router are assigned a numeric integer ID. This ID was traditionally retrieved via this function. As the ID varies between runs it was never safe for long term storage, but it was suitable for short term storage and lookup. As objects can now be unloaded at any time, and these IDs then reused by totally different objects, the function has been declared obsolete. Any scripts which use it should be updated to instead use GameObjectID and the related storage functions. See the comments on GameObjectID.gs for more information.

=====GameObject.GetName()=====
In addition to their integer ID certain GameObject types also supported a "script name", which was generally automatically assigned on creation, but could also be edited by the player in some scenarios. Despite the script comments in certain older versions of Trainz, this name was never /guaranteed/ unique, but it was generally considered to be so for ease of use (and that assumption rarely failed). This script name was typically used for object identification in medium to long term storage, including within Soups for session config, savegames, etc. Any scripts which use it should be updated to instead use GameObjectID and the related storage functions. See the comments on GameObjectID.gs for more information.

=====Router.GetGameObject(int)=====
Much like GetGameObject(GameObjectID), this function would return any loaded object with the integer Router ID passed. As this ID format is now considered obsolete, so is this lookup function. Any scripts which use it should be updated to instead use GameObjectID and that function variant (or the async search functions on World). See the comments on GameObjectID.gs for more information.

=====Router.GetGameObject(string)=====
Much like GetGameObject(GameObjectID), this function would return any loaded object with the "script name" string passed. As this ID format is now considered obsolete, so is this lookup function. Any scripts which use it should be updated to instead use GameObjectID and that function variant (or the async search functions on World). See the comments on GameObjectID.gs for more information.

=====World.Get*List()=====
Prior to GetNamedObjectList() multiple functions existed on World to manually retrieve lists of objects of a specific type(e.g. GetIndustryList(), GetTrainList(), etc). These search functions were slow, and scripts would often stall Trainz while the searches were performed. Because of this, and the fact that the functions can now only return those objects that currently loaded, they have been declared obsolete. Any scripts which use them for custom functionality should be updated to instead use World.GetNamedObjectList(). See the comments on this function and the AsyncObjectSearchResult in World.gs for more information on their use. Alternatively, any scripts using them for PropertyObject "list" types may be better served by the new "map-object" type, detailed [[PropertyObject#GetPropertyType|here]].

==See Also==
[[Asynchronous_Route_Streaming| Asynchronous Route Streaming]]

[[Category:How-to_guides|HowTo Guides]]

Class AsyncObjectSearchResult

2020-12-28T20:05:57Z

Danny252: /* Code Examples */ Correct example to wait for AsyncResult, not AsyncLoadComplete

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****[[Class AsyncQueryHelper|AsyncQueryHelper]]
*****[[Class AsyncObjectSearchResult|AsyncObjectSearchResult]]
 

*An AsyncObjectSearchResult represents an asynchronous search of objects in the game world.
*[[HowTo/Search for objects in the world]] provides a detailed tutorial on asynchronous searches.
 

==Related Messages==
*Messages sent to and from TrackMark objects are listed below:
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''||bgcolor="#EEEEEE"|'''Description'''
|-
|ObjectSearch||AsyncResult||AsyncObjectSearchResult||Broadcast||Search is complete, and [[#GetResults|GetResults]] may be called.
|-
|ObjectSearch||AsyncLoadComplete||AsyncObjectSearchResult||Broadcast||Loading of search result has been completed. See [[Class World#GetGameObjectByID|World.GetGameObjectByID()]].
|-
|ObjectSearch||Failure||AsyncObjectSearchResult||Broadcast||Search has failed, call [[#GetSearchErrorCode|GetSearchErrorCode]] for more information.
|-
|ObjectSearch||Expired||AsyncObjectSearchResult||Broadcast||New search results are available, and this result has expired. Not posted by default - see [[Class World#GetNamedObjectList|World.GetNamedObjectList()]].
|}

==Methods==
 
===GetResults===
{{MethodHeader|public native [[Class NamedObjectInfo|NamedObjectInfo]][] GetResults(void)}}
;Parameters
*None
;Returned Value
*Array of search results
;Syntax
NamedObjectInfo[] results = searchObj.GetResults();
for (int i = 0; i < results.size(); ++i) {
NamedObjectInfo result = results[i];
Interface.Log("Result " + i + ": '" + result.localisedUsername + "'");
// Process each result in some useful way...
}
;Notes
*The caller must wait for the search to complete, indicated by the ObjectSearch/AsyncResult message.
*If the search is not complete, calling this method will result in an exception.
 

===GetQueryErrorCode===
{{MethodHeader|public native int GetQueryErrorCode(void)}}
See [[#GetSearchErrorCode|GetSearchErrorCode]]
 

===GetSearchErrorCode===
{{MethodHeader|public native int GetSearchErrorCode(void)}}
;Parameters
*None
;Returned Value
*Error code for the query
;Syntax
wait() {
on "ObjectSearch", "Failure", msg:
if (msg.src == searchObj) {
Interface.Log("Search error " + searchObj.GetSearchErrorCode();
}
}
;Notes
*When a ObjectSearch/Failure message is posted, this method will return an error code.
*Error codes are defined in the ERROR_ constants for [[Class AsyncQueryHelper|AsyncQueryHelper]].
 

==Code Examples==
 
thread void SearchForTrains()
{
// Start a search for any traincars within the world
AsyncObjectSearchResult searchObj = World.GetNamedObjectList(AssetCategory.TrainCar, "");

// Sniff for search related messages, and then wait for either completion or failure
Sniff(searchObj, "ObjectSearch", "", true);
Message msg;
wait()
{
on "ObjectSearch", "Failure", msg:
if (msg.src == searchObj)
break;
continue;

on "ObjectSearch", "AsyncResult", msg:
if (msg.src == searchObj)
break;
continue;
};

// Check the results
int errCode = searchObj.GetSearchErrorCode();
if (errCode != AsyncObjectSearchResult.ERROR_NONE)
{
// TODO: Add any error handling here, such as waiting and reattempting the
// search later, showing an error message, throwing script exceptions, etc.
return;
}

// Get the search results
NamedObjectInfo[] results = searchObj.GetResults();

// TODO: Add any processing of the results here
}

==Related Methods==
*[[Class World#GetGameObjectByID|World.GetGameObjectByID()]]
*[[Class World#GetNamedObjectList|World.GetNamedObjectList()]]
 
 

==Categories==
[[Category:Script Class]]

Class AsyncObjectSearchResult

2020-12-28T19:43:40Z

Danny252: /* Related Messages */ Fix table formatting

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****[[Class AsyncQueryHelper|AsyncQueryHelper]]
*****[[Class AsyncObjectSearchResult|AsyncObjectSearchResult]]
 

*An AsyncObjectSearchResult represents an asynchronous search of objects in the game world.
*[[HowTo/Search for objects in the world]] provides a detailed tutorial on asynchronous searches.
 

==Related Messages==
*Messages sent to and from TrackMark objects are listed below:
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''||bgcolor="#EEEEEE"|'''Description'''
|-
|ObjectSearch||AsyncResult||AsyncObjectSearchResult||Broadcast||Search is complete, and [[#GetResults|GetResults]] may be called.
|-
|ObjectSearch||AsyncLoadComplete||AsyncObjectSearchResult||Broadcast||Loading of search result has been completed. See [[Class World#GetGameObjectByID|World.GetGameObjectByID()]].
|-
|ObjectSearch||Failure||AsyncObjectSearchResult||Broadcast||Search has failed, call [[#GetSearchErrorCode|GetSearchErrorCode]] for more information.
|-
|ObjectSearch||Expired||AsyncObjectSearchResult||Broadcast||New search results are available, and this result has expired. Not posted by default - see [[Class World#GetNamedObjectList|World.GetNamedObjectList()]].
|}

==Methods==
 
===GetResults===
{{MethodHeader|public native [[Class NamedObjectInfo|NamedObjectInfo]][] GetResults(void)}}
;Parameters
*None
;Returned Value
*Array of search results
;Syntax
NamedObjectInfo[] results = searchObj.GetResults();
for (int i = 0; i < results.size(); ++i) {
NamedObjectInfo result = results[i];
Interface.Log("Result " + i + ": '" + result.localisedUsername + "'");
// Process each result in some useful way...
}
;Notes
*The caller must wait for the search to complete, indicated by the ObjectSearch/AsyncResult message.
*If the search is not complete, calling this method will result in an exception.
 

===GetQueryErrorCode===
{{MethodHeader|public native int GetQueryErrorCode(void)}}
See [[#GetSearchErrorCode|GetSearchErrorCode]]
 

===GetSearchErrorCode===
{{MethodHeader|public native int GetSearchErrorCode(void)}}
;Parameters
*None
;Returned Value
*Error code for the query
;Syntax
wait() {
on "ObjectSearch", "Failure", msg:
if (msg.src == searchObj) {
Interface.Log("Search error " + searchObj.GetSearchErrorCode();
}
}
;Notes
*When a ObjectSearch/Failure message is posted, this method will return an error code.
*Error codes are defined in the ERROR_ constants for [[Class AsyncQueryHelper|AsyncQueryHelper]].
 

==Code Examples==
 
thread void SearchForTrains()
{
// Start a search for any traincars within the world
AsyncObjectSearchResult searchObj = World.GetNamedObjectList(AssetCategory.TrainCar, "");

// Sniff for search related messages, and then wait for either completion or failure
Sniff(searchObj, "ObjectSearch", "", true);
Message msg;
wait()
{
on "ObjectSearch", "Failure", msg:
if (msg.src == searchObj)
break;
continue;

on "ObjectSearch", "AsyncLoadComplete", msg:
if (msg.src == searchObj)
break;
continue;
};

// Check the results
int errCode = searchObj.GetSearchErrorCode();
if (errCode != AsyncObjectSearchResult.ERROR_NONE)
{
// TODO: Add any error handling here, such as waiting and reattempting the
// search later, showing an error message, throwing script exceptions, etc.
return;
}

// Get the search results
NamedObjectInfo[] results = searchObj.GetResults();

// TODO: Add any processing of the results here
}

==Related Methods==
*[[Class World#GetGameObjectByID|World.GetGameObjectByID()]]
*[[Class World#GetNamedObjectList|World.GetNamedObjectList()]]
 
 

==Categories==
[[Category:Script Class]]

Class AsyncQueryHelper

2020-12-28T19:43:37Z

Danny252: /* Related Messages */ Fix table formatting

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****[[Class AsyncQueryHelper|AsyncQueryHelper]]
 
AsyncQueryHelper is a generic base class for asynchronous (non-blocking) queries. Most notably, it is inherited by the [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] class.
 

==Constants==
*These constants are used to define various values and can be used as mnenomics.
*If accessed from scripts the values must be prefixed ''AsyncQueryHelper.'', for example:
int errorCode = AsyncQueryHelper.ERROR_INVALID_STATE

 

===Search Errors and Warnings===
----
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int ERROR_NONE = 0 || Query completed without error
|-
|public define int ERROR_FLOOD = 1 || System is flooded, query was not run
|-
|public define int ERROR_INVALID_STATE = 2 || Invalid state for query. This is the initial state of an AsyncQueryHelper object.
|-
|public define int ERROR_NOT_COMPLETE = 3 || Query is still running
|-
|public define int WARN_MORE_RESULTS = 101 || Query aborted early because result limit was hit
|}

===Error and Warning Number Ranges===
----
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WARNINGS_START = 100 || Error codes above 100 are warnings. Code 100 is not a valid result.
|-
|public define int CUSTOM_ERROR_START = 1000 || Extending classes may define custom error codes between 1000 and 2000
|-
|public define int CUSTOM_WARN_START = 2000 || Extending classes may define custom warning codes above 2000
|}

==Related Messages==
*The major parameter of messages may be customised by the inheriting class, via the GetMessageMajor() function, however this should be avoided unless it is absolutely necessary.
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''||bgcolor="#EEEEEE"|'''Description'''
|-
|AsyncQuery||AsyncResult||AsyncObjectSearchResult||Broadcast||Query is complete.
|-
|AsyncQuery||Failure||AsyncObjectSearchResult||Broadcast||Query has failed, call [[#GetQueryErrorCode|GetQueryErrorCode]] for more information.
|}

==Methods==
 

==Related Classes==
*[[Class World|AsyncObjectSearchResult]]
 
 

==Categories==
[[Category:Script Class]]

Class AsyncQueryHelper

2020-12-28T19:42:51Z

Danny252: Add partial docs on AsyncQueryHelper

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****[[Class AsyncQueryHelper|AsyncQueryHelper]]
 
AsyncQueryHelper is a generic base class for asynchronous (non-blocking) queries. Most notably, it is inherited by the [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] class.
 

==Constants==
*These constants are used to define various values and can be used as mnenomics.
*If accessed from scripts the values must be prefixed ''AsyncQueryHelper.'', for example:
int errorCode = AsyncQueryHelper.ERROR_INVALID_STATE

 

===Search Errors and Warnings===
----
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int ERROR_NONE = 0 || Query completed without error
|-
|public define int ERROR_FLOOD = 1 || System is flooded, query was not run
|-
|public define int ERROR_INVALID_STATE = 2 || Invalid state for query. This is the initial state of an AsyncQueryHelper object.
|-
|public define int ERROR_NOT_COMPLETE = 3 || Query is still running
|-
|public define int WARN_MORE_RESULTS = 101 || Query aborted early because result limit was hit
|}

===Error and Warning Number Ranges===
----
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WARNINGS_START = 100 || Error codes above 100 are warnings. Code 100 is not a valid result.
|-
|public define int CUSTOM_ERROR_START = 1000 || Extending classes may define custom error codes between 1000 and 2000
|-
|public define int CUSTOM_WARN_START = 2000 || Extending classes may define custom warning codes above 2000
|}

==Related Messages==
*The major parameter of messages may be customised by the inheriting class, via the GetMessageMajor() function, however this should be avoided unless it is absolutely necessary.
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''|bgcolor="#EEEEEE"|'''Description'''
|-
|AsyncQuery||AsyncResult||AsyncObjectSearchResult||Broadcast||Query is complete.
|-
|AsyncQuery||Failure||AsyncObjectSearchResult||Broadcast||Query has failed, call [[#GetQueryErrorCode|GetQueryErrorCode]] for more information.
|}

==Methods==
 

==Related Classes==
*[[Class World|AsyncObjectSearchResult]]
 
 

==Categories==
[[Category:Script Class]]

Class AsyncObjectSearchResult

2020-12-28T19:42:42Z

Danny252: Add GetQueryErrorCode

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****[[Class AsyncQueryHelper|AsyncQueryHelper]]
*****[[Class AsyncObjectSearchResult|AsyncObjectSearchResult]]
 

*An AsyncObjectSearchResult represents an asynchronous search of objects in the game world.
*[[HowTo/Search for objects in the world]] provides a detailed tutorial on asynchronous searches.
 

==Related Messages==
*Messages sent to and from TrackMark objects are listed below:
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''|bgcolor="#EEEEEE"|'''Description'''
|-
|ObjectSearch||AsyncResult||AsyncObjectSearchResult||Broadcast||Search is complete, and [[#GetResults|GetResults]] may be called.
|-
|ObjectSearch||AsyncLoadComplete||AsyncObjectSearchResult||Broadcast||Loading of search result has been completed. See [[Class World#GetGameObjectByID|World.GetGameObjectByID()]].
|-
|ObjectSearch||Failure||AsyncObjectSearchResult||Broadcast||Search has failed, call [[#GetSearchErrorCode|GetSearchErrorCode]] for more information.
|-
|ObjectSearch||Expired||AsyncObjectSearchResult||Broadcast||New search results are available, and this result has expired. Not posted by default - see [[Class World#GetNamedObjectList|World.GetNamedObjectList()]].
|}

==Methods==
 
===GetResults===
{{MethodHeader|public native [[Class NamedObjectInfo|NamedObjectInfo]][] GetResults(void)}}
;Parameters
*None
;Returned Value
*Array of search results
;Syntax
NamedObjectInfo[] results = searchObj.GetResults();
for (int i = 0; i < results.size(); ++i) {
NamedObjectInfo result = results[i];
Interface.Log("Result " + i + ": '" + result.localisedUsername + "'");
// Process each result in some useful way...
}
;Notes
*The caller must wait for the search to complete, indicated by the ObjectSearch/AsyncResult message.
*If the search is not complete, calling this method will result in an exception.
 

===GetQueryErrorCode===
{{MethodHeader|public native int GetQueryErrorCode(void)}}
See [[#GetSearchErrorCode|GetSearchErrorCode]]
 

===GetSearchErrorCode===
{{MethodHeader|public native int GetSearchErrorCode(void)}}
;Parameters
*None
;Returned Value
*Error code for the query
;Syntax
wait() {
on "ObjectSearch", "Failure", msg:
if (msg.src == searchObj) {
Interface.Log("Search error " + searchObj.GetSearchErrorCode();
}
}
;Notes
*When a ObjectSearch/Failure message is posted, this method will return an error code.
*Error codes are defined in the ERROR_ constants for [[Class AsyncQueryHelper|AsyncQueryHelper]].
 

==Code Examples==
 
thread void SearchForTrains()
{
// Start a search for any traincars within the world
AsyncObjectSearchResult searchObj = World.GetNamedObjectList(AssetCategory.TrainCar, "");

// Sniff for search related messages, and then wait for either completion or failure
Sniff(searchObj, "ObjectSearch", "", true);
Message msg;
wait()
{
on "ObjectSearch", "Failure", msg:
if (msg.src == searchObj)
break;
continue;

on "ObjectSearch", "AsyncLoadComplete", msg:
if (msg.src == searchObj)
break;
continue;
};

// Check the results
int errCode = searchObj.GetSearchErrorCode();
if (errCode != AsyncObjectSearchResult.ERROR_NONE)
{
// TODO: Add any error handling here, such as waiting and reattempting the
// search later, showing an error message, throwing script exceptions, etc.
return;
}

// Get the search results
NamedObjectInfo[] results = searchObj.GetResults();

// TODO: Add any processing of the results here
}

==Related Methods==
*[[Class World#GetGameObjectByID|World.GetGameObjectByID()]]
*[[Class World#GetNamedObjectList|World.GetNamedObjectList()]]
 
 

==Categories==
[[Category:Script Class]]

Class AsyncObjectSearchResult

2020-12-28T19:31:36Z

Danny252: Create AsyncObjectSearchResult

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****[[Class AsyncQueryHelper|AsyncQueryHelper]]
*****[[Class AsyncObjectSearchResult|AsyncObjectSearchResult]]
 

*An AsyncObjectSearchResult represents an asynchronous search of objects in the game world.
*[[HowTo/Search for objects in the world]] provides a detailed tutorial on asynchronous searches.
 

==Related Messages==
*Messages sent to and from TrackMark objects are listed below:
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''|bgcolor="#EEEEEE"|'''Description'''
|-
|ObjectSearch||AsyncResult||AsyncObjectSearchResult||Broadcast||Search is complete, and [[#GetResults|GetResults]] may be called.
|-
|ObjectSearch||AsyncLoadComplete||AsyncObjectSearchResult||Broadcast||Loading of search result has been completed. See [[Class World#GetGameObjectByID|World.GetGameObjectByID()]].
|-
|ObjectSearch||Failure||AsyncObjectSearchResult||Broadcast||Search has failed, call [[#GetSearchErrorCode|GetSearchErrorCode]] for more information.
|-
|ObjectSearch||Expired||AsyncObjectSearchResult||Broadcast||New search results are available, and this result has expired. Not posted by default - see [[Class World#GetNamedObjectList|World.GetNamedObjectList()]].
|}

==Methods==
 
===GetResults===
{{MethodHeader|public native [[Class NamedObjectInfo|NamedObjectInfo]][] GetResults(void)}}
;Parameters
*None
;Returned Value
*Array of search results
;Syntax
NamedObjectInfo[] results = searchObj.GetResults();
for (int i = 0; i < results.size(); ++i) {
NamedObjectInfo result = results[i];
Interface.Log("Result " + i + ": '" + result.localisedUsername + "'");
// Process each result in some useful way...
}
;Notes
*The caller must wait for the search to complete, indicated by the ObjectSearch/AsyncResult message.
*If the search is not complete, calling this method will result in an exception.
 

===GetSearchErrorCode===
{{MethodHeader|public native int GetSearchErrorCode(void)}}
;Parameters
*None
;Returned Value
*Error code for the query
;Syntax
wait() {
on "ObjectSearch", "Failure", msg:
if (msg.src == searchObj) {
Interface.Log("Search error " + searchObj.GetSearchErrorCode();
}
}
;Notes
*When a ObjectSearch/Failure message is posted, this method will return an error code.
*Error codes are defined in the ERROR_ constants for [[Class AsyncQueryHelper|AsyncQueryHelper]].
 

==Code Examples==
 
thread void SearchForTrains()
{
// Start a search for any traincars within the world
AsyncObjectSearchResult searchObj = World.GetNamedObjectList(AssetCategory.TrainCar, "");

// Sniff for search related messages, and then wait for either completion or failure
Sniff(searchObj, "ObjectSearch", "", true);
Message msg;
wait()
{
on "ObjectSearch", "Failure", msg:
if (msg.src == searchObj)
break;
continue;

on "ObjectSearch", "AsyncLoadComplete", msg:
if (msg.src == searchObj)
break;
continue;
};

// Check the results
int errCode = searchObj.GetSearchErrorCode();
if (errCode != AsyncObjectSearchResult.ERROR_NONE)
{
// TODO: Add any error handling here, such as waiting and reattempting the
// search later, showing an error message, throwing script exceptions, etc.
return;
}

// Get the search results
NamedObjectInfo[] results = searchObj.GetResults();

// TODO: Add any processing of the results here
}

==Related Methods==
*[[Class World#GetGameObjectByID|World.GetGameObjectByID()]]
*[[Class World#GetNamedObjectList|World.GetNamedObjectList()]]
 
 

==Categories==
[[Category:Script Class]]

Class NamedObjectInfo

2020-12-28T19:09:23Z

Danny252: Correct class name in text

*[[TrainzScript Library Reference|API Hierarchy]]
**NamedObjectInfo
 

*NamedObjectInfo is a lightweight class containing a result from an asynchronous object search. It defines only four member fields.
*NamedObjectInfo is located in '''asyncobjectsearch.gs'''.
 

==Members==
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public [[Class GameObject|GameObject]] objectRef||A reference to the object, if it's loaded
|-
|public [[Class GameObjectID|GameObjectID]] objectId||The unique ID of the object
|-
|public string localisedUsername||The display name for the object, in the current language
|-
|public string categoryString||The category code string for the object
|}
 

==Related Methods==

* [[Class AsyncObjectSearchResult#GetResults|AsyncObjectSearchResult.GetResults()]]

==Categories==
[[Category:Script Class]]

Class NamedObjectInfo

2020-12-28T19:01:39Z

Danny252: Create NamedObjectInfo

*[[TrainzScript Library Reference|API Hierarchy]]
**NamedObjectInfo
 

*NamedObjectInfo is a lightweight class containing a result from an asynchronous object search. It defines only four member fields.
*TrainUtil is located in '''asyncobjectsearch.gs'''.
 

==Members==
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public [[Class GameObject|GameObject]] objectRef||A reference to the object, if it's loaded
|-
|public [[Class GameObjectID|GameObjectID]] objectId||The unique ID of the object
|-
|public string localisedUsername||The display name for the object, in the current language
|-
|public string categoryString||The category code string for the object
|}
 

==Related Methods==

* [[Class AsyncObjectSearchResult#GetResults|AsyncObjectSearchResult.GetResults()]]

==Categories==
[[Category:Script Class]]

TrainzScript Library Reference

2020-12-28T18:13:35Z

Danny252: AsyncTrainzAssetSearchObject is also a subclass of AsyncQueryHelper

The following is a list of all classes provided by Auran for use with the Trainz game runtime environment. Some of these classes may not be available from other runtime environments. Please see the [[TrainzScript Language Reference]] for a list of the "core" TrainzScript classes that are present in all runtime environments. This list may not be complete, but will be extended in future.

The source code for all classes can be found within your Trainz installation, under ''resources/scripts''. Most classes are contained within obviously named files - e.g. the [[Class World|World]] class can be found in ''world.gs'' - although not all classes are in separate files - [[Class TrainUtil|TrainUtil]] is located in ''common.gs''. Thorough documentation of classes, methods, and constants exists within the source code.

''Classes marked with an asterisk have no parent class.''

*[[class AssetCategory|AssetCategory]] *
*[[class GSObject|GSObject]] *
**[[class Asset|Asset]]
**[[class DLCInfo|DLCInfo]]
**[[class GameObjectID|GameObjectID]]
**[[class GameObject|GameObject]]
***[[class AsyncQueryHelper|AsyncQueryHelper]]
****[[class AsyncObjectSearchResult|AsyncObjectSearchResult]]
****[[class AsyncTrainzAssetSearchObject|AsyncTrainzAssetSearchObject]]
***[[class Browser|Browser]]
***[[class BrowserInterface|BrowserInterface]]
***[[class CabinControl|CabinControl]]
***[[class ConstructorsBase|ConstructorsBase]]
****[[class Constructors|Constructors]]
***[[class DLCStore|DLCStore]]
***[[class DriverCommand|DriverCommand]]
***[[class DriverCommands|DriverCommands]]
***[[class HTMLPropertyHandler|HTMLProprtyHandler]]
***[[class Interface|Interface]]
***[[class InterlockingTowerPath|InterlockingTowerPath]]
***[[class JunctionBaseGameObject|JunctionBaseGameObject]] (Additional parent class: [[class JunctionBase|JunctionBase]] *)
***[[class NavPoints|NavPoints]]
***[[class ChatChannel|ChatChannel]]
***[[class OnlineAccess|OnlineAccess]]
***[[class OnlineGroup|OnlineGroup]]
***[[class Track|Track]]
***[[class TrackCircuitBlock|TrackCircuitBlock]]
***[[class Train|Train]]
***[[class TrainzAssetSearch|TrainzAssetSearch]]
***[[class TrainzGameObject|TrainzGameObject]]
****[[class GameplayMenuBase|GameplayMenuBase]]
*****[[class GameplayMenu|GameplayMenu]]
*****[[class GameplayMenuMobile|GameplayMenuMobile]]
****[[class Library|Library]] (Additional parent class: [[class PropertyObject|PropertyObject]] *)
*****[[class OAChat|OAChat]]
*****[[class Servlet|Servlet]]
*****[[class SessionVariables|SessionVariables]]
*****[[class WaybillManager|WaybillManager]]
****[[class MeshObject|MeshObject]] (Additional parent class: [[class PropertyObject|PropertyObject]] *)
*****[[class Bogey|Bogey]]
*****[[class Cabin|Cabin]]
*****[[class MapObject|MapObject]]
******[[class InterlockingTower|InterlockingTower]]
******[[class SceneryWithTrack|SceneryWithTrack]]
*******[[class Buildable|Buildable]]
********[[class Industry|Industry]]
*********[[class BaseIndustry|BaseIndustry]]
**********[[class GenericPassengerStation|GenericPassengerStation]]
*********[[class BasePortal|BasePortal]]
*********[[class GenericIndustry|GenericIndustry]]
*******[[class Crossing|Crossing]]
*******[[Class_Turntable|TurnTable]]
******[[class Trackside|Trackside]]
*******[[class CarSignal|CarSignal]]
*******[[class Junction|Junction]] (Additional parent class: [[class JunctionBase|JunctionBase]] *)
*******[[class Signal|Signal]]
*******[[class TrackMark|TrackMark]]
*******[[class Trigger|Trigger]]
*******[[class Vehicle|Vehicle]]
********[[class Locomotive|Locomotive]]
****[[class ModulScript|ModulScript]]
*****[[class DriverCharacter|DriverCharacter]]
****[[class ScenarioBehavior|ScenarioBehavior]]
*****[[class ConditionalScenarioBehavior|ConditionalScenarioBehavior]]
*****[[class ScenarioBehaviorTemplate|ScenarioBehaviorTemplate]]
***[[class TrainzScriptBase|TrainzScriptBase]]
****[[class World|World]]
***[[class World1|World1]]
**[[class HTMLBuffer|HTMLBuffer]]
**[[class IndustryTrainController|IndustryTrainController]]
**[[class KUID|KUID]]
**[[class KUIDList|KUIDList]]
**[[class LoadingReport|LoadingReport]]
**[[class Menu|Menu]]
**[[class Permit|Permit]]
**[[class ProductFilter|ProductFilter]]
**[[class ProductQueue|ProductQueue]]
**[[class SecurityToken|SecurityToken]]
**[[class Soup|Soup]]
**[[class StringTable|StringTable]]
**[[class TrackPathDisplay|TrackPathDisplay]]
**[[class TrainTimeTable|TrainTimeTable]]
*[[class GSTrackSearch|GSTrackSearch]] *
*[[class Math|Math]] *
*[[class NamedObjectInfo|NamedObjectInfo]] *
*[[class Router|Router]] *
*[[class Str|Str]] *
*[[class TrainUtil|TrainUtil]] *

=Categories=
[[Category:TrainzScript]]

TrainzScript Library Reference

2020-12-28T18:12:52Z

Danny252: Add NamedObjectInfo, AsyncQueryHelper stubs

The following is a list of all classes provided by Auran for use with the Trainz game runtime environment. Some of these classes may not be available from other runtime environments. Please see the [[TrainzScript Language Reference]] for a list of the "core" TrainzScript classes that are present in all runtime environments. This list may not be complete, but will be extended in future.

The source code for all classes can be found within your Trainz installation, under ''resources/scripts''. Most classes are contained within obviously named files - e.g. the [[Class World|World]] class can be found in ''world.gs'' - although not all classes are in separate files - [[Class TrainUtil|TrainUtil]] is located in ''common.gs''. Thorough documentation of classes, methods, and constants exists within the source code.

''Classes marked with an asterisk have no parent class.''

*[[class AssetCategory|AssetCategory]] *
*[[class GSObject|GSObject]] *
**[[class Asset|Asset]]
**[[class DLCInfo|DLCInfo]]
**[[class GameObjectID|GameObjectID]]
**[[class GameObject|GameObject]]
***[[class AsyncQueryHelper|AsyncQueryHelper]]
****[[class AsyncObjectSearchResult|AsyncObjectSearchResult]]
***[[class AsyncTrainzAssetSearchObject|AsyncTrainzAssetSearchObject]]
***[[class Browser|Browser]]
***[[class BrowserInterface|BrowserInterface]]
***[[class CabinControl|CabinControl]]
***[[class ConstructorsBase|ConstructorsBase]]
****[[class Constructors|Constructors]]
***[[class DLCStore|DLCStore]]
***[[class DriverCommand|DriverCommand]]
***[[class DriverCommands|DriverCommands]]
***[[class HTMLPropertyHandler|HTMLProprtyHandler]]
***[[class Interface|Interface]]
***[[class InterlockingTowerPath|InterlockingTowerPath]]
***[[class JunctionBaseGameObject|JunctionBaseGameObject]] (Additional parent class: [[class JunctionBase|JunctionBase]] *)
***[[class NavPoints|NavPoints]]
***[[class ChatChannel|ChatChannel]]
***[[class OnlineAccess|OnlineAccess]]
***[[class OnlineGroup|OnlineGroup]]
***[[class Track|Track]]
***[[class TrackCircuitBlock|TrackCircuitBlock]]
***[[class Train|Train]]
***[[class TrainzAssetSearch|TrainzAssetSearch]]
***[[class TrainzGameObject|TrainzGameObject]]
****[[class GameplayMenuBase|GameplayMenuBase]]
*****[[class GameplayMenu|GameplayMenu]]
*****[[class GameplayMenuMobile|GameplayMenuMobile]]
****[[class Library|Library]] (Additional parent class: [[class PropertyObject|PropertyObject]] *)
*****[[class OAChat|OAChat]]
*****[[class Servlet|Servlet]]
*****[[class SessionVariables|SessionVariables]]
*****[[class WaybillManager|WaybillManager]]
****[[class MeshObject|MeshObject]] (Additional parent class: [[class PropertyObject|PropertyObject]] *)
*****[[class Bogey|Bogey]]
*****[[class Cabin|Cabin]]
*****[[class MapObject|MapObject]]
******[[class InterlockingTower|InterlockingTower]]
******[[class SceneryWithTrack|SceneryWithTrack]]
*******[[class Buildable|Buildable]]
********[[class Industry|Industry]]
*********[[class BaseIndustry|BaseIndustry]]
**********[[class GenericPassengerStation|GenericPassengerStation]]
*********[[class BasePortal|BasePortal]]
*********[[class GenericIndustry|GenericIndustry]]
*******[[class Crossing|Crossing]]
*******[[Class_Turntable|TurnTable]]
******[[class Trackside|Trackside]]
*******[[class CarSignal|CarSignal]]
*******[[class Junction|Junction]] (Additional parent class: [[class JunctionBase|JunctionBase]] *)
*******[[class Signal|Signal]]
*******[[class TrackMark|TrackMark]]
*******[[class Trigger|Trigger]]
*******[[class Vehicle|Vehicle]]
********[[class Locomotive|Locomotive]]
****[[class ModulScript|ModulScript]]
*****[[class DriverCharacter|DriverCharacter]]
****[[class ScenarioBehavior|ScenarioBehavior]]
*****[[class ConditionalScenarioBehavior|ConditionalScenarioBehavior]]
*****[[class ScenarioBehaviorTemplate|ScenarioBehaviorTemplate]]
***[[class TrainzScriptBase|TrainzScriptBase]]
****[[class World|World]]
***[[class World1|World1]]
**[[class HTMLBuffer|HTMLBuffer]]
**[[class IndustryTrainController|IndustryTrainController]]
**[[class KUID|KUID]]
**[[class KUIDList|KUIDList]]
**[[class LoadingReport|LoadingReport]]
**[[class Menu|Menu]]
**[[class Permit|Permit]]
**[[class ProductFilter|ProductFilter]]
**[[class ProductQueue|ProductQueue]]
**[[class SecurityToken|SecurityToken]]
**[[class Soup|Soup]]
**[[class StringTable|StringTable]]
**[[class TrackPathDisplay|TrackPathDisplay]]
**[[class TrainTimeTable|TrainTimeTable]]
*[[class GSTrackSearch|GSTrackSearch]] *
*[[class Math|Math]] *
*[[class NamedObjectInfo|NamedObjectInfo]] *
*[[class Router|Router]] *
*[[class Str|Str]] *
*[[class TrainUtil|TrainUtil]] *

=Categories=
[[Category:TrainzScript]]

HowTo/Search for objects in the world

2020-12-28T18:07:51Z

Danny252: /* Named Object Searches */ Correct code example - referred to undefined 'asyncSearch' object

Scripted asset may sometimes wish to search for other objects within the world, either in bulk lists, or for a specific single object. This page is intended to provide an overview of how this is achieved in the latest versions of Trainz. Details about certain legacy search methods and the best modern techniques to update them to are also provided in the final section of this page.

==Object Identification==
Scripted objects identified in script using several different methods, many of which have become obsolete as Trainz and the script environment has grown in complexity. As of trainz-build 4.5 (TANE SP2 and later) scripted objects should be identified using their GameObjectID, where present. This ID format has been designed to be future-proof/extensible, should the need arise, and supports various lookup and generic storage functions as per the legacy integer and string based IDs. For more information about legacy ID formats, see [[HowTo/Search_for_objects_in_the_world#Legacy_Search_Functions|here]].

The GameObjectID class is defined within GameObjectID.gs, which can be found in the Trainz core script folder (resources/scripts). For the most up to date and accurate usage instructions please see the comments within that file.

==Named Object Searches==
It is occasionally desirable for scripted assets to be able to search for objects within the world. Most commonly, this is a requirement of session rules, which frequently require a session creator to specify target trains, junctions, signals, etc, in order to perform some gameplay function. Occasionally, placable assets such as industries etc may also require this feature. One such example is the Interlocking Tower asset type, which performs complex management of track blocks using management of user defined signals, junctions and crossings.

As of trainz-build 4.5 (TANE SP2 and later) manual object searches are performed via the World.GetNamedObjectList() function. This function takes both a [[Category_List|category list]] and a partial name, allowing for very specific searches, or quite broad ones. Once called, this function returns an object of type AsyncObjectSearchResult, which is used to monitor for the search completion, and then to retrieve the results. For the most up to date and accurate information on how to use GetNamedObjectList and AsyncObjectSearchResult, please see their script comments. Both are currently defined in World.gs, which can be found in the Trainz core script folder (resources/scripts).

Usage example:

thread void SearchForTrains()
{
// Start a search for any traincars within the world
AsyncObjectSearchResult searchObj = World.GetNamedObjectList(AssetCategory.TrainCar, "");

// Sniff for search related messages, and then wait for either completion or failure
Sniff(searchObj, "ObjectSearch", "", true);
Message msg;
wait()
{
on "ObjectSearch", "Failure", msg:
if (msg.src == searchObj)
break;
continue;

on "ObjectSearch", "AsyncLoadComplete", msg:
if (msg.src == searchObj)
break;
continue;
};

// Check the results
int errCode = searchObj.GetSearchErrorCode();
if (errCode != AsyncObjectSearchResult.ERROR_NONE)
{
// TODO: Add any error handling here, such as waiting and reattempting the
// search later, showing an error message, throwing script exceptions, etc.
return;
}

// Get the search results
NamedObjectInfo[] results = searchObj.GetResults();

// TODO: Add any processing of the results here
}

==Storing References to Specific Objects==
As shown in the example above, named object searches return their results as an array of NamedObjectInfo objects. Currently, this class has 4 member variables:
* objectRef - A reference to the object, if it is currently loaded
* objectId - The GameObjectID for the object (see GameObjectID.gs)
* localisedUsername - The localised name of the object, for displaying to the player
* categoryString - A category string, usable to further determine the exact type and features of the object

Any script which wishes to save a reference to specific named object should /always/ do so via the GameObjectID. This is currently the /only/ safe and reliable way to store and later retrieve a specific object. If the object is currently loaded it is of course also safe to access and store a reference to the object itself, but note that Trainz may choose to unload the object at any time (if it is inactive, and sufficiently far enough away from the player, etc). Attempts to use an object which native code has unloaded may result in native call errors. To avoid this scripts should call Router.DoesGameObjectStillExist() before attempting to use any object reference that has been stored for some time.

Unlike the named object itself, a referenced GameObjectID will never be deleted by native code, and may be held by a script indefinitely. It can also be stored directly into a [[Soup]] database for storage and retrieval between runs of the game, over a network, etc. For details about saving a GameObjectID into a Soup database please see the comments in Soup.gs, located in the core Trainz script folder (resources/scripts).

In addition to Soup storage, a GameObjectID can be serialised to a string for *temporary* storage. This allows scripts to do thing like store the ID directly in a trainzhttp link, etc (provided it is also appropriately escaped). However, it is crucial to note that the format of this string is *not* guaranteed and may change between versions of the game. As such, no attempt should be made to machine parse it, save it between runs or send it over a network. To convert the string back into a GameObjectID, use Router.SerialiseGameObjectIDFromString().

It is also safe to cache and store the localised display name for an object, but it is important to remember that objects can be renamed, and that this object name may become out of date at any time. As such, scripts which store it should remember to update their cache whenever an opportunity arises (e.g. during any validation steps).

==Searching for Specific Objects by ID==
Several functions exist for looking up an object which has been saved via it's GameObjectID. Each of these serves a slightly different use-case, so it's important to understand them all before selecting the one that best suits the needs of a specific script.

Two functions exist to retrieve a loaded object via it's ID. These both behave identically, and will return a reference to a matching object *only* if that object exists and is currently loaded. In all other cases the functions will return null. There is no way to determine the cause of a null result using this function.

GameObject objectRef1 = World.GetGameObjectByIDIfLoaded(mySavedID);

GameObject objectRef2 = Router.GetGameObject(mySavedID);

Another function exists to allow scripts to search for objects which are not currently loaded, and to optionally request that they are loaded. Scripts should only request loading of objects when absolutely necessary, and scripts which abuse this feature may have their requests ignored by native code in order to maintain performance. As this function may take a considerable amount of time to run, it uses an AsyncObjectSearchResult, much like the named object list functions described above.

AsyncObjectSearchResult searchObj = World.GetGameObjectByID(mySavedID, false);

As with GetNamedObjectList(), calling scripts must Sniff the returned search object and wait for the appropriate result message(s) to be posted. To avoid the need for frequent code duplication another function also exists which allows threaded objects to perform this functionality in a pseudo-synchronous way.

GameObject loadedObjectRef = World.SynchronouslyLoadGameObjectByID(mySavedID);

This function will throw exceptions if used incorrectly (e.g. if called outside of a thread function) so be sure to read and understand the comments on the function itself, before attempting to use it.

==Script Library Lookups==
Script [[KIND_Library|library assets]] are unique within script in that they exist without any visual presence to the end player, and are shared across all scripts that access them. i.e. It is not possible to instantiate multiple instances of the same library asset within a single script context. This makes them extremely useful for managing, organising or communicating between other scripted asset types. For more information about library assets, see the [[KIND_Library]] page.

As libraries are added to the world by script, and the not the player or session creator, they require a script accessible function to create and load them. This function is TrainzScriptBase.GetLibrary(). When this function is called the library asset will be immediately loaded and returned by Trainz native code. Once loaded, the library will remain loaded in script, and any future calls to GetLibrary() will return the same instance.

Example usage:
public void Init(Asset asset)
{
inherited(asset);

// Load our shared library asset
KUID libraryKuid = asset.LookupKUIDTable("shared-library");
m_sharedLibrary = World.GetLibrary(libraryKuid);

// TODO: Add any library specific init, registration, etc code here
}

==Legacy Search Functions==
Prior to trainz-build 4.5 (TANE SP1 and earlier) all world objects were loaded on Route/Session load, and remained that way until the session was ended. As Routes grow larger and larger this technique becomes unmanageable, and it is thus necessary for Trainz (and it's scripted assets) to support the unloading of objects which are not currently gameplay relevant. As a result of this, numerous script functions have been declared obsolete, as they are incompatible with this concept. Below is a summary of these functions and a mention of their modern replacements.

=====GameObject.GetId()=====
All GameObject instances with a Router are assigned a numeric integer ID. This ID was traditionally retrieved via this function. As the ID varies between runs it was never safe for long term storage, but it was suitable for short term storage and lookup. As objects can now be unloaded at any time, and these IDs then reused by totally different objects, the function has been declared obsolete. Any scripts which use it should be updated to instead use GameObjectID and the related storage functions. See the comments on GameObjectID.gs for more information.

=====GameObject.GetName()=====
In addition to their integer ID certain GameObject types also supported a "script name", which was generally automatically assigned on creation, but could also be edited by the player in some scenarios. Despite the script comments in certain older versions of Trainz, this name was never /guaranteed/ unique, but it was generally considered to be so for ease of use (and that assumption rarely failed). This script name was typically used for object identification in medium to long term storage, including within Soups for session config, savegames, etc. Any scripts which use it should be updated to instead use GameObjectID and the related storage functions. See the comments on GameObjectID.gs for more information.

=====Router.GetGameObject(int)=====
Much like GetGameObject(GameObjectID), this function would return any loaded object with the integer Router ID passed. As this ID format is now considered obsolete, so is this lookup function. Any scripts which use it should be updated to instead use GameObjectID and that function variant (or the async search functions on World). See the comments on GameObjectID.gs for more information.

=====Router.GetGameObject(string)=====
Much like GetGameObject(GameObjectID), this function would return any loaded object with the "script name" string passed. As this ID format is now considered obsolete, so is this lookup function. Any scripts which use it should be updated to instead use GameObjectID and that function variant (or the async search functions on World). See the comments on GameObjectID.gs for more information.

=====World.Get*List()=====
Prior to GetNamedObjectList() multiple functions existed on World to manually retrieve lists of objects of a specific type(e.g. GetIndustryList(), GetTrainList(), etc). These search functions were slow, and scripts would often stall Trainz while the searches were performed. Because of this, and the fact that the functions can now only return those objects that currently loaded, they have been declared obsolete. Any scripts which use them for custom functionality should be updated to instead use World.GetNamedObjectList(). See the comments on this function and the AsyncObjectSearchResult in World.gs for more information on their use. Alternatively, any scripts using them for PropertyObject "list" types may be better served by the new "map-object" type, detailed [[PropertyObject#GetPropertyType|here]].

==See Also==
[[Asynchronous_Route_Streaming| Asynchronous Route Streaming]]

[[Category:How-to_guides|HowTo Guides]]

Class TrackMark

2020-12-28T17:31:09Z

Danny252: Link to messages documentation

Class TrackMark

2020-12-28T17:29:33Z

Danny252: Fix formatting

Class TrackMark

2020-12-28T17:28:55Z

Danny252: Create TrackMark class docs

Class GSTrackSearch

2020-12-28T17:26:21Z

Danny252: Undo revision 26600 by Danny252 (talk) - Wrong class

*[[TrainzScript Library Reference|API Hierarchy]]
**GSTrackSearch
 

*A class enabling the searching of a length of track for [[class Trackside|Trackside]] items.
*The GSTrackSearch class provides an interface to access certain items along a track in a specified direction from an existing trackside item.
*A GSTrackSearch object can be obtained by calling the [[Class Trackside#BeginTrackSearch|BeginTrackSearch()]] method on the [[class Trackside|Trackside]] item that you want to start your search from.
*The SearchNext() and GetMapObject() methods are provided to get a reference to a discovered [[class Trackside|Trackside]] object.
*The reference returned by these methods can be cast to [[class Trackside|Trackside]] child classes to find out if that item is in fact a [[class Signal|Signal]] or a [[class Junction|Junction]] for instance. As the script code doesn't know what the next item will be, always verify the cast.
*Since [[class Vehicle|Vehicles]] and [[Class Locomotive|Locomotives]] descend from [[class Trackside|Trackside]], searches can be initiated from rolling stock and rolling stock will be returned.
*GSTrackSearch methods will also find [[Class SceneryWithTrack|SceneryWithTrack]] and descendants, although the information which can be obtained from them is limited and these objects cannot be used to initiate a search.
*The search will continue (following the direction set by any junctions) until it is blocked by:
**A junction set against the track
**A turntable.
**A crossing. *** ? "crossing" appears to mean a track (diamond, etc), rather than a road (grade, level) crossing, since the function appears to work properly across road crossings.
**The end of the line.
 
*See [[TrackSearch]] for details of enhancements being developed for future versions of the game.
 

==Trackside.BeginTrackSearch==
{{MethodHeader|public native GSTrackSearch Trackside.BeginTrackSearch(bool direction)}}
*This method is called on objects descending from the [[class Trackside|Trackside]] class to obtain a GSTrackSearch object in the specified search direction.
*See [[Class Trackside#BeginTrackSearch|Trackside.BeginTrackSearch()]] for details.
 

==GetDistance==
{{MethodHeader|public native float GetDistance(void)}}
;Parameters
*None
;Returned Value
*The distance in metres from the origin of the search to the object at which the search cursor is currently pointing.
;Syntax
float distance = gst.GetDistance();
;Notes
*See [[#Code Examples|Code Examples]]
 

==GetFacingRelativeToSearchDirection==
{{MethodHeader|public native bool GetFacingRelativeToSearchDirection(void)}}
;Parameters
*None
;Returned Value
*True if the returned object orientation matches the direction of search, false otherwise.
;Syntax
bool facing = gst.GetFacingRelativeToSearchDirection();
;Notes
*Note that it is the direction of the search that matters, not the facing direction of the search origin.
*A search forwards from a fixed object such as a [[Class Trigger|Trigger]] will return '''true''' for any returned trigger which has the same orientation as the source.
*A search backwards from a fixed object such as a [[Class Trigger|Trigger]] will return '''false''' for any returned trigger which has the same orientation as the source.
 

==GetMapObject==
{{MethodHeader|public native MapObject GetMapObject(void)}}
;Parameters
*None
;Returned Value
*A reference to a MapObject or null if nothing has been found.
;Syntax
MapObject mo = gst.GetMapObject();
;Notes
*MapObject returns Trackside descendants including Vehicles and SceneryWithTrack descendants including Industries.
*Ensure that you attempt a cast to SceneryWithTrack and Trackside if you want the maximum possible amount of information from the search.
 

==SearchNext==
{{MethodHeader|public native MapObject SearchNext(void)}}
;Parameters
*None
;Returned Value
*A reference to a MapObject or null if nothing has been found.
;Syntax
MapObject mo = gst.GetMapObject();
;Notes
*SearchNext moves the search cursor to the next object if such an object exists.
 

==Known Issues==
*GSTrackSearch will return a null reference if it finds certain types of [[Class Crossing|Crossing]] objects, but will continue searching beyond them if asked. As a result of this it is often necessary to make repeated calls to SearchNext following a null return to decide whether you have reached the end of the track or whether your search has simply been interrupted by one or more crossings.
 

==Code Examples==
*This code fragment implements a search forwards from a locomotive. The distance from the locomotive to any discovered object is printed to ''jetlog.txt''
*The process continues until the search returns a null value (which might be a crossing or the end of the track) or the distance from the train exceeds 1km.
GSTrackSearch gst = Loco.BeginTrackSearch(true); // obtain a GSTrackSearch object
MapObject mo = gst.SearchNext(); // initiate the search
while (mo) { // continue as long as objects are present
float distance = gst.GetDistance(); // how far ahead the object is
if (distance > 1000.0) break; // break from the loop if the distance exceeds 1km
Interface.Print("object found at " distance " metres"); // print out the results
mo = gst.SearchNext(); // search for the next object
}
 

==Related Methods==
[[Class Trackside#BeginTrackSearch|Trackside.BeginTrackSearch()]]

==Categories==
[[Category:Script Class]]

Class GSTrackSearch

2020-12-28T17:24:09Z

Danny252: Add full hierarchy

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****[[Class TrainzGameObject|TrainzGameObject]]
****[[Class PropertyObject|PropertyObject]] *
*****[[Class MeshObject|MeshObject]]
******[[Class MapObject|MapObject]]
*******[[Class Trackside|Trackside]]
 

*A class enabling the searching of a length of track for [[class Trackside|Trackside]] items.
*The GSTrackSearch class provides an interface to access certain items along a track in a specified direction from an existing trackside item.
*A GSTrackSearch object can be obtained by calling the [[Class Trackside#BeginTrackSearch|BeginTrackSearch()]] method on the [[class Trackside|Trackside]] item that you want to start your search from.
*The SearchNext() and GetMapObject() methods are provided to get a reference to a discovered [[class Trackside|Trackside]] object.
*The reference returned by these methods can be cast to [[class Trackside|Trackside]] child classes to find out if that item is in fact a [[class Signal|Signal]] or a [[class Junction|Junction]] for instance. As the script code doesn't know what the next item will be, always verify the cast.
*Since [[class Vehicle|Vehicles]] and [[Class Locomotive|Locomotives]] descend from [[class Trackside|Trackside]], searches can be initiated from rolling stock and rolling stock will be returned.
*GSTrackSearch methods will also find [[Class SceneryWithTrack|SceneryWithTrack]] and descendants, although the information which can be obtained from them is limited and these objects cannot be used to initiate a search.
*The search will continue (following the direction set by any junctions) until it is blocked by:
**A junction set against the track
**A turntable.
**A crossing. *** ? "crossing" appears to mean a track (diamond, etc), rather than a road (grade, level) crossing, since the function appears to work properly across road crossings.
**The end of the line.
 
*See [[TrackSearch]] for details of enhancements being developed for future versions of the game.
 

==Trackside.BeginTrackSearch==
{{MethodHeader|public native GSTrackSearch Trackside.BeginTrackSearch(bool direction)}}
*This method is called on objects descending from the [[class Trackside|Trackside]] class to obtain a GSTrackSearch object in the specified search direction.
*See [[Class Trackside#BeginTrackSearch|Trackside.BeginTrackSearch()]] for details.
 

==GetDistance==
{{MethodHeader|public native float GetDistance(void)}}
;Parameters
*None
;Returned Value
*The distance in metres from the origin of the search to the object at which the search cursor is currently pointing.
;Syntax
float distance = gst.GetDistance();
;Notes
*See [[#Code Examples|Code Examples]]
 

==GetFacingRelativeToSearchDirection==
{{MethodHeader|public native bool GetFacingRelativeToSearchDirection(void)}}
;Parameters
*None
;Returned Value
*True if the returned object orientation matches the direction of search, false otherwise.
;Syntax
bool facing = gst.GetFacingRelativeToSearchDirection();
;Notes
*Note that it is the direction of the search that matters, not the facing direction of the search origin.
*A search forwards from a fixed object such as a [[Class Trigger|Trigger]] will return '''true''' for any returned trigger which has the same orientation as the source.
*A search backwards from a fixed object such as a [[Class Trigger|Trigger]] will return '''false''' for any returned trigger which has the same orientation as the source.
 

==GetMapObject==
{{MethodHeader|public native MapObject GetMapObject(void)}}
;Parameters
*None
;Returned Value
*A reference to a MapObject or null if nothing has been found.
;Syntax
MapObject mo = gst.GetMapObject();
;Notes
*MapObject returns Trackside descendants including Vehicles and SceneryWithTrack descendants including Industries.
*Ensure that you attempt a cast to SceneryWithTrack and Trackside if you want the maximum possible amount of information from the search.
 

==SearchNext==
{{MethodHeader|public native MapObject SearchNext(void)}}
;Parameters
*None
;Returned Value
*A reference to a MapObject or null if nothing has been found.
;Syntax
MapObject mo = gst.GetMapObject();
;Notes
*SearchNext moves the search cursor to the next object if such an object exists.
 

==Known Issues==
*GSTrackSearch will return a null reference if it finds certain types of [[Class Crossing|Crossing]] objects, but will continue searching beyond them if asked. As a result of this it is often necessary to make repeated calls to SearchNext following a null return to decide whether you have reached the end of the track or whether your search has simply been interrupted by one or more crossings.
 

==Code Examples==
*This code fragment implements a search forwards from a locomotive. The distance from the locomotive to any discovered object is printed to ''jetlog.txt''
*The process continues until the search returns a null value (which might be a crossing or the end of the track) or the distance from the train exceeds 1km.
GSTrackSearch gst = Loco.BeginTrackSearch(true); // obtain a GSTrackSearch object
MapObject mo = gst.SearchNext(); // initiate the search
while (mo) { // continue as long as objects are present
float distance = gst.GetDistance(); // how far ahead the object is
if (distance > 1000.0) break; // break from the loop if the distance exceeds 1km
Interface.Print("object found at " distance " metres"); // print out the results
mo = gst.SearchNext(); // search for the next object
}
 

==Related Methods==
[[Class Trackside#BeginTrackSearch|Trackside.BeginTrackSearch()]]

==Categories==
[[Category:Script Class]]

Class GSTrackSearch

2020-12-28T17:23:01Z

Danny252: Change link to library reference, not language reference

Class World

2020-12-28T17:21:18Z

Danny252: /* CreateTrain */ Fix formatting

*[[TrainzScript Library Reference|API Hierarchy]]
**World (world.gs)
 
*World is a static class used to access various aspects of the Trainz environment.
 

==Constants==
*These constants are used to define various values and can be used as mnenomics.
*If accessed from scripts the values must be prefixed ''World.'', for example:
World.SetWeather(World.WEATHER_TYPE_LIGHT_SNOW,World.WEATHER_CHANGEABILITY_PERIODIC);
 

===Camera View Modes===
----
*These values can be used either to choose the current camera viewing mode through World.[[#SetCameraMode|SetCameraMode()]], or to restrict certain camera modes from being accessed through methods such as World.[[#SetCamera|SetCamera()]].

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_INTERNAL = 1||Internal cabin camera view.
|-
|public define int CAMERA_EXTERNAL = 2||External train camera view
|-
|public define int CAMERA_TRACKING = 4||External tracking camera view.
|-
|public define int CAMERA_ROAMING = 128||Roaming camera view.
|}
 

===Camera Flags===
----
*These flags are used in addition to the Camera Mode Flags to allow or disallow specific camera actions.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_SWITCH_VIEWS = 8||User permitted to swap between the camera views.
|-
|public define int CAMERA_SWITCH_VEHICLES = 16||User permitted to swap vehicles within the current train.
|-
|public define int CAMERA_SWITCH_TRAINS = 32||User permitted to swap to other trains which are in the consist menu.
|-
|public define int CAMERA_LOCKED = 64||User is NOT permitted to adjust camera (i.e. zoom, pan etc.).
|-
|public define int CAMERA_NORMAL = * ||Normal camera mode where everything is permitted.
|-
|colspan=2|* NOTE: CAMERA_NORMAL = CAMERA_INTERNAL | CAMERA_EXTERNAL | CAMERA_TRACKING | CAMERA_SWITCH_VIEWS | CAMERA_SWITCH_VEHICLES | CAMERA_SWITCH_TRAINS
|}
 

===Weather Type Constants===
----
*Define the current state of the weather in Trainz.
*A variety of weather conditions are supported and can be changed by using one of these values with the World.[[#SetWeather|SetWeather()]] method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_TYPE_CLEAR = 0||Clear weather, no clouds, rain or snow.
|-
|public define int WEATHER_TYPE_CLOUDY = 1||Cloudy weather, no rain.
|-
|public define int WEATHER_TYPE_DRIZZLE = 2||Drizzle, light rain.
|-
|public define int WEATHER_TYPE_RAIN = 3||Rainy weather.
|-
|public define int WEATHER_TYPE_STORMY = 4||Stormy weather that includes lightning and thunder.
|-
|public define int WEATHER_TYPE_LIGHT_SNOW = 5||Snowing lightly.
|-
|public define int WEATHER_TYPE_MEDIUM_SNOW = 6||Medium level snow fall.
|-
|public define int WEATHER_TYPE_HEAVY_SNOW = 7||Heavy snow fall.
|}
 

===Weather Changeability Constants===
----
*Define the changeability settings for the weather.
*Weather changeability refers to variability of weather conditions rather than to a specific weather type.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_CHANGEABILITY_NONE = 0||Weather remains static.
|-
|public define int WEATHER_CHANGEABILITY_PERIODIC = 1||Periodic changes in weather.
|-
|public define int WEATHER_CHANGEABILITY_EXTREME = 2||Extreme and frequent changes in weather.
|}
 

===Time Values===
----
*Time constants defined in seconds.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float TIME_SECOND = 1.0f||One second.
|-
|public define float TIME_MINUTE = TIME_SECOND * 60.0f||One minute, 60.0 seconds.
|-
|public define float TIME_HOUR = TIME_MINUTE * 60.0f||One hour, 60.0 minutes, 3600.0 seconds.
|-
|public define float TIME_DAY = TIME_HOUR * 24.0f||One day, 24 hours, 1440.0 minutes, 86400.0 seconds.
|}
 

===Time Rate Constants===
----
*Values that define the time rates relative to normal time.
*These constants can be used to set the time rate that Trainz runs out through the World.[[#SetGameTimeRate|SetGameTimeRate()]] method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int TIME_RATE_1X = 0||Real time (i.e. time in Trainz passes at the same rate as in the real world)
|-
|public define int TIME_RATE_2X = 1||Time passes at twice normal speed.
|-
|public define int TIME_RATE_4X = 2||
|-
|public define int TIME_RATE_8X = 3||
|-
|public define int TIME_RATE_16X = 4||
|-
|public define int TIME_RATE_32X = 5||
|-
|public define int TIME_RATE_60X = 6||
|-
|public define int TIME_RATE_120X = 7||
|-
|public define int TIME_RATE_240X = 8||
|-
|public define int TIME_RATE_360X = 9||
|-
|public define int TIME_RATE_480X = 10||
|-
|public define int TIME_RATE_720X = 11||
|-
|public define int TIME_RATE_960X = 12||
|-
|public define int TIME_RATE_1200X = 13||
|-
|public define int TIME_RATE_1440X = 14||
|}
 

===Layer Type Constants===
----
*These constants can be used for querying route/session layers via [[#GetLayerList|GetLayerList]] and [[#GetLayerType|GetLayerType]].
*Added in TRS19?
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int LAYER_INVALID = 0||
|-
|public define int LAYER_ROUTE = 1||
|-
|public define int LAYER_SESSION = 2||
|-
|public define int LAYER_BOTH = 3||
|}
 

===World Editing Mode Constants===
----
*These constants can be used to set editing modes through World.[[#SetWorldEditModeEnabled|SetWorldEditModeEnabled()]].
*Added in TRS19?
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int PERMIT_EDIT_NONE = 0x0||
|-
|public define int PERMIT_EDIT_TOPOLOGY = 0x1||
|-
|public define int PERMIT_EDIT_PAINT = 0x2||
|-
|public define int PERMIT_EDIT_SCENERYOBJECTS = 0x4||
|-
|public define int PERMIT_EDIT_SCENERYSPLINES = 0x8||
|-
|public define int PERMIT_EDIT_TRACKSPLINES = 0x10||
|-
|public define int PERMIT_EDIT_TRACKSIDEOBJECTS = 0x20||
|-
|public define int PERMIT_EDIT_TRACKMARKS = 0x40||
|-
|public define int PERMIT_EDIT_TOOLS = 0x80||
|-
|public define int PERMIT_EDIT_WORLD = 0x100||
|-
|public define int PERMIT_EDIT_LAYERS = 0x200||
|-
|public define int PERMIT_EDIT_TRAINS = 0x400||
|-
|public define int PERMIT_EDIT_CONSISTS = 0x800||
|-
|public define int PERMIT_EDIT_ALL = -1||
|}
 

===Trainz Modules===
----
*Trainz module mode constants.
*These values define the various module environments that Trainz can be in.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NO_MODULE = 0||Trainz not running in a module.
|-
|public define int SURVEYOR_MODULE = 1||Trainz is currently running in Surveyor.
|-
|public define int DRIVER_MODULE = 2||Trainz is currently running in Driver.
|}
 

==Related Messages==
* [[TrainzScript Message Reference]] 
* [[Camera Messages]] 
* [[Interface Messages]] 
* [[ModuleInit Message]] 
 

==AddDriverCharacter==
{{MethodHeader|public native [[Class DriverCharacter|DriverCharacter]] AddDriverCharacter([[Class Asset|Asset]] driverCharacterAsset)}}
;Parameters
*'''driverCharacterAsset''' = Asset containing character to be added.
;Returned Value
*Reference to the DriverCharacter if successful, null otherwise.
;Syntax
DriverCharacter Casey = World.AddDriverCharacter(CaseyJones);
;Notes
*In multiplayer, this will only succeed on the server.
 

==AddDriverCommand==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]] AddDriverCommand([[Class Asset|Asset]] driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.AddDriverCommand(accelerate);
;Notes
*In multiplayer, this will only succeed on the server.
 

==CancelCurrentEditingMode==
{{MethodHeader|public native void CancelCurrentEditingMode(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
World.CancelCurrentEditingMode();
;Notes
* Cancels out of any player entered editing mode, if relevant. This should only normally be called as a result of direct player action.
*Added in TRS19?
 

==CreateBehavior==
{{MethodHeader|public native [[Class ScenarioBehavior|ScenarioBehavior]] CreateBehavior([[Class KUID|KUID]] kuid, [[Class Soup|Soup]] initialProperties)}}
;Parameters
*'''kuid''' = KUID of scenario.
'''initialProperties''' = Soup object containing initial properties for scenario.
;Returned Value
*Reference to the ScenarioBehavior created if successful, null otherwise.
;Syntax
ScenarioBehavior scenario = World.CreateBehavior(scenarioAsset, scenarioSoup);
;Notes
*The returned ScenarioBehavior object may be ended by releasing all references to it (resetting all references to null).
 

==CreateTrain==
{{MethodHeader|public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, string trackmarkName, bool direction) public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class TrackMark|TrackMark]] trackmark, bool direction) public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class Buildable|Buildable]] buildable, string trackName, float position, bool direction) public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class GSTrackSearch|GSTrackSearch]] tracksearch, bool avoidDerailments) public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class GSTrackSearch|GSTrackSearch]] tracksearch)}}
;Parameters
*'''consist''' = An array of vehicle KUIDs used to describe the required Train object.
*'''trackmarkName''' = Name of Trackmark at which the consist is to be formed.
*'''buildable''' = Buildable on which the consist is to be formed.
*'''trackName''' = Name of track within Buildable object.
*'''position''' = Distance at which the Train is to be placed relative to the start of the track.
*'''trackmark''' = Reference to Trackmark at which the consist is to be formed.
*'''direction''' = Orientation of Train relative to direction of track or trackmark.
*'''tracksearch''' = The location at which to create the train
*'''avoidDerailments''' = If true this function will fail and return null if creating the train would cause a derailment
;Returned Value
*Reference to the Train created if successful, null otherwise.
;Syntax
Train train = World.CreateTrain(consist, buildable, "Track 1", 10.0, true);
;Notes
*These methods create a train from a list of vehicles in a consist array.
*Depending on the variant of the method used, the train can be created at a Trackmark, specified by name or reference, or at a Buildable or Industry object.
*It is the responsibility of the script programmer to ensure that sufficient track exists at the given location to allow the train to be created.
*In multiplayer, this will only succeed on the server.
*'''GSTrackSearch''' aliases added in TRS19?
 

==DeleteTrain==
{{MethodHeader|public native void DeleteTrain([[Class Train|Train]] train)}}
;Parameters
*'''train''' = train to be deleted from map.
;Returned Value
*None
;Syntax
World.DeleteTrain(flyingScotsman);
;Notes
*Once a train has been deleted, care should be taken to avoid using its reference.
*In multiplayer, this will only succeed on the server.
 

==DeleteVehicle==
{{MethodHeader|public native void DeleteVehicle([[Class Vehicle|Vehicle]] vehicle)}}
;Parameters
*'''vehicle''' = vehicle to be deleted from its train.
;Returned Value
*None
;Syntax
World.DeleteVehicle(vehicles[vehicles.size()-1]);
;Notes
*Use [[Class Train#GetVehicles|Train.GetVehicles()]] to obtain an array of vehicles for a given train.
*Use [[Class Vehicle#GetMyTrain|Vehicle.GetMyTrain()]] to obtain a train reference for a given vehicle.
*In multiplayer, this will only succeed on the server.
 

==EndScenario==
{{MethodHeader|public void EndScenario(float time)}}
;Parameters
*'''time''' = Amount of seconds to delay before ending the session
;Returned Value
*None
;Syntax
World.EndScenario(30.0);
;Notes
*In multiplayer, this will only succeed on the server.
 

==FindAsset==
{{MethodHeader|public native [[Class Asset|Asset]] FindAsset([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of Asset to return.
;Returned Value
*Given a valid KUID parameter, this method return an Asset reference if successful, null otherwise.
;Syntax
Asset asset = World.FindAsset(kuid);
;Notes
*See also Asset.FindAsset()
 

==FindDriverCommand==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]] FindDriverCommand([[Class Asset|Asset]] driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.FindDriverCommand(accelerate);
;Notes
 

==GetAssetList==
{{MethodHeader|public native [[Class Asset|Asset]][ ] GetAssetList(string kind)}}
;Parameters
*'''kind''' = String representing the Kind of asset to return.
;Returned Value
*A list of all assets of the given ''kind''
;Syntax
Asset[] Libraries = World.GetAssetList("Library");
;Notes
*All installed assets of the given ''kind'' are returned, irrespective of whether or not they are in use on the current map.
 

==GetBadWeatherFog==
{{MethodHeader|public obsolete native float GetBadWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Bad weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetBadWeatherFog();
;Notes
*Obsolete in TRS19
 

==GetBehaviors==
{{MethodHeader|public native [[Class ScenarioBehavior|ScenarioBehavior]][ ] GetBehaviors(void)}}
;Parameters
*None
;Returned Value
*A list of top-level behaviors or rules on the currently loaded route.
;Syntax
ScenarioBehavior[] rules = World.GetBehaviors();
;Notes
 

==GetCameraPitch==
{{MethodHeader|public native float GetCameraPitch(void)}}
;Parameters
*None
;Returned Value
*Current camera pitch, in radians
;Syntax
float pitch = World.GetCameraPitch();
;Notes
*Added in ...?
 

==GetCameraPositionX==
{{MethodHeader|public obsolete native float GetCameraPositionX(void)}}
;Parameters
*None
;Returned Value
*X Coordinate of the current camera position.
;Syntax
float X = World.GetCameraPositionX();
;Notes
*Obsolete in TRS19
 

==GetCameraPositionY==
{{MethodHeader|public obsolete native float GetCameraPositionY(void)}}
;Parameters
*None
;Returned Value
*Y Coordinate of the current camera position.
;Syntax
float Y = World.GetCameraPositionY();
;Notes
*Obsolete in TRS19
 

==GetCameraPositionZ==
{{MethodHeader|public obsolete native float GetCameraPositionZ(void)}}
;Parameters
*None
;Returned Value
*Z Coordinate of the current camera position.
;Syntax
float Z = World.GetCameraPositionZ();
;Notes
*Obsolete in TRS19
 

==GetCameraYaw==
{{MethodHeader|public native float GetCameraYaw(void)}}
;Parameters
*None
;Returned Value
*Current camera yaw, in radians
;Syntax
float yaw = World.GetCameraYaw();
;Notes
*Added in ...?
 

==GetCameraZoom==
{{MethodHeader|public native float GetCameraZoom(void)}}
;Parameters
*None
;Returned Value
*Current camera zoom, in meters
;Syntax
float zoom= World.GetCameraZoom();
;Notes
*Is this value equivalent to '''radius''' in [[#SetCameraAngle|SetCameraAngle()]]?
*Added in ...?
 

==GetCurrentModule==
{{MethodHeader|public native int GetCurrentModule(void)}}
;Parameters
*None
;Returned Value
*An integer representing the current Trainz module.
;Syntax
int module = World.GetCurrentModule();
;Notes
* See [[#Trainz Modules|Trainz Modules]] for details of the constants associated with this method.
* See [[ModuleInit Message]] for further details.
 

==GetCurrentProfile==
{{MethodHeader|public native [[Class Asset|Asset]] GetCurrentProfile(void)}}
;Parameters
*None
;Returned Value
*The current session asset
;Syntax
Asset currentSession = World.GetCurrentProfile();
;Notes
*Added in ...?
 

==GetCurrentTrain==
{{MethodHeader|public native Train GetCurrentTrain(void)}}
;Parameters
*None
;Returned Value
*The currently focused train
;Syntax
Train myTrain = World.GetCurrentTrain();
;Notes
* The current train is the one currently controlled by the user, which may not be the train the camera is focused on.
*Added in ...?
 

==GetDriverCharacterList==
{{MethodHeader|public native [[Class DriverCharacter|DriverCharacter]][ ] GetDriverCharacterList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCharacter objects installed in the current world.
;Syntax
DriverCharacter[] drivers = World.GetDriverCharacterList();
;Notes
 

==GetDriverCommandList==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]][ ] GetDriverCommandList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCommand objects installed in the current world.
;Syntax
DriverCommand[] commands = World.GetDriverCommandList();
;Notes
 

==GetGameDate==
{{MethodHeader|public native int GetGameDate(void)}}
;Parameters
*None
;Returned value
*Current game day (1 - 31)
;Syntax
int Now = World.GetGameDate();
;Notes
*Added in ...?
 

==GetGameMonth==
{{MethodHeader|public native int GetGameMonth(void)}}
;Parameters
*None
;Returned value
*Current game month (1 - 12)
;Syntax
int Now = World.GetGameMonth();
;Notes
*Added in ...?
 

==GetGameObjectByID==
{{MethodHeader|public native [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetGameObjectByID([[Class GameObjectID|GameObjectID]] objectID, bool bTriggerLoad) public native [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetGameObjectByID([[Class GameObjectID|GameObjectID]] objectID)}}
;Parameters
*'''objectID''' = The ID of the object to find.
*'''bTriggerLoad''' = Optional, defaults to true. Whether to trigger an asynchronous load of any matching object (if it's not loaded already).
;Returned Value
* Asynchronous search result object.
;Syntax
AsyncObjectSearchResult search_result = World.GetGameObjectByID(objectID, true); // Search for and load an object
;Notes
*See [[HowTo/Search for objects in the world]] for a detailed guide on asynchronous searches.
*The retured object is a reference to the in-progress object search.
*When the search completes, a message of type "ObjectSearch","AsyncResult" will be posted to the result object.
*If bTriggerLoad is true, a further message of type "ObjectSearch","AsyncLoadComplete" will be posted when all objects are loaded into memory. This message will still be posted if every object is already loaded.
*Added in TRS19
 

==GetGameObjectByIDIfLoaded==
{{MethodHeader|public native [[Class GameObject|GameObject]] GetGameObjectByIDIfLoaded([[Class GameObjectID|GameObjectID]] objectID)}}
;Parameters
*'''objectID''' = The ID of the boject to find.
;Returned Value
* The object, if it exists and is currently loaded.
;Syntax
GameObject my_object = World.GetGameObjectByID(objectID);
if (my_object Interface.Print("Object exists and is loaded");
;Notes
*Added in TRS19
 

==GetGameSeason==
{{MethodHeader|public native float GetGameSeason(void)}}
;Parameters
*None
;Returned value
*Current game season
;Syntax
float Season = World.GetGameSeason();
;Notes
*The returned time is normalised to a value between 0.0 and 1.0
*0.0 = mid-summer
*0.5 = mid-winter
*Added in ...?
 

==GetGameTime==
{{MethodHeader|public native float GetGameTime(void)}}
;Parameters
*None
;Returned value
*Current game time.
;Syntax
float Now = World.GetGameTime();
;Notes
*The returned time is normalised to a value between 0.0 and 1.0
*0.0 = midday
*0.25 = 6 p.m.
*0.5 = midnight
*0.75 = 6 a.m.
*1.0 = midday again
*Use the [[#Time_Values|Time Value]] constants to convert the normalised values to human readable times.
 

==GetGameYear==
{{MethodHeader|public native int GetGameYear(void)}}
;Parameters
*None
;Returned value
*Current game year.
;Syntax
int Now = World.GetGameYear();
;Notes
*Added in ...?
 

==GetGoodWeatherFog==
{{MethodHeader|public obsolete native float GetGoodWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Good weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetGoodWeatherFog();
;Notes
*Obsolete in TRS19
 

==GetGroundDrawDistance==
{{MethodHeader|public obsolete native float GetGroundDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Ground draw distance in metres.
;Syntax
float dist = World.GetGroundDrawDistance();
;Notes
 

==GetIndustryList==
{{MethodHeader|public obsolete native [[Class GameObject|GameObject]][ ] GetIndustryList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the Industry objects for the current route.
;Syntax
GameObject[] Industries = World.GetIndustryList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetJunctionList==
{{MethodHeader|public obsolete native [[Class Junction|Junction]][ ] GetJunctionList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackside junction objects for the current route.
;Syntax
Junction[] junctions = World.GetJunctionList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
*Junction objects attached to fixed track junctions are not returned by this method.
 

==GetLayerList==
{{MethodHeader|public native string[ ] GetLayerList(int layerType)}}
;Parameters
*layerType = LAYER_ROUTE, LAYER_SESSION, or LAYER_BOTH
;Returned Value
*Array of layer names
;Syntax
string[] routeLayerNames = World.GetLayerList(World.LAYER_ROUTE);
;Notes
*Added in ...?
 

==GetLayerType==
{{MethodHeader|public native int GetLayerType(string layerName)}}
;Parameters
*layerName = The name of the layer
;Returned Value
*LAYER_ROUTE or LAYER_SESSION
;Syntax
int layerType = World.GetLayerType("MyLayer");
;Notes
*Added in ...?
 

==GetLibrary==
{{MethodHeader|public native [[Class Library|Library]] GetLibrary([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of script library asset to load.
;Returned Value
*A reference to the script library asset if successful, null otherwise.
;Syntax
Library codelib = World.GetLibrary(LibraryKUID);
;Notes
*The [[Class Library|Library]] asset is initialised when this method is first called in a session.
*Since only one instance can exist, subsequent calls return a reference to the existing Library object.
*See [[Class Library|Library]] for notes on how to use this method.
 

==GetLocalPlayerName==
{{MethodHeader|public native string GetLocalPlayerName(void)}}
;Parameters
*None
;Returned Value
*The name of the local player
;Syntax
string playerName = World.GetLocalPlayerName();
;Notes
* Gets the name of the local player, as should be used for setting ownership on DriverCharacters, etc.
*Added in .TRS19?
 

==GetNamedObjectList==
{{MethodHeader|public native [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetNamedObjectList(string categoryFilter, string nameFilter, bool bNotifyOfExpiry) public [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetNamedObjectList(string categoryFilter, string nameFilter)}}
;Parameters
*'''categoryFilter''' = A category filter to search for. Optional, provided a nameFilter parameter is provided. A category code reference can be found in [[Class AssetCategory|AssetCategory]].
*'''nameFilter''' = A partial object name to search for. Optional, provided a categoryFilter parameter is provided.
*'''bNotifyOfExpiry''' = Optional, defaults to false. If native code detects that the search results have changed then a message of type "ObjectSearch","Expired" will be posted to the result object, and the calling script can perform a new search if desired
;Returned Value
* Asynchronous search result object.
;Syntax
AsyncObjectSearchResult search_result = World.GetNamedObjectList(AssetCategory.Locomotive, "SD40-2"); // Search for all SD40-2 locomotives in the world
;Notes
*See [[HowTo/Search for objects in the world]] for a detailed guide on asynchronous searches.
*The retured object is a reference to the in-progress object search.
*When the search completes, a message of type "ObjectSearch","AsyncResult" will be posted to the result object.
*With expiration notices are enabled, only one notification of type "ObjectSearch","Expired" will be posted for each search.
*Added in TRS19
 

==GetSceneryDrawDistance==
{{MethodHeader|public obsolete native float GetSceneryDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Undefined.
;Notes
*Included for legacy script compatibility only. Has no effect.
 

==GetSeconds==
{{MethodHeader|public native float GetSeconds(void)}}
;Parameters
*None
;Returned Value
*The current value of a floating point number incrementing once per second in real time.
;Syntax
float start = World.GetSeconds();
// do stuff
float finish = World.GetSeconds();
float period = finish - start;
;Notes
*Each call will return a float value containing the current value of an internal counter.
*Subtracting a later value from a value saved at an earlier call will enable the delay between the two calls to be established.
 

==GetSignalList==
{{MethodHeader|public obsolete native [[Class Signal|Signal]][ ] GetSignalList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the signal objects for the current route.
;Syntax
Signal[] signals = World.GetSignalList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetStringTable==
{{MethodHeader|public native [[Class StringTable|StringTable]] GetStringTable(void)}}
;Parameters
*None
;Returned Value
*The StringTable for the current session.
;Syntax
StringTable data = World.GetStringTable();
;Notes
 

==GetSurveyorSavedConsist==
{{MethodHeader|public obsolete native [[Class Soup|Soup]] GetSurveyorSavedConsist(string name)}}
;Parameters
*'''name''' = Name of the consist to retrieve.
;Returned Value
*Returns a Soup definition of the named consist if it exists, null otherwise.
;Syntax
Soup consist = World.GetSurveyorSavedConsist("Brighton Belle");
;Notes
*Remember that the returned data is in a Soup format, which is not the same thing as a Train.
*[[Class TrainUtil#CreateTrainFromSoup|TrainUtil.CreateTrainFromSoup()]] can be used to create a train from the returned Soup.
*This method only works in Surveyor.
*Obsolete in TRS19.
 

==GetSurveyorSavedConsistList==
{{MethodHeader|public native string[ ] GetSurveyorSavedConsistList()}}
;Parameters
*None
;Returned Value
*An array of names of all the saved consist objects in Surveyor.
;Syntax
string[] consists = World.GetSurveyorSavedConsistList();
;Notes
*This method only works in Surveyor.
*Obsolete in TRS19.
 

==GetTimeElapsed==
{{MethodHeader|public native float GetTimeElapsed(void)}}
;Parameters
*None
;Returned Value
*The number of real-time seconds that have passed since the start of the current session.
;Syntax
float secondsElapsed = World.GetTimeElapsed();
;Notes
*This measure of time stops passing while the game is paused.
*Added in ...?
 

==GetTrackmarkList==
{{MethodHeader|public obsolete native [[Class TrackMark|TrackMark]][ ] GetTrackmarkList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackmark objects for the current route.
;Syntax
Trackmark[] trackmarks = World.GetTrackmarkList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetTrainList==
{{MethodHeader|public obsolete native [[Class Train|Train]][ ] GetTrainList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trains for the current route.
;Syntax
Train[] trains = World.GetTrainList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetTrainzBuild==
{{MethodHeader|public native int GetTrainzBuild(void)}}
;Parameters;
*None
;Returned Value
*Gets the current build number of Trainz.
;Syntax
int build = World.GetTrainzBuild();
;Notes
*The value returned corresponds to the build number you can see in the bottom-right side of the main Trainz menu screen.
 

==GetTrainzVersion==
{{MethodHeader|public native float GetTrainzVersion(void)}}
;Parameters
*None
;Returned Value
*The TRS version number.
;Syntax
float version = World.GetTrainzVersion();
;Notes
*The value returned corresponds to the version number of Content manager (for example 4.6).
 

==GetTriggerList==
{{MethodHeader|public obsolete native [[Class Trigger|Trigger]][ ] GetTriggerList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trigger objects for the current route.
;Syntax
Trigger[] triggers = World.GetTriggerList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
*This method does not return scenery triggers, ie those attached to SceneryWithTrack objects and their descendants.
 

==GetVehicleList==
{{MethodHeader|public obsolete native [[Class Vehicle|Vehicle]][ ] GetVehicleList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the vehicles in the current route.
;Syntax
Vehicle[] vehicles = World.GetVehicleList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetWeatherChangeability==
{{MethodHeader|public native int GetWeatherChangeability(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Weather_Changeability_Constants|Weather Changeability Constants]] denoting the variability of weather conditions.
;Syntax
int variability = World.GetWeatherChangeability();
;Notes
 

==GetWeatherType==
{{MethodHeader|public native int GetWeatherType(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Weather_Type_Constants|Weather Type Constants]] denoting the current weather conditions.
;Syntax
int weather = World.GetWeatherType();
;Notes
 

==IsAssetRestrictionInEffect==
{{MethodHeader|public native bool IsAssetRestrictionInEffect(string)}}
;Parameters
*None
;Returned Value
*Whether this game world has Asset Restrictions.
;Syntax
bool assetRestrictionsExist = World.IsAssetRestrictionInEffect();
;Notes
*Multiplayer Sessions require Asset Restrictions to be in effect to avoid compatibility issues between peers.
*Added in ...?
 

==IsLayerVisible==
{{MethodHeader|public native bool IsLayerVisible(string layerName)}}
;Parameter
*layerName = Name of the layer to check
;Returned Value
*Whether the layer is visible
;Syntax
bool isVisible = World.IsLayerVisible("MyLayer");
;Notes
*Added in ...?
 

==LoadMap==
{{MethodHeader|public native bool LoadMap([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of map to load.
;Returned Value
*True if successful, false otherwise.
;Syntax
if (World.LoadMap(mapKUID) Interface.Print("Map loaded OK");
else Interface.Print("Map load failed");
;Notes
*Use World.[[#FindKUID|FindKUID()]] to find the desired route KUID.
*In multiplayer, this will only succeed on the server.
 

==LoadSession==
{{MethodHeader|public native bool LoadSession([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of session to load.
;Returned Value
*True if successful, false otherwise.
;Syntax
if (World.LoadSession(sessionKUID) Interface.Print("Session loaded OK");
else Interface.Print("Session load failed");
;Notes
*Use World.[[#FindKUID|FindKUID()]] to find the desired session KUID.
*In multiplayer, this will only succeed on the server.
*Added in ...?
 

==Play2DSound==
{{MethodHeader|public float Play2DSound([[Class Asset|Asset]] asset, string wave)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
;Returned Value
* Undefined.
;Syntax
// Play the sound and continues script execution.
World.Play2DSound(soundAsset,"sounds/allaboard.wav");
// Wait until sound has completed before continuing (pre-TS12 only!)
Sleep(World.Play2DSound(soundAsset,"sounds/allaboard.wav"));
;Notes
*Plays a ''.wav" sound file from the given asset's folder.
*The sound is non directional and can be mono or stereo.
*This method does not return after the sound has finished playing, it returns with the length of the sound as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
 

==PlaySound==
{{MethodHeader|public native float PlaySound     ([[Class Asset|Asset]] asset, string wave, float vol, float near, float far, [[Class GameObject|GameObject]] target, string pt)     ([[Class Asset|Asset]] asset, string wave, float vol, float near, float far, [[Class GameObject|GameObject]] target, string pt, bool loop)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
*'''vol''' = Volume level to play the sound at (0 to 1)<- These values taken from TRS2019 world.gs file comments
*'''near''' = Distance from the target asset at which the sound will be played at maximum volume.
*'''far''' = Distance from the target asset at which the sound will become inaudible.
*'''target''' = GameObject to which the sound will be attached if a 3d sound is required, null for 2D.
*'''pt''' = Name of attachment point in the target object if a 3d sound is required, null for 2D.
*'''loop''' = (Optional) If true the sound will loop continuously.
;Returned Value
* Sound length in seconds for Trainz before TS12
* Undefined for TS12 and TANE
;Syntax
// Play the sound and continues script execution.
World.PlaySound(soundAsset,"sounds/allaboard.wav",1.0,10.0,100.0,Station,"a.loudspeaker");
// Wait until sound has completed before continuing (pre-TS12 only!)
Sleep(World.PlaySound(soundAsset,"sounds/allaboard.wav",1000.0,10.0,100.0,Station,"a.loudspeaker");
;Notes
*Plays a ''.wav'' sound file from the given asset's folder.
*If the sound is to be directional a mono sound file is required.
*This method does not return after the sound has finished playing: it returns as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
*If you want to wait for the sound to complete playing before moving on, wrap the PlaySound() call up in a Sleep() call. '''Note!''' This works only in Trainz versions before TS12. For newer versions, TS12 and TANE, you can hard-code the duration of the sound, or store it in the extensions container of the config.txt file.
*The sound volume will be at a maximum for a camera position at or less than the value of the ''near'' parameter and will reduce with distance until the hearing position reaches ''far'', when the sound will be inaudible.
 

==RemoveDriverCharacter==
{{MethodHeader|public native void RemoveDriverCharacter([[Class DriverCharacter|DriverCharacter]] driver)}}
;Parameters
*'''driver''' = DriverCharacter to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCharacter(dave);
;Notes
*In multiplayer, this will only succeed on the server.
 

==RemoveDriverCommand==
{{MethodHeader|public native void RemoveDriverCommand([[Class DriverCommand|DriverCommand]] command)}}
;Parameters
*'''command''' = DriverCommand to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCommand(driverCommand);
;Notes
*In multiplayer, this will only succeed on the server.
 

==RestartSession==
{{MethodHeader|public native bool RestartSession()}}
;Parameters
;Returned Value
*True if successful, false otherwise.
;Syntax
World.RestartSession();
;Notes
*Valid in Driver mode only.
*In multiplayer, this will only succeed on the server.
 

==SetBadWeatherFog==
{{MethodHeader|public obsolete native void SetBadWeatherFog(float distance)}}
;Parameters
*'''distance''' = Bad weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetBadWeatherFog(0.5);
;Notes
*Obsolete in TRS19
 

==SetCamera==
{{MethodHeader|public native bool SetCamera([[Class MapObject|MapObject]] focus) public native void SetCamera([[Class Junction|Junction]] focus) public native void SetCamera([[Class Vehicle|Vehicle]] focus, int cameraMode) public native void SetCamera([[Class Train|Train]] focus, int cameraMode)}}
;Parameters
*'''focus''' = Object on which the camera is to be focused.
*''cameraMode''' = One of the [[#Camera_View_Modes|Camera View Mode]] constants defining the view which should be assigned to the camera.
;Returned Value
*The first variant returns a boolean to indicate success or failure.
*Remaining variants do not return a value
;Syntax
World.SetCamera(train.GetVehicles[0],World.CAMERA_TRACKING); // sets the camera to track the first vehicle in the train.
;Notes
*Junction alias removed in TRS19?
 

==SetCameraAngle==
{{MethodHeader|public void SetCameraAngle(float yaw, float pitch, float radius) public obsolete void SetCameraAngle(int yaw, int pitch, float radius)}}
;Parameters
*'''yaw''' = Camera rotation in radians (float) or degrees (int), 90 is a direct front view.
*'''pitch''' = Camera angle relative to the horizon in radians (float), or degrees (int), 0 is horizontal, 90 points vertically upwards.
*'''radius''' = Distance in metres to the object in focus.
;Returned Value
*None
;Syntax
World.SetCameraAngle(90,0,25); // Sets the camera to a direct frontal view at 25 metres from the currently focused object.
;Notes
*''Radius'' is measured from the object origin point (0,0,0). If there's no target object this will be the distance to the ground.
*Note difference in units of ''yaw'' and ''pitch'' depending in the method signature used.
*The integer version of this method call is obsolete in TRS19.
 

==SetCameraFlags==
{{MethodHeader|public native void SetCameraFlags(int flags)}}
;Parameter
*'''flags''' integer value defining what the user is permitted to do with the game camera.
;Returned Value
*None
;Syntax
// User is permitted to select External or Tracking views only.
World.SetCameraFlags(World.CAMERA_EXTERNAL | World.CAMERA_TRACKING);
;Notes
*Use any combination of [[#Camera_Flags|Camera Flags]] and [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetCameraMode==
{{MethodHeader|public void SetCameraMode(int mode)}}
;Parameter
*'''mode''' = Camera mode to select.
;Returned Value
*None
;Syntax
World.SetCameraMode(World.CAMERA_TRACKING);
;Notes
*Use one of the [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetEditingCamera==
{{MethodHeader|public void SetEditingCamera([[Class GameObject|GameObject]] actor, bool bIsActorEditingCamera)}}
;Parameter
*'''actor''' = The script who is intended to edit the camera position.
*'''bIsActorEditingCamera''' = True to begin editing, or False to end the editing operation.
;Returned Value
*None
;Syntax
World.SetEditingCamera(myScript, true);
;Notes
*Hints to the caching systems that the camera position is in the process of being changed. This may reduce the amount of streaming that will occur until the change is complete.
*This is intended for use-cases where the decision to move the camera happens in advance of the actual call to [[#SetCamera|SetCamera()]] or etc., for example when the new camera target needs to be streamed in first.
*There is no advantage in calling this unless your code then sleeps/waits before undoing the call.
*It is not required to call this before using SetCamera() etc.
*A boolean state is stored per actor; multiple calls to enable editing on a single actor do not need to be matched to multiple calls to disable editing.
*It is counterproductive to call this when transitioning the camera over a short distance (ie. where the source and target locations can see each other). If jumping to a new location, followed by a visual camera transition at the new location, camera editing may be enabled around the target-selection for the jump, and the jump itself, but should be disabled before proceeding with the transition.
*Added in TRS19?
 

==SetGameDate==
{{MethodHeader|public void SetGameTime(int year, int month, int date)}}
;Parameters
*'''year''' = The year to set (1970-2038)
*'''month''' = The month to set (1-12)
*'''day''' = The day to set (1-31)
;Returned Value
*None
;Syntax
World.SetGameTime(2000, 12, 25); // sets date to 25 December 2000
;Notes
*In multiplayer, this will only succeed on the server.
*Added in ...?
 

==SetGameTime==
{{MethodHeader|public void SetGameTime(float time)}}
;Parameters
*'''time''' = new gane time to set.
;Returned Value
*None
;Syntax
World.SetGameTime(0.5); // sets time to midnight
;Notes
*Game time is normalised to a value between 0.0 and 1.0
*0.0 = midday
*0.25 = 6 p.m.
*0.5 = midnight
*0.75 = 6 a.m.
*1.0 = midday again
*Use the [[#Time_Values|Time Value]] constants to convert human readable times to normalised values.
 

==SetGameTimeRate==
{{MethodHeader|public native void SetGameTimeRate(float rate)}}
;Parameters
*'''rate''' = New time rate to set.
;Returned Value
*None
;Syntax
World.SetGameTimeRate(World.TIME_RATE_8X); // sets game time to advance by 8 minutes per minute of real world time.
;Notes
*Use one of the [[#Time_Rate_Constants|Time Rate Constants]] to define the parameter.
*In multiplayer, this will only succeed on the server.
 

==SetGoodWeatherFog==
{{MethodHeader|public obsolete native void SetGoodWeatherFog(float distance)}}
;Parameters
*'''distance''' = Good weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetGoodWeatherFog(0.5);
;Notes
*Obsolete in TRS19
 

==SetGroundDrawDistance==
{{MethodHeader|public obsolete native void SetGroundDrawDistance(float distance)}}
;Parameters
*'''distance''' = Ground draw distance in metres.
;Returned Value
*None
;Syntax
World.SetGroundDrawDistance(1000.0);
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==SetLayerVisible==
{{MethodHeader|public native void IsLayerVisible(string layerName, bool visible)}}
;Parameter
*layerName = Name of the layer to check
*visible = Whether to set the layer visible or not
;Returned Value
*None
;Syntax
World.IsLayerVisible("MyLayer", False);
;Notes
*Show/Hide a route/session layer.
*In multiplayer, this will only succeed on the server.
*Added in ...?
 

==SetSceneryDrawDistance==
{{MethodHeader|public obsolete native void SetSceneryDrawDistance(float distance)}}
;Parameters
*'''distance''' = unused.
;Returned Value
*None
;Notes
* Does nothing. Included for script compatibility only.
 

==SetTargetObserver==
{{MethodHeader|public void SetTargetObserver([[Class GameObject|GameObject]] observer)}}
;Parameters
*'''observer''' = The game object to receive targeting messages.
;Returned Value
*None
;Syntax
SetTargetObserver(self);
;Notes
* It is unlikely a script programmer would ever need to use this method.
* Causes the specified object to receive "Track", "LeftClick" messages when a track is clicked. Causes the specified object to receive "Interface-Event", "Left-Click" messages when a targetable MapObject is clicked. May cause the functionality of a left mouse click to change from what the user is expecting, so should be used with caution. Used in modal scripts to allow the user to indicate a location for train placement, etc. As there is only a single observer at any given time, the script must take care to only call this function when entering placement mode at the user's request.
 

==SetWeather==
{{MethodHeader|public native void SetWeather(int type, int changeability)}}
;Parameters
*'''type''' = Weather conditions as defined by one of the [[#Weather_Type_Constants|Weather Type Constants]].
*'''change''' = Weather variation as defined by one of the [[#Weather_Changeability_Constants|Weather Changeability Constants]].
;Returned Value
*None
;Syntax
World.SetWeather(World.WEATHER_TYPE_HEAVY_SNOW,World.WEATHER_CHANGEABILITY_EXTREME); // April in Paris.
;Notes
 

==SetWorldEditModeEnabled==
{{MethodHeader|public native bool SetWorldEditModeEnabled(int editFlags, bool enable)}}
;Parameters
*'''editFlags''' = Bitmask specifying which modes to alter, see PERMIT_EDIT_*
*''cameraMode''' = Whether to enable or disable the mode
;Returned Value
*Whether the change was completely successful
;Syntax
World.SetWorldEditModeEnabled(World.PERMIT_EDIT_TRAINS | World.PERMIT_EDIT_CONSISTS, True); // Enable player editing of trains and consists
;Notes
*This does not affect scripts which may alter the world, only the availability of the player world editing tools (i.e, the Surveyor tabs).
*Added in TRS19?
 

==SynchronouslyLoadGameObjectByID==
{{MethodHeader|public [[Class GameObject|GameObject]] SynchronouslyLoadGameObjectByID([[Class GameObjectID|GameObjectID]] objectID)}}
;Parameters
*'''objectID''' = The ID of the object to find.
;Returned Value
* The object, if it exists.
;Syntax
GameObject my_object = World.SynchronouslyLoadGameObjectByID(objectID);
if (my_object Interface.Print("Object exists and has been loaded if required");
;Notes
*This function is usable only by script 'thread' functions and will throw an exception if called incorrectly.
*Added in TRS19
 

==UpdatePositionToGroundHeight==
{{MethodHeader|public native bool UpdatePositionToGroundHeight([[Class WorldCoordinate|WorldCoordinate]] position)}}
;Parameters
*'''position''' (in, out) = Position object to update with the ground height at it's location
;Returned Value
* True if the ground position was updated
;Syntax
if (World.UpdatePositionToGroundHeight(position) Interface.Print("Position was updated");
;Notes
*This updates the input ''position'' object with the ground height at that location.
*This process may fail if the ground data at the specified location is not currently loaded.
*Added in TRS19?
 

==UpdatePositionToSurfaceHeight==
{{MethodHeader|public native bool UpdatePositionToSurfaceHeight([[Class WorldCoordinate|WorldCoordinate]] position)}}
;Parameters
*'''position''' (in, out) = Position object to update with the water height at it's location
;Returned Value
* True if the ground position was updated
;Syntax
if (World.UpdatePositionToGroundHeight(position) Interface.Print("Position was updated");
;Notes
*This updates the input ''position'' object with the water height at that location. If no water is present, the position is adjusted to the ground height.
*This process may fail if the ground data at the specified location is not currently loaded.
*Added in TRS19?
 

==UserSetCamera==
{{MethodHeader|public native bool UserSetCamera([[Class GameObject|GameObject]] target)}}
;Parameters
*'''target''' = GameObject to set focus to.
;Returned Value
*True if successful, false otherwise.
;Syntax
World.UserSetCamera(Router,GetGameObject("Junction 5"));
;Notes
 

==UserSetCameraMode==
{{MethodHeader|public native void UserSetCameraMode(int mode)}}
;Parameters
*'''mode''' = One of the [[#Camera_View_Modes|Camera View Modes]]
;Returned Value
*None
;Syntax
World.UserSetCameraMode(World.CAMERA_ROAMING); // switches to roaming view if permitted.
;Notes
*This method respects the current [[#Camera_Flags|Camera Flag]] settings, disallowing any change which the flags do not permit.
 

==UserSetCameraPosition==
{{MethodHeader|public native bool UserSetCamera([[Class WorldCoordinate|WorldCoordinate]] camPos)}}
;Parameters
*'''camPos''' = World coordinates to set camera to
;Returned Value
*True if successful, false otherwise.
;Syntax
World.UserSetCamera(Router,GetGameObject("Junction 5"));
;Notes
* For camera modes which do not need to target specific objects, this allows the camera to be set to an arbitrary world position.
*Added in TRS19?
 

==Categories==
[[Category:Script Class]]

Class TrainUtil

2020-12-28T17:20:50Z

Danny252: /* CreateTrainFromSoup */ Note existence of World.CreateTrain

*[[TrainzScript Library Reference|API Hierarchy]]
**TrainUtil
 

*TrainUtil is a static utility class containing a miscellany of methods.
*TrainUtil is located in '''common.gs'''.
 

==AlreadyThereStr==
{{MethodHeader|public bool AlreadyThereStr(string[ ] target, string search)}}
;Parameters
*'''target''' = Array of strings to search.
*'''search''' = String to look for.
;Returned Value
*Boolean indicating whether or not the string ''search'' exists in the ''target'' array.
;Syntax
string[] target = Str.Tokens("one two three");
bool found = TrainUtil.AlreadyThereStr(target,"four"); // the result will be false
;Notes
*As is usual in Trainzscript string methods the search is case sensitive.
 

==AreInTrain==
{{MethodHeader|public bool AreInTrain([[Class Train|Train]] train, [[Class Vehicle|Vehicle]][ ] vehicles)}}
;Parameters
*'''train''' = Train to search.
*'''vehicles''' = Array of vehicle to look for.
;Returned Value
*True if all of the vehicles in the array are found in the train, false otherwise.
;Syntax
bool allPresent = TrainUtil.AreInTrain(train,vehicles);
;Notes
*See also [[#IsInTrain|IsInTrain()]]
 

==CompareStrLists==
{{MethodHeader|public bool CompareStrLists(string[ ] list1, string[ ] list2)}}
;Parameters
*'''list1,list2''' = String arrays.
;Returned Value
*True if the lists are identical, same strings in each index position, same total count. False otherwise.
;Syntax
bool identical = TrainUtil.CompareStrLists(address1,address2);
;Notes
 

==CreateTrainFromSoup==
{{MethodHeader|public [[Class Train|Train]] CreateTrainFromSoup([[Class Soup|Soup]] trainSoup, string trackmarkName, bool direction)}}
;Parameters
*'''trainSoup''' = Consist definition in the form returned by [[Class World#GetSurveyorSavedConsist|World.GetSurveyorSavedConsist()]].
*'''trackmarkName''' = Name of the trackmark where the train is to be placed.
*'''direction''' = True denotes that the train direction should match that of the trackmark.
;Returned Value
*A reference to the newly created train if successful, null otherwise.
;Syntax
Train train = TrainUtil.CreateTrainFromSoup(BrightonBelle,"Victoria Station",true);
;Notes
*It is the script programmer's responibility to ensure that sufficient track exists.
*See also [[Class World#CreateTrain|World.CreateTrain()]].
 

==DoCoupleUp==
{{MethodHeader|public [[Class Train|Train]] DoCoupleUp([[Class Train|Train]] train, [[Class Train|Train]] coupleTo)}}
*'''train''' = First train.
*'''coupleTo''' = Train to couple with.
;Returned Value
*A reference to the newly extended train.
;Syntax
Train newTrain = TrainUtil.DoCoupleUp(train, newSection);
;Notes
 

==DoDecouple==
{{MethodHeader|public [[Class Train|Train]] DoDecouple([[Class Train|Train]] train, int count)}}
;Parameters
*'''train''' = Train reference.
*'''count''' = Number of wagons to detach from the rear of the train.
;Returned Value
*A reference to the remaining consist (front section) if successful, null otherwise.
;Syntax
train = TrainUtil.DoDecouple(train,4); // drop four cars from the rear of the train, ''train'' will be null if this fails.
;Notes
*It is assumed that the train is stopped and already in position.
*The method will wait for the operation to be completed.
 

==GetAfter==
{{MethodHeader|public string GetAfter(string target, string search)}}
;Parameters
*'''target''' = String to operate on.
*'''search''' = String containing delimiter characters.
;Returned Value
*Substring of ''target'' to the right of the characters in ''search''.
;Syntax
string result = TrainUtil.GetAfter("Afternoon", "er"); // result is "noon"
;Notes
*The method starts at the end of the string and works backwards until any of the characters in ''search'' are encountered.
*Once any character in ''search'' is found the substring after that character is returned.
*If ''search'' is not found the result will be an empty string.
 

==GetUpTo==
{{MethodHeader|public string GetUpTo(string target, string search)}}
;Parameters
*'''target''' = String to operate on.
*'''search''' = String containing delimiter characters.
;Returned Value
*Substring of ''target'' to the left of the characters in ''search''.
;Syntax
string result = TrainUtil.GetUpTo("Before noon"," no"); // result is "Before"
;Notes
*The method starts at the beginning of the string and works forwards until any of the characters in ''search'' are encountered.
*Once any character in ''search'' is found the substring before that character is returned.
*If ''search'' is not found the result will be an empty string.
 

==HasPrefix==
{{MethodHeader|public bool HasPrefix(string target, string prefix)}}
;Parameters
*'''target''' = String to operate on.
*'''prefix''' = String containing prefix to search for.
;Returned Value
*True if ''target'' starts with ''prefix'', false otherwise.
;Syntax
bool IsPrefixed = TrainUtil.HasPrefix("ante","antecedent"); // returns true
;Notes
 

==HasSufix==
{{MethodHeader|public bool HasSufix(string target, string suffix)}}
;Parameters
*'''target''' = String to operate on.
*'''suffix''' = String containing suffix to search for.
;Returned Value
*True if ''target'' ends with ''suffix'', false otherwise.
;Syntax
bool IsSuffixed = TrainUtil.HasSufix("dent","antecedent"); // returns true
;Notes
*This will not work if the method identifier is correctly spelled!
 

==IsInTrain==
{{MethodHeader|public bool IsInTrain([[Class Train|Train]] train, [[Class Vehicle|Vehicle]] vehicle)}}
;Parameters
*'''train''' = Train reference.
*'''vehicle''' = Vehicle reference.
;Returned Value
*True if ''vehicle'' is included in ''train'', false otherwise.
;Syntax
bool brakeVanPresent = TrainUtil.IsInTrain(train,brakeVan);
;Notes
*See also [[#AreInTrain|AreInTrain()]]
 

==IsPartTrainInTrigger==
{{MethodHeader|public bool IsPartTrainInTrigger([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, [[Class Trigger|Trigger]] trigger)}}
;Parameters
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''trigger''' = Reference to the trigger to query.
;Returned Value
*True if any part of the train is in the trigger area, false otherwise.
;Syntax
bool arrived = TrainUtil.IsPartTrainInTrigger(me,train,trigger);
;Notes
 

==IsTrainInTrigger==
{{MethodHeader|public bool IsTrainInTrigger([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, [[Class Trigger|Trigger]] trigger)}}
;Parameters
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''trigger''' = Reference to the trigger to query.
;Returned Value
*True if the train is in the trigger area, false otherwise.
;Syntax
bool arrived = TrainUtil.IsTrainInTrigger(me,train,trigger);
;Notes
 

==RandBool==
{{MethodHeader|public bool RandBool(void)}}
;Parameters
*None
;Returned Value
*True or false at random.
;Syntax
if(TrainUtil.RandBool()) DoItAtRandom();
;Notes
 

==RunTurnTable==
Is this still valid?
{{MethodHeader|public void RunTurnTable([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, string turntable)}}
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''turntable''' = Name of turntable.
;Returned Value
*None
;Syntax
TrainUtil.RunTurnTable(me,train,"Turntabel 1");
;Notes
*???????
 

==StrSubst==
{{MethodHeader|public string StrSubst(string target, string remove, string replace)}}
;Parameters
*'''target''' = String to operate on.
*'''remove''' = Substring to remove.
*'''replace''' = Replacement substring.
;Returned Value
*Returns the string target with ''replace'' substituted for ''remove'', if the method fails an empty string is returned.
;Syntax
string s = "Gnomes are your friends";
s = TrainUtil.StrSubst(s,"friends","enemies"); // returns "Gnomes are your enemies"
;Notes
*''remove'' must exist as a substring of ''target'', otherwise and empty string will be returned.
*''remove'' and ''replace'' do not have to be the same length.
*Only the first instance of ''remove'' will be substituted.
 

==WaitUntilHas==
Is this still valid?
{{MethodHeader|public void WaitUntilHas([[Class Vehicle|Vehicle]] loco, ShuntTrack tracking)}}
;Parameters
*'''loco''' = Consist locomotive.
*'''tracking''' = Tracking array.
;Returned Value
*None
;Syntax

;Notes
*Waits until all of the vehicles tracked by the tracking array are in the train of the given loco.
 

==Related Methods==

==Categories==
[[Category:Script Class]]

TrainzScript Library Reference

2020-12-28T17:19:34Z

Danny252: Note location of Trainz script source code

The following is a list of all classes provided by Auran for use with the Trainz game runtime environment. Some of these classes may not be available from other runtime environments. Please see the [[TrainzScript Language Reference]] for a list of the "core" TrainzScript classes that are present in all runtime environments. This list may not be complete, but will be extended in future.

The source code for all classes can be found within your Trainz installation, under ''resources/scripts''. Most classes are contained within obviously named files - e.g. the [[Class World|World]] class can be found in ''world.gs'' - although not all classes are in separate files - [[Class TrainUtil|TrainUtil]] is located in ''common.gs''. Thorough documentation of classes, methods, and constants exists within the source code.

''Classes marked with an asterisk have no parent class.''

*[[class AssetCategory|AssetCategory]] *
*[[class GSObject|GSObject]] *
**[[class Asset|Asset]]
**[[class DLCInfo|DLCInfo]]
**[[class GameObjectID|GameObjectID]]
**[[class GameObject|GameObject]]
***[[class AsyncObjectSearchResult|AsyncObjectSearchResult]]
***[[class AsyncTrainzAssetSearchObject|AsyncTrainzAssetSearchObject]]
***[[class Browser|Browser]]
***[[class BrowserInterface|BrowserInterface]]
***[[class CabinControl|CabinControl]]
***[[class ConstructorsBase|ConstructorsBase]]
****[[class Constructors|Constructors]]
***[[class DLCStore|DLCStore]]
***[[class DriverCommand|DriverCommand]]
***[[class DriverCommands|DriverCommands]]
***[[class HTMLPropertyHandler|HTMLProprtyHandler]]
***[[class Interface|Interface]]
***[[class InterlockingTowerPath|InterlockingTowerPath]]
***[[class JunctionBaseGameObject|JunctionBaseGameObject]] (Additional parent class: [[class JunctionBase|JunctionBase]] *)
***[[class NavPoints|NavPoints]]
***[[class ChatChannel|ChatChannel]]
***[[class OnlineAccess|OnlineAccess]]
***[[class OnlineGroup|OnlineGroup]]
***[[class Track|Track]]
***[[class TrackCircuitBlock|TrackCircuitBlock]]
***[[class Train|Train]]
***[[class TrainzAssetSearch|TrainzAssetSearch]]
***[[class TrainzGameObject|TrainzGameObject]]
****[[class GameplayMenuBase|GameplayMenuBase]]
*****[[class GameplayMenu|GameplayMenu]]
*****[[class GameplayMenuMobile|GameplayMenuMobile]]
****[[class Library|Library]] (Additional parent class: [[class PropertyObject|PropertyObject]] *)
*****[[class OAChat|OAChat]]
*****[[class Servlet|Servlet]]
*****[[class SessionVariables|SessionVariables]]
*****[[class WaybillManager|WaybillManager]]
****[[class MeshObject|MeshObject]] (Additional parent class: [[class PropertyObject|PropertyObject]] *)
*****[[class Bogey|Bogey]]
*****[[class Cabin|Cabin]]
*****[[class MapObject|MapObject]]
******[[class InterlockingTower|InterlockingTower]]
******[[class SceneryWithTrack|SceneryWithTrack]]
*******[[class Buildable|Buildable]]
********[[class Industry|Industry]]
*********[[class BaseIndustry|BaseIndustry]]
**********[[class GenericPassengerStation|GenericPassengerStation]]
*********[[class BasePortal|BasePortal]]
*********[[class GenericIndustry|GenericIndustry]]
*******[[class Crossing|Crossing]]
*******[[Class_Turntable|TurnTable]]
******[[class Trackside|Trackside]]
*******[[class CarSignal|CarSignal]]
*******[[class Junction|Junction]] (Additional parent class: [[class JunctionBase|JunctionBase]] *)
*******[[class Signal|Signal]]
*******[[class TrackMark|TrackMark]]
*******[[class Trigger|Trigger]]
*******[[class Vehicle|Vehicle]]
********[[class Locomotive|Locomotive]]
****[[class ModulScript|ModulScript]]
*****[[class DriverCharacter|DriverCharacter]]
****[[class ScenarioBehavior|ScenarioBehavior]]
*****[[class ConditionalScenarioBehavior|ConditionalScenarioBehavior]]
*****[[class ScenarioBehaviorTemplate|ScenarioBehaviorTemplate]]
***[[class TrainzScriptBase|TrainzScriptBase]]
****[[class World|World]]
***[[class World1|World1]]
**[[class HTMLBuffer|HTMLBuffer]]
**[[class IndustryTrainController|IndustryTrainController]]
**[[class KUID|KUID]]
**[[class KUIDList|KUIDList]]
**[[class LoadingReport|LoadingReport]]
**[[class Menu|Menu]]
**[[class Permit|Permit]]
**[[class ProductFilter|ProductFilter]]
**[[class ProductQueue|ProductQueue]]
**[[class SecurityToken|SecurityToken]]
**[[class Soup|Soup]]
**[[class StringTable|StringTable]]
**[[class TrackPathDisplay|TrackPathDisplay]]
**[[class TrainTimeTable|TrainTimeTable]]
*[[class GSTrackSearch|GSTrackSearch]] *
*[[class Math|Math]] *
*[[class Router|Router]] *
*[[class Str|Str]] *
*[[class TrainUtil|TrainUtil]] *

=Categories=
[[Category:TrainzScript]]

Class TrainUtil

2020-12-28T17:13:31Z

Danny252: Change link to library reference, not language reference

*[[TrainzScript Library Reference|API Hierarchy]]
**TrainUtil
 

*TrainUtil is a static utility class containing a miscellany of methods.
*TrainUtil is located in '''common.gs'''.
 

==AlreadyThereStr==
{{MethodHeader|public bool AlreadyThereStr(string[ ] target, string search)}}
;Parameters
*'''target''' = Array of strings to search.
*'''search''' = String to look for.
;Returned Value
*Boolean indicating whether or not the string ''search'' exists in the ''target'' array.
;Syntax
string[] target = Str.Tokens("one two three");
bool found = TrainUtil.AlreadyThereStr(target,"four"); // the result will be false
;Notes
*As is usual in Trainzscript string methods the search is case sensitive.
 

==AreInTrain==
{{MethodHeader|public bool AreInTrain([[Class Train|Train]] train, [[Class Vehicle|Vehicle]][ ] vehicles)}}
;Parameters
*'''train''' = Train to search.
*'''vehicles''' = Array of vehicle to look for.
;Returned Value
*True if all of the vehicles in the array are found in the train, false otherwise.
;Syntax
bool allPresent = TrainUtil.AreInTrain(train,vehicles);
;Notes
*See also [[#IsInTrain|IsInTrain()]]
 

==CompareStrLists==
{{MethodHeader|public bool CompareStrLists(string[ ] list1, string[ ] list2)}}
;Parameters
*'''list1,list2''' = String arrays.
;Returned Value
*True if the lists are identical, same strings in each index position, same total count. False otherwise.
;Syntax
bool identical = TrainUtil.CompareStrLists(address1,address2);
;Notes
 

==CreateTrainFromSoup==
{{MethodHeader|public [[Class Train|Train]] CreateTrainFromSoup([[Class Soup|Soup]] trainSoup, string trackmarkName, bool direction)}}
;Parameters
*'''trainSoup''' = Consist definition in the form returned by [[Class World#GetSurveyorSavedConsist|World.GetSurveyorSavedConsist()]].
*'''trackmarkName''' = Name of the trackmark where the train is to be placed.
*'''direction''' = True denotes that the train direction should match that of the trackmark.
;Returned Value
*A reference to the newly created train if successful, null otherwise.
;Syntax
Train train = TrainUtil.CreateTrainFromSoup(BrightonBelle,"Victoria Station",true);
;Notes
*It is the script programmer's responibility to ensure that sufficient track exists.
 

==DoCoupleUp==
{{MethodHeader|public [[Class Train|Train]] DoCoupleUp([[Class Train|Train]] train, [[Class Train|Train]] coupleTo)}}
*'''train''' = First train.
*'''coupleTo''' = Train to couple with.
;Returned Value
*A reference to the newly extended train.
;Syntax
Train newTrain = TrainUtil.DoCoupleUp(train, newSection);
;Notes
 

==DoDecouple==
{{MethodHeader|public [[Class Train|Train]] DoDecouple([[Class Train|Train]] train, int count)}}
;Parameters
*'''train''' = Train reference.
*'''count''' = Number of wagons to detach from the rear of the train.
;Returned Value
*A reference to the remaining consist (front section) if successful, null otherwise.
;Syntax
train = TrainUtil.DoDecouple(train,4); // drop four cars from the rear of the train, ''train'' will be null if this fails.
;Notes
*It is assumed that the train is stopped and already in position.
*The method will wait for the operation to be completed.
 

==GetAfter==
{{MethodHeader|public string GetAfter(string target, string search)}}
;Parameters
*'''target''' = String to operate on.
*'''search''' = String containing delimiter characters.
;Returned Value
*Substring of ''target'' to the right of the characters in ''search''.
;Syntax
string result = TrainUtil.GetAfter("Afternoon", "er"); // result is "noon"
;Notes
*The method starts at the end of the string and works backwards until any of the characters in ''search'' are encountered.
*Once any character in ''search'' is found the substring after that character is returned.
*If ''search'' is not found the result will be an empty string.
 

==GetUpTo==
{{MethodHeader|public string GetUpTo(string target, string search)}}
;Parameters
*'''target''' = String to operate on.
*'''search''' = String containing delimiter characters.
;Returned Value
*Substring of ''target'' to the left of the characters in ''search''.
;Syntax
string result = TrainUtil.GetUpTo("Before noon"," no"); // result is "Before"
;Notes
*The method starts at the beginning of the string and works forwards until any of the characters in ''search'' are encountered.
*Once any character in ''search'' is found the substring before that character is returned.
*If ''search'' is not found the result will be an empty string.
 

==HasPrefix==
{{MethodHeader|public bool HasPrefix(string target, string prefix)}}
;Parameters
*'''target''' = String to operate on.
*'''prefix''' = String containing prefix to search for.
;Returned Value
*True if ''target'' starts with ''prefix'', false otherwise.
;Syntax
bool IsPrefixed = TrainUtil.HasPrefix("ante","antecedent"); // returns true
;Notes
 

==HasSufix==
{{MethodHeader|public bool HasSufix(string target, string suffix)}}
;Parameters
*'''target''' = String to operate on.
*'''suffix''' = String containing suffix to search for.
;Returned Value
*True if ''target'' ends with ''suffix'', false otherwise.
;Syntax
bool IsSuffixed = TrainUtil.HasSufix("dent","antecedent"); // returns true
;Notes
*This will not work if the method identifier is correctly spelled!
 

==IsInTrain==
{{MethodHeader|public bool IsInTrain([[Class Train|Train]] train, [[Class Vehicle|Vehicle]] vehicle)}}
;Parameters
*'''train''' = Train reference.
*'''vehicle''' = Vehicle reference.
;Returned Value
*True if ''vehicle'' is included in ''train'', false otherwise.
;Syntax
bool brakeVanPresent = TrainUtil.IsInTrain(train,brakeVan);
;Notes
*See also [[#AreInTrain|AreInTrain()]]
 

==IsPartTrainInTrigger==
{{MethodHeader|public bool IsPartTrainInTrigger([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, [[Class Trigger|Trigger]] trigger)}}
;Parameters
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''trigger''' = Reference to the trigger to query.
;Returned Value
*True if any part of the train is in the trigger area, false otherwise.
;Syntax
bool arrived = TrainUtil.IsPartTrainInTrigger(me,train,trigger);
;Notes
 

==IsTrainInTrigger==
{{MethodHeader|public bool IsTrainInTrigger([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, [[Class Trigger|Trigger]] trigger)}}
;Parameters
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''trigger''' = Reference to the trigger to query.
;Returned Value
*True if the train is in the trigger area, false otherwise.
;Syntax
bool arrived = TrainUtil.IsTrainInTrigger(me,train,trigger);
;Notes
 

==RandBool==
{{MethodHeader|public bool RandBool(void)}}
;Parameters
*None
;Returned Value
*True or false at random.
;Syntax
if(TrainUtil.RandBool()) DoItAtRandom();
;Notes
 

==RunTurnTable==
Is this still valid?
{{MethodHeader|public void RunTurnTable([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, string turntable)}}
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''turntable''' = Name of turntable.
;Returned Value
*None
;Syntax
TrainUtil.RunTurnTable(me,train,"Turntabel 1");
;Notes
*???????
 

==StrSubst==
{{MethodHeader|public string StrSubst(string target, string remove, string replace)}}
;Parameters
*'''target''' = String to operate on.
*'''remove''' = Substring to remove.
*'''replace''' = Replacement substring.
;Returned Value
*Returns the string target with ''replace'' substituted for ''remove'', if the method fails an empty string is returned.
;Syntax
string s = "Gnomes are your friends";
s = TrainUtil.StrSubst(s,"friends","enemies"); // returns "Gnomes are your enemies"
;Notes
*''remove'' must exist as a substring of ''target'', otherwise and empty string will be returned.
*''remove'' and ''replace'' do not have to be the same length.
*Only the first instance of ''remove'' will be substituted.
 

==WaitUntilHas==
Is this still valid?
{{MethodHeader|public void WaitUntilHas([[Class Vehicle|Vehicle]] loco, ShuntTrack tracking)}}
;Parameters
*'''loco''' = Consist locomotive.
*'''tracking''' = Tracking array.
;Returned Value
*None
;Syntax

;Notes
*Waits until all of the vehicles tracked by the tracking array are in the train of the given loco.
 

==Related Methods==

==Categories==
[[Category:Script Class]]

Class TrainUtil

2020-12-28T17:12:37Z

Danny252: Note where TrainUtil class is defined

*[[TrainzScript Language Reference|API Hierarchy]]
**TrainUtil
 

*TrainUtil is a static utility class containing a miscellany of methods.
*TrainUtil is located in '''common.gs'''.
 

==AlreadyThereStr==
{{MethodHeader|public bool AlreadyThereStr(string[ ] target, string search)}}
;Parameters
*'''target''' = Array of strings to search.
*'''search''' = String to look for.
;Returned Value
*Boolean indicating whether or not the string ''search'' exists in the ''target'' array.
;Syntax
string[] target = Str.Tokens("one two three");
bool found = TrainUtil.AlreadyThereStr(target,"four"); // the result will be false
;Notes
*As is usual in Trainzscript string methods the search is case sensitive.
 

==AreInTrain==
{{MethodHeader|public bool AreInTrain([[Class Train|Train]] train, [[Class Vehicle|Vehicle]][ ] vehicles)}}
;Parameters
*'''train''' = Train to search.
*'''vehicles''' = Array of vehicle to look for.
;Returned Value
*True if all of the vehicles in the array are found in the train, false otherwise.
;Syntax
bool allPresent = TrainUtil.AreInTrain(train,vehicles);
;Notes
*See also [[#IsInTrain|IsInTrain()]]
 

==CompareStrLists==
{{MethodHeader|public bool CompareStrLists(string[ ] list1, string[ ] list2)}}
;Parameters
*'''list1,list2''' = String arrays.
;Returned Value
*True if the lists are identical, same strings in each index position, same total count. False otherwise.
;Syntax
bool identical = TrainUtil.CompareStrLists(address1,address2);
;Notes
 

==CreateTrainFromSoup==
{{MethodHeader|public [[Class Train|Train]] CreateTrainFromSoup([[Class Soup|Soup]] trainSoup, string trackmarkName, bool direction)}}
;Parameters
*'''trainSoup''' = Consist definition in the form returned by [[Class World#GetSurveyorSavedConsist|World.GetSurveyorSavedConsist()]].
*'''trackmarkName''' = Name of the trackmark where the train is to be placed.
*'''direction''' = True denotes that the train direction should match that of the trackmark.
;Returned Value
*A reference to the newly created train if successful, null otherwise.
;Syntax
Train train = TrainUtil.CreateTrainFromSoup(BrightonBelle,"Victoria Station",true);
;Notes
*It is the script programmer's responibility to ensure that sufficient track exists.
 

==DoCoupleUp==
{{MethodHeader|public [[Class Train|Train]] DoCoupleUp([[Class Train|Train]] train, [[Class Train|Train]] coupleTo)}}
*'''train''' = First train.
*'''coupleTo''' = Train to couple with.
;Returned Value
*A reference to the newly extended train.
;Syntax
Train newTrain = TrainUtil.DoCoupleUp(train, newSection);
;Notes
 

==DoDecouple==
{{MethodHeader|public [[Class Train|Train]] DoDecouple([[Class Train|Train]] train, int count)}}
;Parameters
*'''train''' = Train reference.
*'''count''' = Number of wagons to detach from the rear of the train.
;Returned Value
*A reference to the remaining consist (front section) if successful, null otherwise.
;Syntax
train = TrainUtil.DoDecouple(train,4); // drop four cars from the rear of the train, ''train'' will be null if this fails.
;Notes
*It is assumed that the train is stopped and already in position.
*The method will wait for the operation to be completed.
 

==GetAfter==
{{MethodHeader|public string GetAfter(string target, string search)}}
;Parameters
*'''target''' = String to operate on.
*'''search''' = String containing delimiter characters.
;Returned Value
*Substring of ''target'' to the right of the characters in ''search''.
;Syntax
string result = TrainUtil.GetAfter("Afternoon", "er"); // result is "noon"
;Notes
*The method starts at the end of the string and works backwards until any of the characters in ''search'' are encountered.
*Once any character in ''search'' is found the substring after that character is returned.
*If ''search'' is not found the result will be an empty string.
 

==GetUpTo==
{{MethodHeader|public string GetUpTo(string target, string search)}}
;Parameters
*'''target''' = String to operate on.
*'''search''' = String containing delimiter characters.
;Returned Value
*Substring of ''target'' to the left of the characters in ''search''.
;Syntax
string result = TrainUtil.GetUpTo("Before noon"," no"); // result is "Before"
;Notes
*The method starts at the beginning of the string and works forwards until any of the characters in ''search'' are encountered.
*Once any character in ''search'' is found the substring before that character is returned.
*If ''search'' is not found the result will be an empty string.
 

==HasPrefix==
{{MethodHeader|public bool HasPrefix(string target, string prefix)}}
;Parameters
*'''target''' = String to operate on.
*'''prefix''' = String containing prefix to search for.
;Returned Value
*True if ''target'' starts with ''prefix'', false otherwise.
;Syntax
bool IsPrefixed = TrainUtil.HasPrefix("ante","antecedent"); // returns true
;Notes
 

==HasSufix==
{{MethodHeader|public bool HasSufix(string target, string suffix)}}
;Parameters
*'''target''' = String to operate on.
*'''suffix''' = String containing suffix to search for.
;Returned Value
*True if ''target'' ends with ''suffix'', false otherwise.
;Syntax
bool IsSuffixed = TrainUtil.HasSufix("dent","antecedent"); // returns true
;Notes
*This will not work if the method identifier is correctly spelled!
 

==IsInTrain==
{{MethodHeader|public bool IsInTrain([[Class Train|Train]] train, [[Class Vehicle|Vehicle]] vehicle)}}
;Parameters
*'''train''' = Train reference.
*'''vehicle''' = Vehicle reference.
;Returned Value
*True if ''vehicle'' is included in ''train'', false otherwise.
;Syntax
bool brakeVanPresent = TrainUtil.IsInTrain(train,brakeVan);
;Notes
*See also [[#AreInTrain|AreInTrain()]]
 

==IsPartTrainInTrigger==
{{MethodHeader|public bool IsPartTrainInTrigger([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, [[Class Trigger|Trigger]] trigger)}}
;Parameters
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''trigger''' = Reference to the trigger to query.
;Returned Value
*True if any part of the train is in the trigger area, false otherwise.
;Syntax
bool arrived = TrainUtil.IsPartTrainInTrigger(me,train,trigger);
;Notes
 

==IsTrainInTrigger==
{{MethodHeader|public bool IsTrainInTrigger([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, [[Class Trigger|Trigger]] trigger)}}
;Parameters
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''trigger''' = Reference to the trigger to query.
;Returned Value
*True if the train is in the trigger area, false otherwise.
;Syntax
bool arrived = TrainUtil.IsTrainInTrigger(me,train,trigger);
;Notes
 

==RandBool==
{{MethodHeader|public bool RandBool(void)}}
;Parameters
*None
;Returned Value
*True or false at random.
;Syntax
if(TrainUtil.RandBool()) DoItAtRandom();
;Notes
 

==RunTurnTable==
Is this still valid?
{{MethodHeader|public void RunTurnTable([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, string turntable)}}
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''turntable''' = Name of turntable.
;Returned Value
*None
;Syntax
TrainUtil.RunTurnTable(me,train,"Turntabel 1");
;Notes
*???????
 

==StrSubst==
{{MethodHeader|public string StrSubst(string target, string remove, string replace)}}
;Parameters
*'''target''' = String to operate on.
*'''remove''' = Substring to remove.
*'''replace''' = Replacement substring.
;Returned Value
*Returns the string target with ''replace'' substituted for ''remove'', if the method fails an empty string is returned.
;Syntax
string s = "Gnomes are your friends";
s = TrainUtil.StrSubst(s,"friends","enemies"); // returns "Gnomes are your enemies"
;Notes
*''remove'' must exist as a substring of ''target'', otherwise and empty string will be returned.
*''remove'' and ''replace'' do not have to be the same length.
*Only the first instance of ''remove'' will be substituted.
 

==WaitUntilHas==
Is this still valid?
{{MethodHeader|public void WaitUntilHas([[Class Vehicle|Vehicle]] loco, ShuntTrack tracking)}}
;Parameters
*'''loco''' = Consist locomotive.
*'''tracking''' = Tracking array.
;Returned Value
*None
;Syntax

;Notes
*Waits until all of the vehicles tracked by the tracking array are in the train of the given loco.
 

==Related Methods==

==Categories==
[[Category:Script Class]]

Class World

2020-12-28T17:09:09Z

Danny252: /* GetSurveyorSavedConsist */ Add link to TrainUtil

*[[TrainzScript Library Reference|API Hierarchy]]
**World (world.gs)
 
*World is a static class used to access various aspects of the Trainz environment.
 

==Constants==
*These constants are used to define various values and can be used as mnenomics.
*If accessed from scripts the values must be prefixed ''World.'', for example:
World.SetWeather(World.WEATHER_TYPE_LIGHT_SNOW,World.WEATHER_CHANGEABILITY_PERIODIC);
 

===Camera View Modes===
----
*These values can be used either to choose the current camera viewing mode through World.[[#SetCameraMode|SetCameraMode()]], or to restrict certain camera modes from being accessed through methods such as World.[[#SetCamera|SetCamera()]].

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_INTERNAL = 1||Internal cabin camera view.
|-
|public define int CAMERA_EXTERNAL = 2||External train camera view
|-
|public define int CAMERA_TRACKING = 4||External tracking camera view.
|-
|public define int CAMERA_ROAMING = 128||Roaming camera view.
|}
 

===Camera Flags===
----
*These flags are used in addition to the Camera Mode Flags to allow or disallow specific camera actions.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_SWITCH_VIEWS = 8||User permitted to swap between the camera views.
|-
|public define int CAMERA_SWITCH_VEHICLES = 16||User permitted to swap vehicles within the current train.
|-
|public define int CAMERA_SWITCH_TRAINS = 32||User permitted to swap to other trains which are in the consist menu.
|-
|public define int CAMERA_LOCKED = 64||User is NOT permitted to adjust camera (i.e. zoom, pan etc.).
|-
|public define int CAMERA_NORMAL = * ||Normal camera mode where everything is permitted.
|-
|colspan=2|* NOTE: CAMERA_NORMAL = CAMERA_INTERNAL | CAMERA_EXTERNAL | CAMERA_TRACKING | CAMERA_SWITCH_VIEWS | CAMERA_SWITCH_VEHICLES | CAMERA_SWITCH_TRAINS
|}
 

===Weather Type Constants===
----
*Define the current state of the weather in Trainz.
*A variety of weather conditions are supported and can be changed by using one of these values with the World.[[#SetWeather|SetWeather()]] method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_TYPE_CLEAR = 0||Clear weather, no clouds, rain or snow.
|-
|public define int WEATHER_TYPE_CLOUDY = 1||Cloudy weather, no rain.
|-
|public define int WEATHER_TYPE_DRIZZLE = 2||Drizzle, light rain.
|-
|public define int WEATHER_TYPE_RAIN = 3||Rainy weather.
|-
|public define int WEATHER_TYPE_STORMY = 4||Stormy weather that includes lightning and thunder.
|-
|public define int WEATHER_TYPE_LIGHT_SNOW = 5||Snowing lightly.
|-
|public define int WEATHER_TYPE_MEDIUM_SNOW = 6||Medium level snow fall.
|-
|public define int WEATHER_TYPE_HEAVY_SNOW = 7||Heavy snow fall.
|}
 

===Weather Changeability Constants===
----
*Define the changeability settings for the weather.
*Weather changeability refers to variability of weather conditions rather than to a specific weather type.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_CHANGEABILITY_NONE = 0||Weather remains static.
|-
|public define int WEATHER_CHANGEABILITY_PERIODIC = 1||Periodic changes in weather.
|-
|public define int WEATHER_CHANGEABILITY_EXTREME = 2||Extreme and frequent changes in weather.
|}
 

===Time Values===
----
*Time constants defined in seconds.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float TIME_SECOND = 1.0f||One second.
|-
|public define float TIME_MINUTE = TIME_SECOND * 60.0f||One minute, 60.0 seconds.
|-
|public define float TIME_HOUR = TIME_MINUTE * 60.0f||One hour, 60.0 minutes, 3600.0 seconds.
|-
|public define float TIME_DAY = TIME_HOUR * 24.0f||One day, 24 hours, 1440.0 minutes, 86400.0 seconds.
|}
 

===Time Rate Constants===
----
*Values that define the time rates relative to normal time.
*These constants can be used to set the time rate that Trainz runs out through the World.[[#SetGameTimeRate|SetGameTimeRate()]] method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int TIME_RATE_1X = 0||Real time (i.e. time in Trainz passes at the same rate as in the real world)
|-
|public define int TIME_RATE_2X = 1||Time passes at twice normal speed.
|-
|public define int TIME_RATE_4X = 2||
|-
|public define int TIME_RATE_8X = 3||
|-
|public define int TIME_RATE_16X = 4||
|-
|public define int TIME_RATE_32X = 5||
|-
|public define int TIME_RATE_60X = 6||
|-
|public define int TIME_RATE_120X = 7||
|-
|public define int TIME_RATE_240X = 8||
|-
|public define int TIME_RATE_360X = 9||
|-
|public define int TIME_RATE_480X = 10||
|-
|public define int TIME_RATE_720X = 11||
|-
|public define int TIME_RATE_960X = 12||
|-
|public define int TIME_RATE_1200X = 13||
|-
|public define int TIME_RATE_1440X = 14||
|}
 

===Layer Type Constants===
----
*These constants can be used for querying route/session layers via [[#GetLayerList|GetLayerList]] and [[#GetLayerType|GetLayerType]].
*Added in TRS19?
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int LAYER_INVALID = 0||
|-
|public define int LAYER_ROUTE = 1||
|-
|public define int LAYER_SESSION = 2||
|-
|public define int LAYER_BOTH = 3||
|}
 

===World Editing Mode Constants===
----
*These constants can be used to set editing modes through World.[[#SetWorldEditModeEnabled|SetWorldEditModeEnabled()]].
*Added in TRS19?
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int PERMIT_EDIT_NONE = 0x0||
|-
|public define int PERMIT_EDIT_TOPOLOGY = 0x1||
|-
|public define int PERMIT_EDIT_PAINT = 0x2||
|-
|public define int PERMIT_EDIT_SCENERYOBJECTS = 0x4||
|-
|public define int PERMIT_EDIT_SCENERYSPLINES = 0x8||
|-
|public define int PERMIT_EDIT_TRACKSPLINES = 0x10||
|-
|public define int PERMIT_EDIT_TRACKSIDEOBJECTS = 0x20||
|-
|public define int PERMIT_EDIT_TRACKMARKS = 0x40||
|-
|public define int PERMIT_EDIT_TOOLS = 0x80||
|-
|public define int PERMIT_EDIT_WORLD = 0x100||
|-
|public define int PERMIT_EDIT_LAYERS = 0x200||
|-
|public define int PERMIT_EDIT_TRAINS = 0x400||
|-
|public define int PERMIT_EDIT_CONSISTS = 0x800||
|-
|public define int PERMIT_EDIT_ALL = -1||
|}
 

===Trainz Modules===
----
*Trainz module mode constants.
*These values define the various module environments that Trainz can be in.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NO_MODULE = 0||Trainz not running in a module.
|-
|public define int SURVEYOR_MODULE = 1||Trainz is currently running in Surveyor.
|-
|public define int DRIVER_MODULE = 2||Trainz is currently running in Driver.
|}
 

==Related Messages==
* [[TrainzScript Message Reference]] 
* [[Camera Messages]] 
* [[Interface Messages]] 
* [[ModuleInit Message]] 
 

==AddDriverCharacter==
{{MethodHeader|public native [[Class DriverCharacter|DriverCharacter]] AddDriverCharacter([[Class Asset|Asset]] driverCharacterAsset)}}
;Parameters
*'''driverCharacterAsset''' = Asset containing character to be added.
;Returned Value
*Reference to the DriverCharacter if successful, null otherwise.
;Syntax
DriverCharacter Casey = World.AddDriverCharacter(CaseyJones);
;Notes
*In multiplayer, this will only succeed on the server.
 

==AddDriverCommand==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]] AddDriverCommand([[Class Asset|Asset]] driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.AddDriverCommand(accelerate);
;Notes
*In multiplayer, this will only succeed on the server.
 

==CancelCurrentEditingMode==
{{MethodHeader|public native void CancelCurrentEditingMode(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
World.CancelCurrentEditingMode();
;Notes
* Cancels out of any player entered editing mode, if relevant. This should only normally be called as a result of direct player action.
*Added in TRS19?
 

==CreateBehavior==
{{MethodHeader|public native [[Class ScenarioBehavior|ScenarioBehavior]] CreateBehavior([[Class KUID|KUID]] kuid, [[Class Soup|Soup]] initialProperties)}}
;Parameters
*'''kuid''' = KUID of scenario.
'''initialProperties''' = Soup object containing initial properties for scenario.
;Returned Value
*Reference to the ScenarioBehavior created if successful, null otherwise.
;Syntax
ScenarioBehavior scenario = World.CreateBehavior(scenarioAsset, scenarioSoup);
;Notes
*The returned ScenarioBehavior object may be ended by releasing all references to it (resetting all references to null).
 

==CreateTrain==
{{MethodHeader|public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, string trackmarkName, bool direction) public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class TrackMark|TrackMark]] trackmark, bool direction) public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class Buildable|Buildable]] buildable, string trackName, float position, bool direction)}} public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class GSTrackSearch|GSTrackSearch]] tracksearch, bool avoidDerailments)}} public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class GSTrackSearch|GSTrackSearch]] tracksearch)}}
;Parameters
*'''consist''' = An array of vehicle KUIDs used to describe the required Train object.
*'''trackmarkName''' = Name of Trackmark at which the consist is to be formed.
*'''buildable''' = Buildable on which the consist is to be formed.
*'''trackName''' = Name of track within Buildable object.
*'''position''' = Distance at which the Train is to be placed relative to the start of the track.
*'''trackmark''' = Reference to Trackmark at which the consist is to be formed.
*'''direction''' = Orientation of Train relative to direction of track or trackmark.
*'''tracksearch''' = The location at which to create the train
*'''avoidDerailments''' = If true this function will fail and return null if creating the train would cause a derailment
;Returned Value
*Reference to the Train created if successful, null otherwise.
;Syntax
Train train = World.CreateTrain(consist, buildable, "Track 1", 10.0, true);
;Notes
*These methods create a train from a list of vehicles in a consist array.
*Depending on the variant of the method used, the train can be created at a Trackmark, specified by name or reference, or at a Buildable or Industry object.
*It is the responsibility of the script programmer to ensure that sufficient track exists at the given location to allow the train to be created.
*In multiplayer, this will only succeed on the server.
*'''GSTrackSearch''' aliases added in TRS19?
 

==DeleteTrain==
{{MethodHeader|public native void DeleteTrain([[Class Train|Train]] train)}}
;Parameters
*'''train''' = train to be deleted from map.
;Returned Value
*None
;Syntax
World.DeleteTrain(flyingScotsman);
;Notes
*Once a train has been deleted, care should be taken to avoid using its reference.
*In multiplayer, this will only succeed on the server.
 

==DeleteVehicle==
{{MethodHeader|public native void DeleteVehicle([[Class Vehicle|Vehicle]] vehicle)}}
;Parameters
*'''vehicle''' = vehicle to be deleted from its train.
;Returned Value
*None
;Syntax
World.DeleteVehicle(vehicles[vehicles.size()-1]);
;Notes
*Use [[Class Train#GetVehicles|Train.GetVehicles()]] to obtain an array of vehicles for a given train.
*Use [[Class Vehicle#GetMyTrain|Vehicle.GetMyTrain()]] to obtain a train reference for a given vehicle.
*In multiplayer, this will only succeed on the server.
 

==EndScenario==
{{MethodHeader|public void EndScenario(float time)}}
;Parameters
*'''time''' = Amount of seconds to delay before ending the session
;Returned Value
*None
;Syntax
World.EndScenario(30.0);
;Notes
*In multiplayer, this will only succeed on the server.
 

==FindAsset==
{{MethodHeader|public native [[Class Asset|Asset]] FindAsset([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of Asset to return.
;Returned Value
*Given a valid KUID parameter, this method return an Asset reference if successful, null otherwise.
;Syntax
Asset asset = World.FindAsset(kuid);
;Notes
*See also Asset.FindAsset()
 

==FindDriverCommand==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]] FindDriverCommand([[Class Asset|Asset]] driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.FindDriverCommand(accelerate);
;Notes
 

==GetAssetList==
{{MethodHeader|public native [[Class Asset|Asset]][ ] GetAssetList(string kind)}}
;Parameters
*'''kind''' = String representing the Kind of asset to return.
;Returned Value
*A list of all assets of the given ''kind''
;Syntax
Asset[] Libraries = World.GetAssetList("Library");
;Notes
*All installed assets of the given ''kind'' are returned, irrespective of whether or not they are in use on the current map.
 

==GetBadWeatherFog==
{{MethodHeader|public obsolete native float GetBadWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Bad weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetBadWeatherFog();
;Notes
*Obsolete in TRS19
 

==GetBehaviors==
{{MethodHeader|public native [[Class ScenarioBehavior|ScenarioBehavior]][ ] GetBehaviors(void)}}
;Parameters
*None
;Returned Value
*A list of top-level behaviors or rules on the currently loaded route.
;Syntax
ScenarioBehavior[] rules = World.GetBehaviors();
;Notes
 

==GetCameraPitch==
{{MethodHeader|public native float GetCameraPitch(void)}}
;Parameters
*None
;Returned Value
*Current camera pitch, in radians
;Syntax
float pitch = World.GetCameraPitch();
;Notes
*Added in ...?
 

==GetCameraPositionX==
{{MethodHeader|public obsolete native float GetCameraPositionX(void)}}
;Parameters
*None
;Returned Value
*X Coordinate of the current camera position.
;Syntax
float X = World.GetCameraPositionX();
;Notes
*Obsolete in TRS19
 

==GetCameraPositionY==
{{MethodHeader|public obsolete native float GetCameraPositionY(void)}}
;Parameters
*None
;Returned Value
*Y Coordinate of the current camera position.
;Syntax
float Y = World.GetCameraPositionY();
;Notes
*Obsolete in TRS19
 

==GetCameraPositionZ==
{{MethodHeader|public obsolete native float GetCameraPositionZ(void)}}
;Parameters
*None
;Returned Value
*Z Coordinate of the current camera position.
;Syntax
float Z = World.GetCameraPositionZ();
;Notes
*Obsolete in TRS19
 

==GetCameraYaw==
{{MethodHeader|public native float GetCameraYaw(void)}}
;Parameters
*None
;Returned Value
*Current camera yaw, in radians
;Syntax
float yaw = World.GetCameraYaw();
;Notes
*Added in ...?
 

==GetCameraZoom==
{{MethodHeader|public native float GetCameraZoom(void)}}
;Parameters
*None
;Returned Value
*Current camera zoom, in meters
;Syntax
float zoom= World.GetCameraZoom();
;Notes
*Is this value equivalent to '''radius''' in [[#SetCameraAngle|SetCameraAngle()]]?
*Added in ...?
 

==GetCurrentModule==
{{MethodHeader|public native int GetCurrentModule(void)}}
;Parameters
*None
;Returned Value
*An integer representing the current Trainz module.
;Syntax
int module = World.GetCurrentModule();
;Notes
* See [[#Trainz Modules|Trainz Modules]] for details of the constants associated with this method.
* See [[ModuleInit Message]] for further details.
 

==GetCurrentProfile==
{{MethodHeader|public native [[Class Asset|Asset]] GetCurrentProfile(void)}}
;Parameters
*None
;Returned Value
*The current session asset
;Syntax
Asset currentSession = World.GetCurrentProfile();
;Notes
*Added in ...?
 

==GetCurrentTrain==
{{MethodHeader|public native Train GetCurrentTrain(void)}}
;Parameters
*None
;Returned Value
*The currently focused train
;Syntax
Train myTrain = World.GetCurrentTrain();
;Notes
* The current train is the one currently controlled by the user, which may not be the train the camera is focused on.
*Added in ...?
 

==GetDriverCharacterList==
{{MethodHeader|public native [[Class DriverCharacter|DriverCharacter]][ ] GetDriverCharacterList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCharacter objects installed in the current world.
;Syntax
DriverCharacter[] drivers = World.GetDriverCharacterList();
;Notes
 

==GetDriverCommandList==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]][ ] GetDriverCommandList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCommand objects installed in the current world.
;Syntax
DriverCommand[] commands = World.GetDriverCommandList();
;Notes
 

==GetGameDate==
{{MethodHeader|public native int GetGameDate(void)}}
;Parameters
*None
;Returned value
*Current game day (1 - 31)
;Syntax
int Now = World.GetGameDate();
;Notes
*Added in ...?
 

==GetGameMonth==
{{MethodHeader|public native int GetGameMonth(void)}}
;Parameters
*None
;Returned value
*Current game month (1 - 12)
;Syntax
int Now = World.GetGameMonth();
;Notes
*Added in ...?
 

==GetGameObjectByID==
{{MethodHeader|public native [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetGameObjectByID([[Class GameObjectID|GameObjectID]] objectID, bool bTriggerLoad) public native [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetGameObjectByID([[Class GameObjectID|GameObjectID]] objectID)}}
;Parameters
*'''objectID''' = The ID of the object to find.
*'''bTriggerLoad''' = Optional, defaults to true. Whether to trigger an asynchronous load of any matching object (if it's not loaded already).
;Returned Value
* Asynchronous search result object.
;Syntax
AsyncObjectSearchResult search_result = World.GetGameObjectByID(objectID, true); // Search for and load an object
;Notes
*See [[HowTo/Search for objects in the world]] for a detailed guide on asynchronous searches.
*The retured object is a reference to the in-progress object search.
*When the search completes, a message of type "ObjectSearch","AsyncResult" will be posted to the result object.
*If bTriggerLoad is true, a further message of type "ObjectSearch","AsyncLoadComplete" will be posted when all objects are loaded into memory. This message will still be posted if every object is already loaded.
*Added in TRS19
 

==GetGameObjectByIDIfLoaded==
{{MethodHeader|public native [[Class GameObject|GameObject]] GetGameObjectByIDIfLoaded([[Class GameObjectID|GameObjectID]] objectID)}}
;Parameters
*'''objectID''' = The ID of the boject to find.
;Returned Value
* The object, if it exists and is currently loaded.
;Syntax
GameObject my_object = World.GetGameObjectByID(objectID);
if (my_object Interface.Print("Object exists and is loaded");
;Notes
*Added in TRS19
 

==GetGameSeason==
{{MethodHeader|public native float GetGameSeason(void)}}
;Parameters
*None
;Returned value
*Current game season
;Syntax
float Season = World.GetGameSeason();
;Notes
*The returned time is normalised to a value between 0.0 and 1.0
*0.0 = mid-summer
*0.5 = mid-winter
*Added in ...?
 

==GetGameTime==
{{MethodHeader|public native float GetGameTime(void)}}
;Parameters
*None
;Returned value
*Current game time.
;Syntax
float Now = World.GetGameTime();
;Notes
*The returned time is normalised to a value between 0.0 and 1.0
*0.0 = midday
*0.25 = 6 p.m.
*0.5 = midnight
*0.75 = 6 a.m.
*1.0 = midday again
*Use the [[#Time_Values|Time Value]] constants to convert the normalised values to human readable times.
 

==GetGameYear==
{{MethodHeader|public native int GetGameYear(void)}}
;Parameters
*None
;Returned value
*Current game year.
;Syntax
int Now = World.GetGameYear();
;Notes
*Added in ...?
 

==GetGoodWeatherFog==
{{MethodHeader|public obsolete native float GetGoodWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Good weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetGoodWeatherFog();
;Notes
*Obsolete in TRS19
 

==GetGroundDrawDistance==
{{MethodHeader|public obsolete native float GetGroundDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Ground draw distance in metres.
;Syntax
float dist = World.GetGroundDrawDistance();
;Notes
 

==GetIndustryList==
{{MethodHeader|public obsolete native [[Class GameObject|GameObject]][ ] GetIndustryList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the Industry objects for the current route.
;Syntax
GameObject[] Industries = World.GetIndustryList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetJunctionList==
{{MethodHeader|public obsolete native [[Class Junction|Junction]][ ] GetJunctionList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackside junction objects for the current route.
;Syntax
Junction[] junctions = World.GetJunctionList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
*Junction objects attached to fixed track junctions are not returned by this method.
 

==GetLayerList==
{{MethodHeader|public native string[ ] GetLayerList(int layerType)}}
;Parameters
*layerType = LAYER_ROUTE, LAYER_SESSION, or LAYER_BOTH
;Returned Value
*Array of layer names
;Syntax
string[] routeLayerNames = World.GetLayerList(World.LAYER_ROUTE);
;Notes
*Added in ...?
 

==GetLayerType==
{{MethodHeader|public native int GetLayerType(string layerName)}}
;Parameters
*layerName = The name of the layer
;Returned Value
*LAYER_ROUTE or LAYER_SESSION
;Syntax
int layerType = World.GetLayerType("MyLayer");
;Notes
*Added in ...?
 

==GetLibrary==
{{MethodHeader|public native [[Class Library|Library]] GetLibrary([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of script library asset to load.
;Returned Value
*A reference to the script library asset if successful, null otherwise.
;Syntax
Library codelib = World.GetLibrary(LibraryKUID);
;Notes
*The [[Class Library|Library]] asset is initialised when this method is first called in a session.
*Since only one instance can exist, subsequent calls return a reference to the existing Library object.
*See [[Class Library|Library]] for notes on how to use this method.
 

==GetLocalPlayerName==
{{MethodHeader|public native string GetLocalPlayerName(void)}}
;Parameters
*None
;Returned Value
*The name of the local player
;Syntax
string playerName = World.GetLocalPlayerName();
;Notes
* Gets the name of the local player, as should be used for setting ownership on DriverCharacters, etc.
*Added in .TRS19?
 

==GetNamedObjectList==
{{MethodHeader|public native [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetNamedObjectList(string categoryFilter, string nameFilter, bool bNotifyOfExpiry) public [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetNamedObjectList(string categoryFilter, string nameFilter)}}
;Parameters
*'''categoryFilter''' = A category filter to search for. Optional, provided a nameFilter parameter is provided. A category code reference can be found in [[Class AssetCategory|AssetCategory]].
*'''nameFilter''' = A partial object name to search for. Optional, provided a categoryFilter parameter is provided.
*'''bNotifyOfExpiry''' = Optional, defaults to false. If native code detects that the search results have changed then a message of type "ObjectSearch","Expired" will be posted to the result object, and the calling script can perform a new search if desired
;Returned Value
* Asynchronous search result object.
;Syntax
AsyncObjectSearchResult search_result = World.GetNamedObjectList(AssetCategory.Locomotive, "SD40-2"); // Search for all SD40-2 locomotives in the world
;Notes
*See [[HowTo/Search for objects in the world]] for a detailed guide on asynchronous searches.
*The retured object is a reference to the in-progress object search.
*When the search completes, a message of type "ObjectSearch","AsyncResult" will be posted to the result object.
*With expiration notices are enabled, only one notification of type "ObjectSearch","Expired" will be posted for each search.
*Added in TRS19
 

==GetSceneryDrawDistance==
{{MethodHeader|public obsolete native float GetSceneryDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Undefined.
;Notes
*Included for legacy script compatibility only. Has no effect.
 

==GetSeconds==
{{MethodHeader|public native float GetSeconds(void)}}
;Parameters
*None
;Returned Value
*The current value of a floating point number incrementing once per second in real time.
;Syntax
float start = World.GetSeconds();
// do stuff
float finish = World.GetSeconds();
float period = finish - start;
;Notes
*Each call will return a float value containing the current value of an internal counter.
*Subtracting a later value from a value saved at an earlier call will enable the delay between the two calls to be established.
 

==GetSignalList==
{{MethodHeader|public obsolete native [[Class Signal|Signal]][ ] GetSignalList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the signal objects for the current route.
;Syntax
Signal[] signals = World.GetSignalList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetStringTable==
{{MethodHeader|public native [[Class StringTable|StringTable]] GetStringTable(void)}}
;Parameters
*None
;Returned Value
*The StringTable for the current session.
;Syntax
StringTable data = World.GetStringTable();
;Notes
 

==GetSurveyorSavedConsist==
{{MethodHeader|public obsolete native [[Class Soup|Soup]] GetSurveyorSavedConsist(string name)}}
;Parameters
*'''name''' = Name of the consist to retrieve.
;Returned Value
*Returns a Soup definition of the named consist if it exists, null otherwise.
;Syntax
Soup consist = World.GetSurveyorSavedConsist("Brighton Belle");
;Notes
*Remember that the returned data is in a Soup format, which is not the same thing as a Train.
*[[Class TrainUtil#CreateTrainFromSoup|TrainUtil.CreateTrainFromSoup()]] can be used to create a train from the returned Soup.
*This method only works in Surveyor.
*Obsolete in TRS19.
 

==GetSurveyorSavedConsistList==
{{MethodHeader|public native string[ ] GetSurveyorSavedConsistList()}}
;Parameters
*None
;Returned Value
*An array of names of all the saved consist objects in Surveyor.
;Syntax
string[] consists = World.GetSurveyorSavedConsistList();
;Notes
*This method only works in Surveyor.
*Obsolete in TRS19.
 

==GetTimeElapsed==
{{MethodHeader|public native float GetTimeElapsed(void)}}
;Parameters
*None
;Returned Value
*The number of real-time seconds that have passed since the start of the current session.
;Syntax
float secondsElapsed = World.GetTimeElapsed();
;Notes
*This measure of time stops passing while the game is paused.
*Added in ...?
 

==GetTrackmarkList==
{{MethodHeader|public obsolete native [[Class TrackMark|TrackMark]][ ] GetTrackmarkList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackmark objects for the current route.
;Syntax
Trackmark[] trackmarks = World.GetTrackmarkList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetTrainList==
{{MethodHeader|public obsolete native [[Class Train|Train]][ ] GetTrainList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trains for the current route.
;Syntax
Train[] trains = World.GetTrainList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetTrainzBuild==
{{MethodHeader|public native int GetTrainzBuild(void)}}
;Parameters;
*None
;Returned Value
*Gets the current build number of Trainz.
;Syntax
int build = World.GetTrainzBuild();
;Notes
*The value returned corresponds to the build number you can see in the bottom-right side of the main Trainz menu screen.
 

==GetTrainzVersion==
{{MethodHeader|public native float GetTrainzVersion(void)}}
;Parameters
*None
;Returned Value
*The TRS version number.
;Syntax
float version = World.GetTrainzVersion();
;Notes
*The value returned corresponds to the version number of Content manager (for example 4.6).
 

==GetTriggerList==
{{MethodHeader|public obsolete native [[Class Trigger|Trigger]][ ] GetTriggerList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trigger objects for the current route.
;Syntax
Trigger[] triggers = World.GetTriggerList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
*This method does not return scenery triggers, ie those attached to SceneryWithTrack objects and their descendants.
 

==GetVehicleList==
{{MethodHeader|public obsolete native [[Class Vehicle|Vehicle]][ ] GetVehicleList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the vehicles in the current route.
;Syntax
Vehicle[] vehicles = World.GetVehicleList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetWeatherChangeability==
{{MethodHeader|public native int GetWeatherChangeability(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Weather_Changeability_Constants|Weather Changeability Constants]] denoting the variability of weather conditions.
;Syntax
int variability = World.GetWeatherChangeability();
;Notes
 

==GetWeatherType==
{{MethodHeader|public native int GetWeatherType(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Weather_Type_Constants|Weather Type Constants]] denoting the current weather conditions.
;Syntax
int weather = World.GetWeatherType();
;Notes
 

==IsAssetRestrictionInEffect==
{{MethodHeader|public native bool IsAssetRestrictionInEffect(string)}}
;Parameters
*None
;Returned Value
*Whether this game world has Asset Restrictions.
;Syntax
bool assetRestrictionsExist = World.IsAssetRestrictionInEffect();
;Notes
*Multiplayer Sessions require Asset Restrictions to be in effect to avoid compatibility issues between peers.
*Added in ...?
 

==IsLayerVisible==
{{MethodHeader|public native bool IsLayerVisible(string layerName)}}
;Parameter
*layerName = Name of the layer to check
;Returned Value
*Whether the layer is visible
;Syntax
bool isVisible = World.IsLayerVisible("MyLayer");
;Notes
*Added in ...?
 

==LoadMap==
{{MethodHeader|public native bool LoadMap([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of map to load.
;Returned Value
*True if successful, false otherwise.
;Syntax
if (World.LoadMap(mapKUID) Interface.Print("Map loaded OK");
else Interface.Print("Map load failed");
;Notes
*Use World.[[#FindKUID|FindKUID()]] to find the desired route KUID.
*In multiplayer, this will only succeed on the server.
 

==LoadSession==
{{MethodHeader|public native bool LoadSession([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of session to load.
;Returned Value
*True if successful, false otherwise.
;Syntax
if (World.LoadSession(sessionKUID) Interface.Print("Session loaded OK");
else Interface.Print("Session load failed");
;Notes
*Use World.[[#FindKUID|FindKUID()]] to find the desired session KUID.
*In multiplayer, this will only succeed on the server.
*Added in ...?
 

==Play2DSound==
{{MethodHeader|public float Play2DSound([[Class Asset|Asset]] asset, string wave)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
;Returned Value
* Undefined.
;Syntax
// Play the sound and continues script execution.
World.Play2DSound(soundAsset,"sounds/allaboard.wav");
// Wait until sound has completed before continuing (pre-TS12 only!)
Sleep(World.Play2DSound(soundAsset,"sounds/allaboard.wav"));
;Notes
*Plays a ''.wav" sound file from the given asset's folder.
*The sound is non directional and can be mono or stereo.
*This method does not return after the sound has finished playing, it returns with the length of the sound as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
 

==PlaySound==
{{MethodHeader|public native float PlaySound     ([[Class Asset|Asset]] asset, string wave, float vol, float near, float far, [[Class GameObject|GameObject]] target, string pt)     ([[Class Asset|Asset]] asset, string wave, float vol, float near, float far, [[Class GameObject|GameObject]] target, string pt, bool loop)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
*'''vol''' = Volume level to play the sound at (0 to 1)<- These values taken from TRS2019 world.gs file comments
*'''near''' = Distance from the target asset at which the sound will be played at maximum volume.
*'''far''' = Distance from the target asset at which the sound will become inaudible.
*'''target''' = GameObject to which the sound will be attached if a 3d sound is required, null for 2D.
*'''pt''' = Name of attachment point in the target object if a 3d sound is required, null for 2D.
*'''loop''' = (Optional) If true the sound will loop continuously.
;Returned Value
* Sound length in seconds for Trainz before TS12
* Undefined for TS12 and TANE
;Syntax
// Play the sound and continues script execution.
World.PlaySound(soundAsset,"sounds/allaboard.wav",1.0,10.0,100.0,Station,"a.loudspeaker");
// Wait until sound has completed before continuing (pre-TS12 only!)
Sleep(World.PlaySound(soundAsset,"sounds/allaboard.wav",1000.0,10.0,100.0,Station,"a.loudspeaker");
;Notes
*Plays a ''.wav'' sound file from the given asset's folder.
*If the sound is to be directional a mono sound file is required.
*This method does not return after the sound has finished playing: it returns as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
*If you want to wait for the sound to complete playing before moving on, wrap the PlaySound() call up in a Sleep() call. '''Note!''' This works only in Trainz versions before TS12. For newer versions, TS12 and TANE, you can hard-code the duration of the sound, or store it in the extensions container of the config.txt file.
*The sound volume will be at a maximum for a camera position at or less than the value of the ''near'' parameter and will reduce with distance until the hearing position reaches ''far'', when the sound will be inaudible.
 

==RemoveDriverCharacter==
{{MethodHeader|public native void RemoveDriverCharacter([[Class DriverCharacter|DriverCharacter]] driver)}}
;Parameters
*'''driver''' = DriverCharacter to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCharacter(dave);
;Notes
*In multiplayer, this will only succeed on the server.
 

==RemoveDriverCommand==
{{MethodHeader|public native void RemoveDriverCommand([[Class DriverCommand|DriverCommand]] command)}}
;Parameters
*'''command''' = DriverCommand to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCommand(driverCommand);
;Notes
*In multiplayer, this will only succeed on the server.
 

==RestartSession==
{{MethodHeader|public native bool RestartSession()}}
;Parameters
;Returned Value
*True if successful, false otherwise.
;Syntax
World.RestartSession();
;Notes
*Valid in Driver mode only.
*In multiplayer, this will only succeed on the server.
 

==SetBadWeatherFog==
{{MethodHeader|public obsolete native void SetBadWeatherFog(float distance)}}
;Parameters
*'''distance''' = Bad weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetBadWeatherFog(0.5);
;Notes
*Obsolete in TRS19
 

==SetCamera==
{{MethodHeader|public native bool SetCamera([[Class MapObject|MapObject]] focus) public native void SetCamera([[Class Junction|Junction]] focus) public native void SetCamera([[Class Vehicle|Vehicle]] focus, int cameraMode) public native void SetCamera([[Class Train|Train]] focus, int cameraMode)}}
;Parameters
*'''focus''' = Object on which the camera is to be focused.
*''cameraMode''' = One of the [[#Camera_View_Modes|Camera View Mode]] constants defining the view which should be assigned to the camera.
;Returned Value
*The first variant returns a boolean to indicate success or failure.
*Remaining variants do not return a value
;Syntax
World.SetCamera(train.GetVehicles[0],World.CAMERA_TRACKING); // sets the camera to track the first vehicle in the train.
;Notes
*Junction alias removed in TRS19?
 

==SetCameraAngle==
{{MethodHeader|public void SetCameraAngle(float yaw, float pitch, float radius) public obsolete void SetCameraAngle(int yaw, int pitch, float radius)}}
;Parameters
*'''yaw''' = Camera rotation in radians (float) or degrees (int), 90 is a direct front view.
*'''pitch''' = Camera angle relative to the horizon in radians (float), or degrees (int), 0 is horizontal, 90 points vertically upwards.
*'''radius''' = Distance in metres to the object in focus.
;Returned Value
*None
;Syntax
World.SetCameraAngle(90,0,25); // Sets the camera to a direct frontal view at 25 metres from the currently focused object.
;Notes
*''Radius'' is measured from the object origin point (0,0,0). If there's no target object this will be the distance to the ground.
*Note difference in units of ''yaw'' and ''pitch'' depending in the method signature used.
*The integer version of this method call is obsolete in TRS19.
 

==SetCameraFlags==
{{MethodHeader|public native void SetCameraFlags(int flags)}}
;Parameter
*'''flags''' integer value defining what the user is permitted to do with the game camera.
;Returned Value
*None
;Syntax
// User is permitted to select External or Tracking views only.
World.SetCameraFlags(World.CAMERA_EXTERNAL | World.CAMERA_TRACKING);
;Notes
*Use any combination of [[#Camera_Flags|Camera Flags]] and [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetCameraMode==
{{MethodHeader|public void SetCameraMode(int mode)}}
;Parameter
*'''mode''' = Camera mode to select.
;Returned Value
*None
;Syntax
World.SetCameraMode(World.CAMERA_TRACKING);
;Notes
*Use one of the [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetEditingCamera==
{{MethodHeader|public void SetEditingCamera([[Class GameObject|GameObject]] actor, bool bIsActorEditingCamera)}}
;Parameter
*'''actor''' = The script who is intended to edit the camera position.
*'''bIsActorEditingCamera''' = True to begin editing, or False to end the editing operation.
;Returned Value
*None
;Syntax
World.SetEditingCamera(myScript, true);
;Notes
*Hints to the caching systems that the camera position is in the process of being changed. This may reduce the amount of streaming that will occur until the change is complete.
*This is intended for use-cases where the decision to move the camera happens in advance of the actual call to [[#SetCamera|SetCamera()]] or etc., for example when the new camera target needs to be streamed in first.
*There is no advantage in calling this unless your code then sleeps/waits before undoing the call.
*It is not required to call this before using SetCamera() etc.
*A boolean state is stored per actor; multiple calls to enable editing on a single actor do not need to be matched to multiple calls to disable editing.
*It is counterproductive to call this when transitioning the camera over a short distance (ie. where the source and target locations can see each other). If jumping to a new location, followed by a visual camera transition at the new location, camera editing may be enabled around the target-selection for the jump, and the jump itself, but should be disabled before proceeding with the transition.
*Added in TRS19?
 

==SetGameDate==
{{MethodHeader|public void SetGameTime(int year, int month, int date)}}
;Parameters
*'''year''' = The year to set (1970-2038)
*'''month''' = The month to set (1-12)
*'''day''' = The day to set (1-31)
;Returned Value
*None
;Syntax
World.SetGameTime(2000, 12, 25); // sets date to 25 December 2000
;Notes
*In multiplayer, this will only succeed on the server.
*Added in ...?
 

==SetGameTime==
{{MethodHeader|public void SetGameTime(float time)}}
;Parameters
*'''time''' = new gane time to set.
;Returned Value
*None
;Syntax
World.SetGameTime(0.5); // sets time to midnight
;Notes
*Game time is normalised to a value between 0.0 and 1.0
*0.0 = midday
*0.25 = 6 p.m.
*0.5 = midnight
*0.75 = 6 a.m.
*1.0 = midday again
*Use the [[#Time_Values|Time Value]] constants to convert human readable times to normalised values.
 

==SetGameTimeRate==
{{MethodHeader|public native void SetGameTimeRate(float rate)}}
;Parameters
*'''rate''' = New time rate to set.
;Returned Value
*None
;Syntax
World.SetGameTimeRate(World.TIME_RATE_8X); // sets game time to advance by 8 minutes per minute of real world time.
;Notes
*Use one of the [[#Time_Rate_Constants|Time Rate Constants]] to define the parameter.
*In multiplayer, this will only succeed on the server.
 

==SetGoodWeatherFog==
{{MethodHeader|public obsolete native void SetGoodWeatherFog(float distance)}}
;Parameters
*'''distance''' = Good weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetGoodWeatherFog(0.5);
;Notes
*Obsolete in TRS19
 

==SetGroundDrawDistance==
{{MethodHeader|public obsolete native void SetGroundDrawDistance(float distance)}}
;Parameters
*'''distance''' = Ground draw distance in metres.
;Returned Value
*None
;Syntax
World.SetGroundDrawDistance(1000.0);
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==SetLayerVisible==
{{MethodHeader|public native void IsLayerVisible(string layerName, bool visible)}}
;Parameter
*layerName = Name of the layer to check
*visible = Whether to set the layer visible or not
;Returned Value
*None
;Syntax
World.IsLayerVisible("MyLayer", False);
;Notes
*Show/Hide a route/session layer.
*In multiplayer, this will only succeed on the server.
*Added in ...?
 

==SetSceneryDrawDistance==
{{MethodHeader|public obsolete native void SetSceneryDrawDistance(float distance)}}
;Parameters
*'''distance''' = unused.
;Returned Value
*None
;Notes
* Does nothing. Included for script compatibility only.
 

==SetTargetObserver==
{{MethodHeader|public void SetTargetObserver([[Class GameObject|GameObject]] observer)}}
;Parameters
*'''observer''' = The game object to receive targeting messages.
;Returned Value
*None
;Syntax
SetTargetObserver(self);
;Notes
* It is unlikely a script programmer would ever need to use this method.
* Causes the specified object to receive "Track", "LeftClick" messages when a track is clicked. Causes the specified object to receive "Interface-Event", "Left-Click" messages when a targetable MapObject is clicked. May cause the functionality of a left mouse click to change from what the user is expecting, so should be used with caution. Used in modal scripts to allow the user to indicate a location for train placement, etc. As there is only a single observer at any given time, the script must take care to only call this function when entering placement mode at the user's request.
 

==SetWeather==
{{MethodHeader|public native void SetWeather(int type, int changeability)}}
;Parameters
*'''type''' = Weather conditions as defined by one of the [[#Weather_Type_Constants|Weather Type Constants]].
*'''change''' = Weather variation as defined by one of the [[#Weather_Changeability_Constants|Weather Changeability Constants]].
;Returned Value
*None
;Syntax
World.SetWeather(World.WEATHER_TYPE_HEAVY_SNOW,World.WEATHER_CHANGEABILITY_EXTREME); // April in Paris.
;Notes
 

==SetWorldEditModeEnabled==
{{MethodHeader|public native bool SetWorldEditModeEnabled(int editFlags, bool enable)}}
;Parameters
*'''editFlags''' = Bitmask specifying which modes to alter, see PERMIT_EDIT_*
*''cameraMode''' = Whether to enable or disable the mode
;Returned Value
*Whether the change was completely successful
;Syntax
World.SetWorldEditModeEnabled(World.PERMIT_EDIT_TRAINS | World.PERMIT_EDIT_CONSISTS, True); // Enable player editing of trains and consists
;Notes
*This does not affect scripts which may alter the world, only the availability of the player world editing tools (i.e, the Surveyor tabs).
*Added in TRS19?
 

==SynchronouslyLoadGameObjectByID==
{{MethodHeader|public [[Class GameObject|GameObject]] SynchronouslyLoadGameObjectByID([[Class GameObjectID|GameObjectID]] objectID)}}
;Parameters
*'''objectID''' = The ID of the object to find.
;Returned Value
* The object, if it exists.
;Syntax
GameObject my_object = World.SynchronouslyLoadGameObjectByID(objectID);
if (my_object Interface.Print("Object exists and has been loaded if required");
;Notes
*This function is usable only by script 'thread' functions and will throw an exception if called incorrectly.
*Added in TRS19
 

==UpdatePositionToGroundHeight==
{{MethodHeader|public native bool UpdatePositionToGroundHeight([[Class WorldCoordinate|WorldCoordinate]] position)}}
;Parameters
*'''position''' (in, out) = Position object to update with the ground height at it's location
;Returned Value
* True if the ground position was updated
;Syntax
if (World.UpdatePositionToGroundHeight(position) Interface.Print("Position was updated");
;Notes
*This updates the input ''position'' object with the ground height at that location.
*This process may fail if the ground data at the specified location is not currently loaded.
*Added in TRS19?
 

==UpdatePositionToSurfaceHeight==
{{MethodHeader|public native bool UpdatePositionToSurfaceHeight([[Class WorldCoordinate|WorldCoordinate]] position)}}
;Parameters
*'''position''' (in, out) = Position object to update with the water height at it's location
;Returned Value
* True if the ground position was updated
;Syntax
if (World.UpdatePositionToGroundHeight(position) Interface.Print("Position was updated");
;Notes
*This updates the input ''position'' object with the water height at that location. If no water is present, the position is adjusted to the ground height.
*This process may fail if the ground data at the specified location is not currently loaded.
*Added in TRS19?
 

==UserSetCamera==
{{MethodHeader|public native bool UserSetCamera([[Class GameObject|GameObject]] target)}}
;Parameters
*'''target''' = GameObject to set focus to.
;Returned Value
*True if successful, false otherwise.
;Syntax
World.UserSetCamera(Router,GetGameObject("Junction 5"));
;Notes
 

==UserSetCameraMode==
{{MethodHeader|public native void UserSetCameraMode(int mode)}}
;Parameters
*'''mode''' = One of the [[#Camera_View_Modes|Camera View Modes]]
;Returned Value
*None
;Syntax
World.UserSetCameraMode(World.CAMERA_ROAMING); // switches to roaming view if permitted.
;Notes
*This method respects the current [[#Camera_Flags|Camera Flag]] settings, disallowing any change which the flags do not permit.
 

==UserSetCameraPosition==
{{MethodHeader|public native bool UserSetCamera([[Class WorldCoordinate|WorldCoordinate]] camPos)}}
;Parameters
*'''camPos''' = World coordinates to set camera to
;Returned Value
*True if successful, false otherwise.
;Syntax
World.UserSetCamera(Router,GetGameObject("Junction 5"));
;Notes
* For camera modes which do not need to target specific objects, this allows the camera to be set to an arbitrary world position.
*Added in TRS19?
 

==Categories==
[[Category:Script Class]]

Class World

2020-12-28T17:07:29Z

Danny252: Update to current state of world.gs

*[[TrainzScript Library Reference|API Hierarchy]]
**World (world.gs)
 
*World is a static class used to access various aspects of the Trainz environment.
 

==Constants==
*These constants are used to define various values and can be used as mnenomics.
*If accessed from scripts the values must be prefixed ''World.'', for example:
World.SetWeather(World.WEATHER_TYPE_LIGHT_SNOW,World.WEATHER_CHANGEABILITY_PERIODIC);
 

===Camera View Modes===
----
*These values can be used either to choose the current camera viewing mode through World.[[#SetCameraMode|SetCameraMode()]], or to restrict certain camera modes from being accessed through methods such as World.[[#SetCamera|SetCamera()]].

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_INTERNAL = 1||Internal cabin camera view.
|-
|public define int CAMERA_EXTERNAL = 2||External train camera view
|-
|public define int CAMERA_TRACKING = 4||External tracking camera view.
|-
|public define int CAMERA_ROAMING = 128||Roaming camera view.
|}
 

===Camera Flags===
----
*These flags are used in addition to the Camera Mode Flags to allow or disallow specific camera actions.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_SWITCH_VIEWS = 8||User permitted to swap between the camera views.
|-
|public define int CAMERA_SWITCH_VEHICLES = 16||User permitted to swap vehicles within the current train.
|-
|public define int CAMERA_SWITCH_TRAINS = 32||User permitted to swap to other trains which are in the consist menu.
|-
|public define int CAMERA_LOCKED = 64||User is NOT permitted to adjust camera (i.e. zoom, pan etc.).
|-
|public define int CAMERA_NORMAL = * ||Normal camera mode where everything is permitted.
|-
|colspan=2|* NOTE: CAMERA_NORMAL = CAMERA_INTERNAL | CAMERA_EXTERNAL | CAMERA_TRACKING | CAMERA_SWITCH_VIEWS | CAMERA_SWITCH_VEHICLES | CAMERA_SWITCH_TRAINS
|}
 

===Weather Type Constants===
----
*Define the current state of the weather in Trainz.
*A variety of weather conditions are supported and can be changed by using one of these values with the World.[[#SetWeather|SetWeather()]] method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_TYPE_CLEAR = 0||Clear weather, no clouds, rain or snow.
|-
|public define int WEATHER_TYPE_CLOUDY = 1||Cloudy weather, no rain.
|-
|public define int WEATHER_TYPE_DRIZZLE = 2||Drizzle, light rain.
|-
|public define int WEATHER_TYPE_RAIN = 3||Rainy weather.
|-
|public define int WEATHER_TYPE_STORMY = 4||Stormy weather that includes lightning and thunder.
|-
|public define int WEATHER_TYPE_LIGHT_SNOW = 5||Snowing lightly.
|-
|public define int WEATHER_TYPE_MEDIUM_SNOW = 6||Medium level snow fall.
|-
|public define int WEATHER_TYPE_HEAVY_SNOW = 7||Heavy snow fall.
|}
 

===Weather Changeability Constants===
----
*Define the changeability settings for the weather.
*Weather changeability refers to variability of weather conditions rather than to a specific weather type.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_CHANGEABILITY_NONE = 0||Weather remains static.
|-
|public define int WEATHER_CHANGEABILITY_PERIODIC = 1||Periodic changes in weather.
|-
|public define int WEATHER_CHANGEABILITY_EXTREME = 2||Extreme and frequent changes in weather.
|}
 

===Time Values===
----
*Time constants defined in seconds.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float TIME_SECOND = 1.0f||One second.
|-
|public define float TIME_MINUTE = TIME_SECOND * 60.0f||One minute, 60.0 seconds.
|-
|public define float TIME_HOUR = TIME_MINUTE * 60.0f||One hour, 60.0 minutes, 3600.0 seconds.
|-
|public define float TIME_DAY = TIME_HOUR * 24.0f||One day, 24 hours, 1440.0 minutes, 86400.0 seconds.
|}
 

===Time Rate Constants===
----
*Values that define the time rates relative to normal time.
*These constants can be used to set the time rate that Trainz runs out through the World.[[#SetGameTimeRate|SetGameTimeRate()]] method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int TIME_RATE_1X = 0||Real time (i.e. time in Trainz passes at the same rate as in the real world)
|-
|public define int TIME_RATE_2X = 1||Time passes at twice normal speed.
|-
|public define int TIME_RATE_4X = 2||
|-
|public define int TIME_RATE_8X = 3||
|-
|public define int TIME_RATE_16X = 4||
|-
|public define int TIME_RATE_32X = 5||
|-
|public define int TIME_RATE_60X = 6||
|-
|public define int TIME_RATE_120X = 7||
|-
|public define int TIME_RATE_240X = 8||
|-
|public define int TIME_RATE_360X = 9||
|-
|public define int TIME_RATE_480X = 10||
|-
|public define int TIME_RATE_720X = 11||
|-
|public define int TIME_RATE_960X = 12||
|-
|public define int TIME_RATE_1200X = 13||
|-
|public define int TIME_RATE_1440X = 14||
|}
 

===Layer Type Constants===
----
*These constants can be used for querying route/session layers via [[#GetLayerList|GetLayerList]] and [[#GetLayerType|GetLayerType]].
*Added in TRS19?
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int LAYER_INVALID = 0||
|-
|public define int LAYER_ROUTE = 1||
|-
|public define int LAYER_SESSION = 2||
|-
|public define int LAYER_BOTH = 3||
|}
 

===World Editing Mode Constants===
----
*These constants can be used to set editing modes through World.[[#SetWorldEditModeEnabled|SetWorldEditModeEnabled()]].
*Added in TRS19?
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int PERMIT_EDIT_NONE = 0x0||
|-
|public define int PERMIT_EDIT_TOPOLOGY = 0x1||
|-
|public define int PERMIT_EDIT_PAINT = 0x2||
|-
|public define int PERMIT_EDIT_SCENERYOBJECTS = 0x4||
|-
|public define int PERMIT_EDIT_SCENERYSPLINES = 0x8||
|-
|public define int PERMIT_EDIT_TRACKSPLINES = 0x10||
|-
|public define int PERMIT_EDIT_TRACKSIDEOBJECTS = 0x20||
|-
|public define int PERMIT_EDIT_TRACKMARKS = 0x40||
|-
|public define int PERMIT_EDIT_TOOLS = 0x80||
|-
|public define int PERMIT_EDIT_WORLD = 0x100||
|-
|public define int PERMIT_EDIT_LAYERS = 0x200||
|-
|public define int PERMIT_EDIT_TRAINS = 0x400||
|-
|public define int PERMIT_EDIT_CONSISTS = 0x800||
|-
|public define int PERMIT_EDIT_ALL = -1||
|}
 

===Trainz Modules===
----
*Trainz module mode constants.
*These values define the various module environments that Trainz can be in.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NO_MODULE = 0||Trainz not running in a module.
|-
|public define int SURVEYOR_MODULE = 1||Trainz is currently running in Surveyor.
|-
|public define int DRIVER_MODULE = 2||Trainz is currently running in Driver.
|}
 

==Related Messages==
* [[TrainzScript Message Reference]] 
* [[Camera Messages]] 
* [[Interface Messages]] 
* [[ModuleInit Message]] 
 

==AddDriverCharacter==
{{MethodHeader|public native [[Class DriverCharacter|DriverCharacter]] AddDriverCharacter([[Class Asset|Asset]] driverCharacterAsset)}}
;Parameters
*'''driverCharacterAsset''' = Asset containing character to be added.
;Returned Value
*Reference to the DriverCharacter if successful, null otherwise.
;Syntax
DriverCharacter Casey = World.AddDriverCharacter(CaseyJones);
;Notes
*In multiplayer, this will only succeed on the server.
 

==AddDriverCommand==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]] AddDriverCommand([[Class Asset|Asset]] driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.AddDriverCommand(accelerate);
;Notes
*In multiplayer, this will only succeed on the server.
 

==CancelCurrentEditingMode==
{{MethodHeader|public native void CancelCurrentEditingMode(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
World.CancelCurrentEditingMode();
;Notes
* Cancels out of any player entered editing mode, if relevant. This should only normally be called as a result of direct player action.
*Added in TRS19?
 

==CreateBehavior==
{{MethodHeader|public native [[Class ScenarioBehavior|ScenarioBehavior]] CreateBehavior([[Class KUID|KUID]] kuid, [[Class Soup|Soup]] initialProperties)}}
;Parameters
*'''kuid''' = KUID of scenario.
'''initialProperties''' = Soup object containing initial properties for scenario.
;Returned Value
*Reference to the ScenarioBehavior created if successful, null otherwise.
;Syntax
ScenarioBehavior scenario = World.CreateBehavior(scenarioAsset, scenarioSoup);
;Notes
*The returned ScenarioBehavior object may be ended by releasing all references to it (resetting all references to null).
 

==CreateTrain==
{{MethodHeader|public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, string trackmarkName, bool direction) public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class TrackMark|TrackMark]] trackmark, bool direction) public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class Buildable|Buildable]] buildable, string trackName, float position, bool direction)}} public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class GSTrackSearch|GSTrackSearch]] tracksearch, bool avoidDerailments)}} public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class GSTrackSearch|GSTrackSearch]] tracksearch)}}
;Parameters
*'''consist''' = An array of vehicle KUIDs used to describe the required Train object.
*'''trackmarkName''' = Name of Trackmark at which the consist is to be formed.
*'''buildable''' = Buildable on which the consist is to be formed.
*'''trackName''' = Name of track within Buildable object.
*'''position''' = Distance at which the Train is to be placed relative to the start of the track.
*'''trackmark''' = Reference to Trackmark at which the consist is to be formed.
*'''direction''' = Orientation of Train relative to direction of track or trackmark.
*'''tracksearch''' = The location at which to create the train
*'''avoidDerailments''' = If true this function will fail and return null if creating the train would cause a derailment
;Returned Value
*Reference to the Train created if successful, null otherwise.
;Syntax
Train train = World.CreateTrain(consist, buildable, "Track 1", 10.0, true);
;Notes
*These methods create a train from a list of vehicles in a consist array.
*Depending on the variant of the method used, the train can be created at a Trackmark, specified by name or reference, or at a Buildable or Industry object.
*It is the responsibility of the script programmer to ensure that sufficient track exists at the given location to allow the train to be created.
*In multiplayer, this will only succeed on the server.
*'''GSTrackSearch''' aliases added in TRS19?
 

==DeleteTrain==
{{MethodHeader|public native void DeleteTrain([[Class Train|Train]] train)}}
;Parameters
*'''train''' = train to be deleted from map.
;Returned Value
*None
;Syntax
World.DeleteTrain(flyingScotsman);
;Notes
*Once a train has been deleted, care should be taken to avoid using its reference.
*In multiplayer, this will only succeed on the server.
 

==DeleteVehicle==
{{MethodHeader|public native void DeleteVehicle([[Class Vehicle|Vehicle]] vehicle)}}
;Parameters
*'''vehicle''' = vehicle to be deleted from its train.
;Returned Value
*None
;Syntax
World.DeleteVehicle(vehicles[vehicles.size()-1]);
;Notes
*Use [[Class Train#GetVehicles|Train.GetVehicles()]] to obtain an array of vehicles for a given train.
*Use [[Class Vehicle#GetMyTrain|Vehicle.GetMyTrain()]] to obtain a train reference for a given vehicle.
*In multiplayer, this will only succeed on the server.
 

==EndScenario==
{{MethodHeader|public void EndScenario(float time)}}
;Parameters
*'''time''' = Amount of seconds to delay before ending the session
;Returned Value
*None
;Syntax
World.EndScenario(30.0);
;Notes
*In multiplayer, this will only succeed on the server.
 

==FindAsset==
{{MethodHeader|public native [[Class Asset|Asset]] FindAsset([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of Asset to return.
;Returned Value
*Given a valid KUID parameter, this method return an Asset reference if successful, null otherwise.
;Syntax
Asset asset = World.FindAsset(kuid);
;Notes
*See also Asset.FindAsset()
 

==FindDriverCommand==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]] FindDriverCommand([[Class Asset|Asset]] driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.FindDriverCommand(accelerate);
;Notes
 

==GetAssetList==
{{MethodHeader|public native [[Class Asset|Asset]][ ] GetAssetList(string kind)}}
;Parameters
*'''kind''' = String representing the Kind of asset to return.
;Returned Value
*A list of all assets of the given ''kind''
;Syntax
Asset[] Libraries = World.GetAssetList("Library");
;Notes
*All installed assets of the given ''kind'' are returned, irrespective of whether or not they are in use on the current map.
 

==GetBadWeatherFog==
{{MethodHeader|public obsolete native float GetBadWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Bad weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetBadWeatherFog();
;Notes
*Obsolete in TRS19
 

==GetBehaviors==
{{MethodHeader|public native [[Class ScenarioBehavior|ScenarioBehavior]][ ] GetBehaviors(void)}}
;Parameters
*None
;Returned Value
*A list of top-level behaviors or rules on the currently loaded route.
;Syntax
ScenarioBehavior[] rules = World.GetBehaviors();
;Notes
 

==GetCameraPitch==
{{MethodHeader|public native float GetCameraPitch(void)}}
;Parameters
*None
;Returned Value
*Current camera pitch, in radians
;Syntax
float pitch = World.GetCameraPitch();
;Notes
*Added in ...?
 

==GetCameraPositionX==
{{MethodHeader|public obsolete native float GetCameraPositionX(void)}}
;Parameters
*None
;Returned Value
*X Coordinate of the current camera position.
;Syntax
float X = World.GetCameraPositionX();
;Notes
*Obsolete in TRS19
 

==GetCameraPositionY==
{{MethodHeader|public obsolete native float GetCameraPositionY(void)}}
;Parameters
*None
;Returned Value
*Y Coordinate of the current camera position.
;Syntax
float Y = World.GetCameraPositionY();
;Notes
*Obsolete in TRS19
 

==GetCameraPositionZ==
{{MethodHeader|public obsolete native float GetCameraPositionZ(void)}}
;Parameters
*None
;Returned Value
*Z Coordinate of the current camera position.
;Syntax
float Z = World.GetCameraPositionZ();
;Notes
*Obsolete in TRS19
 

==GetCameraYaw==
{{MethodHeader|public native float GetCameraYaw(void)}}
;Parameters
*None
;Returned Value
*Current camera yaw, in radians
;Syntax
float yaw = World.GetCameraYaw();
;Notes
*Added in ...?
 

==GetCameraZoom==
{{MethodHeader|public native float GetCameraZoom(void)}}
;Parameters
*None
;Returned Value
*Current camera zoom, in meters
;Syntax
float zoom= World.GetCameraZoom();
;Notes
*Is this value equivalent to '''radius''' in [[#SetCameraAngle|SetCameraAngle()]]?
*Added in ...?
 

==GetCurrentModule==
{{MethodHeader|public native int GetCurrentModule(void)}}
;Parameters
*None
;Returned Value
*An integer representing the current Trainz module.
;Syntax
int module = World.GetCurrentModule();
;Notes
* See [[#Trainz Modules|Trainz Modules]] for details of the constants associated with this method.
* See [[ModuleInit Message]] for further details.
 

==GetCurrentProfile==
{{MethodHeader|public native [[Class Asset|Asset]] GetCurrentProfile(void)}}
;Parameters
*None
;Returned Value
*The current session asset
;Syntax
Asset currentSession = World.GetCurrentProfile();
;Notes
*Added in ...?
 

==GetCurrentTrain==
{{MethodHeader|public native Train GetCurrentTrain(void)}}
;Parameters
*None
;Returned Value
*The currently focused train
;Syntax
Train myTrain = World.GetCurrentTrain();
;Notes
* The current train is the one currently controlled by the user, which may not be the train the camera is focused on.
*Added in ...?
 

==GetDriverCharacterList==
{{MethodHeader|public native [[Class DriverCharacter|DriverCharacter]][ ] GetDriverCharacterList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCharacter objects installed in the current world.
;Syntax
DriverCharacter[] drivers = World.GetDriverCharacterList();
;Notes
 

==GetDriverCommandList==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]][ ] GetDriverCommandList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCommand objects installed in the current world.
;Syntax
DriverCommand[] commands = World.GetDriverCommandList();
;Notes
 

==GetGameDate==
{{MethodHeader|public native int GetGameDate(void)}}
;Parameters
*None
;Returned value
*Current game day (1 - 31)
;Syntax
int Now = World.GetGameDate();
;Notes
*Added in ...?
 

==GetGameMonth==
{{MethodHeader|public native int GetGameMonth(void)}}
;Parameters
*None
;Returned value
*Current game month (1 - 12)
;Syntax
int Now = World.GetGameMonth();
;Notes
*Added in ...?
 

==GetGameObjectByID==
{{MethodHeader|public native [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetGameObjectByID([[Class GameObjectID|GameObjectID]] objectID, bool bTriggerLoad) public native [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetGameObjectByID([[Class GameObjectID|GameObjectID]] objectID)}}
;Parameters
*'''objectID''' = The ID of the object to find.
*'''bTriggerLoad''' = Optional, defaults to true. Whether to trigger an asynchronous load of any matching object (if it's not loaded already).
;Returned Value
* Asynchronous search result object.
;Syntax
AsyncObjectSearchResult search_result = World.GetGameObjectByID(objectID, true); // Search for and load an object
;Notes
*See [[HowTo/Search for objects in the world]] for a detailed guide on asynchronous searches.
*The retured object is a reference to the in-progress object search.
*When the search completes, a message of type "ObjectSearch","AsyncResult" will be posted to the result object.
*If bTriggerLoad is true, a further message of type "ObjectSearch","AsyncLoadComplete" will be posted when all objects are loaded into memory. This message will still be posted if every object is already loaded.
*Added in TRS19
 

==GetGameObjectByIDIfLoaded==
{{MethodHeader|public native [[Class GameObject|GameObject]] GetGameObjectByIDIfLoaded([[Class GameObjectID|GameObjectID]] objectID)}}
;Parameters
*'''objectID''' = The ID of the boject to find.
;Returned Value
* The object, if it exists and is currently loaded.
;Syntax
GameObject my_object = World.GetGameObjectByID(objectID);
if (my_object Interface.Print("Object exists and is loaded");
;Notes
*Added in TRS19
 

==GetGameSeason==
{{MethodHeader|public native float GetGameSeason(void)}}
;Parameters
*None
;Returned value
*Current game season
;Syntax
float Season = World.GetGameSeason();
;Notes
*The returned time is normalised to a value between 0.0 and 1.0
*0.0 = mid-summer
*0.5 = mid-winter
*Added in ...?
 

==GetGameTime==
{{MethodHeader|public native float GetGameTime(void)}}
;Parameters
*None
;Returned value
*Current game time.
;Syntax
float Now = World.GetGameTime();
;Notes
*The returned time is normalised to a value between 0.0 and 1.0
*0.0 = midday
*0.25 = 6 p.m.
*0.5 = midnight
*0.75 = 6 a.m.
*1.0 = midday again
*Use the [[#Time_Values|Time Value]] constants to convert the normalised values to human readable times.
 

==GetGameYear==
{{MethodHeader|public native int GetGameYear(void)}}
;Parameters
*None
;Returned value
*Current game year.
;Syntax
int Now = World.GetGameYear();
;Notes
*Added in ...?
 

==GetGoodWeatherFog==
{{MethodHeader|public obsolete native float GetGoodWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Good weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetGoodWeatherFog();
;Notes
*Obsolete in TRS19
 

==GetGroundDrawDistance==
{{MethodHeader|public obsolete native float GetGroundDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Ground draw distance in metres.
;Syntax
float dist = World.GetGroundDrawDistance();
;Notes
 

==GetIndustryList==
{{MethodHeader|public obsolete native [[Class GameObject|GameObject]][ ] GetIndustryList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the Industry objects for the current route.
;Syntax
GameObject[] Industries = World.GetIndustryList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetJunctionList==
{{MethodHeader|public obsolete native [[Class Junction|Junction]][ ] GetJunctionList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackside junction objects for the current route.
;Syntax
Junction[] junctions = World.GetJunctionList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
*Junction objects attached to fixed track junctions are not returned by this method.
 

==GetLayerList==
{{MethodHeader|public native string[ ] GetLayerList(int layerType)}}
;Parameters
*layerType = LAYER_ROUTE, LAYER_SESSION, or LAYER_BOTH
;Returned Value
*Array of layer names
;Syntax
string[] routeLayerNames = World.GetLayerList(World.LAYER_ROUTE);
;Notes
*Added in ...?
 

==GetLayerType==
{{MethodHeader|public native int GetLayerType(string layerName)}}
;Parameters
*layerName = The name of the layer
;Returned Value
*LAYER_ROUTE or LAYER_SESSION
;Syntax
int layerType = World.GetLayerType("MyLayer");
;Notes
*Added in ...?
 

==GetLibrary==
{{MethodHeader|public native [[Class Library|Library]] GetLibrary([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of script library asset to load.
;Returned Value
*A reference to the script library asset if successful, null otherwise.
;Syntax
Library codelib = World.GetLibrary(LibraryKUID);
;Notes
*The [[Class Library|Library]] asset is initialised when this method is first called in a session.
*Since only one instance can exist, subsequent calls return a reference to the existing Library object.
*See [[Class Library|Library]] for notes on how to use this method.
 

==GetLocalPlayerName==
{{MethodHeader|public native string GetLocalPlayerName(void)}}
;Parameters
*None
;Returned Value
*The name of the local player
;Syntax
string playerName = World.GetLocalPlayerName();
;Notes
* Gets the name of the local player, as should be used for setting ownership on DriverCharacters, etc.
*Added in .TRS19?
 

==GetNamedObjectList==
{{MethodHeader|public native [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetNamedObjectList(string categoryFilter, string nameFilter, bool bNotifyOfExpiry) public [[Class AsyncObjectSearchResult|AsyncObjectSearchResult]] GetNamedObjectList(string categoryFilter, string nameFilter)}}
;Parameters
*'''categoryFilter''' = A category filter to search for. Optional, provided a nameFilter parameter is provided. A category code reference can be found in [[Class AssetCategory|AssetCategory]].
*'''nameFilter''' = A partial object name to search for. Optional, provided a categoryFilter parameter is provided.
*'''bNotifyOfExpiry''' = Optional, defaults to false. If native code detects that the search results have changed then a message of type "ObjectSearch","Expired" will be posted to the result object, and the calling script can perform a new search if desired
;Returned Value
* Asynchronous search result object.
;Syntax
AsyncObjectSearchResult search_result = World.GetNamedObjectList(AssetCategory.Locomotive, "SD40-2"); // Search for all SD40-2 locomotives in the world
;Notes
*See [[HowTo/Search for objects in the world]] for a detailed guide on asynchronous searches.
*The retured object is a reference to the in-progress object search.
*When the search completes, a message of type "ObjectSearch","AsyncResult" will be posted to the result object.
*With expiration notices are enabled, only one notification of type "ObjectSearch","Expired" will be posted for each search.
*Added in TRS19
 

==GetSceneryDrawDistance==
{{MethodHeader|public obsolete native float GetSceneryDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Undefined.
;Notes
*Included for legacy script compatibility only. Has no effect.
 

==GetSeconds==
{{MethodHeader|public native float GetSeconds(void)}}
;Parameters
*None
;Returned Value
*The current value of a floating point number incrementing once per second in real time.
;Syntax
float start = World.GetSeconds();
// do stuff
float finish = World.GetSeconds();
float period = finish - start;
;Notes
*Each call will return a float value containing the current value of an internal counter.
*Subtracting a later value from a value saved at an earlier call will enable the delay between the two calls to be established.
 

==GetSignalList==
{{MethodHeader|public obsolete native [[Class Signal|Signal]][ ] GetSignalList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the signal objects for the current route.
;Syntax
Signal[] signals = World.GetSignalList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetStringTable==
{{MethodHeader|public native [[Class StringTable|StringTable]] GetStringTable(void)}}
;Parameters
*None
;Returned Value
*The StringTable for the current session.
;Syntax
StringTable data = World.GetStringTable();
;Notes
 

==GetSurveyorSavedConsist==
{{MethodHeader|public obsolete native [[Class Soup|Soup]] GetSurveyorSavedConsist(string name)}}
;Parameters
*'''name''' = Name of the consist to retrieve.
;Returned Value
*Returns a Soup definition of the named consist if it exists, null otherwise.
;Syntax
Soup consist = World.GetSurveyorSavedConsist("Brighton Belle");
;Notes
*Remember that the returned data is in a Soup format, which is not the same thing as a Train.
*TrainUtil.CreateTrainFormSoup() can be used to create a train from the returned Soup.
*This method only works in Surveyor.
*Obsolete in TRS19.
 

==GetSurveyorSavedConsistList==
{{MethodHeader|public native string[ ] GetSurveyorSavedConsistList()}}
;Parameters
*None
;Returned Value
*An array of names of all the saved consist objects in Surveyor.
;Syntax
string[] consists = World.GetSurveyorSavedConsistList();
;Notes
*This method only works in Surveyor.
*Obsolete in TRS19.
 

==GetTimeElapsed==
{{MethodHeader|public native float GetTimeElapsed(void)}}
;Parameters
*None
;Returned Value
*The number of real-time seconds that have passed since the start of the current session.
;Syntax
float secondsElapsed = World.GetTimeElapsed();
;Notes
*This measure of time stops passing while the game is paused.
*Added in ...?
 

==GetTrackmarkList==
{{MethodHeader|public obsolete native [[Class TrackMark|TrackMark]][ ] GetTrackmarkList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackmark objects for the current route.
;Syntax
Trackmark[] trackmarks = World.GetTrackmarkList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetTrainList==
{{MethodHeader|public obsolete native [[Class Train|Train]][ ] GetTrainList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trains for the current route.
;Syntax
Train[] trains = World.GetTrainList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetTrainzBuild==
{{MethodHeader|public native int GetTrainzBuild(void)}}
;Parameters;
*None
;Returned Value
*Gets the current build number of Trainz.
;Syntax
int build = World.GetTrainzBuild();
;Notes
*The value returned corresponds to the build number you can see in the bottom-right side of the main Trainz menu screen.
 

==GetTrainzVersion==
{{MethodHeader|public native float GetTrainzVersion(void)}}
;Parameters
*None
;Returned Value
*The TRS version number.
;Syntax
float version = World.GetTrainzVersion();
;Notes
*The value returned corresponds to the version number of Content manager (for example 4.6).
 

==GetTriggerList==
{{MethodHeader|public obsolete native [[Class Trigger|Trigger]][ ] GetTriggerList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trigger objects for the current route.
;Syntax
Trigger[] triggers = World.GetTriggerList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
*This method does not return scenery triggers, ie those attached to SceneryWithTrack objects and their descendants.
 

==GetVehicleList==
{{MethodHeader|public obsolete native [[Class Vehicle|Vehicle]][ ] GetVehicleList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the vehicles in the current route.
;Syntax
Vehicle[] vehicles = World.GetVehicleList();
;Notes
*This function is obsolete and should not be used. Use [[#GetNamedObjectList|GetNamedObjectList]] instead.
 

==GetWeatherChangeability==
{{MethodHeader|public native int GetWeatherChangeability(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Weather_Changeability_Constants|Weather Changeability Constants]] denoting the variability of weather conditions.
;Syntax
int variability = World.GetWeatherChangeability();
;Notes
 

==GetWeatherType==
{{MethodHeader|public native int GetWeatherType(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Weather_Type_Constants|Weather Type Constants]] denoting the current weather conditions.
;Syntax
int weather = World.GetWeatherType();
;Notes
 

==IsAssetRestrictionInEffect==
{{MethodHeader|public native bool IsAssetRestrictionInEffect(string)}}
;Parameters
*None
;Returned Value
*Whether this game world has Asset Restrictions.
;Syntax
bool assetRestrictionsExist = World.IsAssetRestrictionInEffect();
;Notes
*Multiplayer Sessions require Asset Restrictions to be in effect to avoid compatibility issues between peers.
*Added in ...?
 

==IsLayerVisible==
{{MethodHeader|public native bool IsLayerVisible(string layerName)}}
;Parameter
*layerName = Name of the layer to check
;Returned Value
*Whether the layer is visible
;Syntax
bool isVisible = World.IsLayerVisible("MyLayer");
;Notes
*Added in ...?
 

==LoadMap==
{{MethodHeader|public native bool LoadMap([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of map to load.
;Returned Value
*True if successful, false otherwise.
;Syntax
if (World.LoadMap(mapKUID) Interface.Print("Map loaded OK");
else Interface.Print("Map load failed");
;Notes
*Use World.[[#FindKUID|FindKUID()]] to find the desired route KUID.
*In multiplayer, this will only succeed on the server.
 

==LoadSession==
{{MethodHeader|public native bool LoadSession([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of session to load.
;Returned Value
*True if successful, false otherwise.
;Syntax
if (World.LoadSession(sessionKUID) Interface.Print("Session loaded OK");
else Interface.Print("Session load failed");
;Notes
*Use World.[[#FindKUID|FindKUID()]] to find the desired session KUID.
*In multiplayer, this will only succeed on the server.
*Added in ...?
 

==Play2DSound==
{{MethodHeader|public float Play2DSound([[Class Asset|Asset]] asset, string wave)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
;Returned Value
* Undefined.
;Syntax
// Play the sound and continues script execution.
World.Play2DSound(soundAsset,"sounds/allaboard.wav");
// Wait until sound has completed before continuing (pre-TS12 only!)
Sleep(World.Play2DSound(soundAsset,"sounds/allaboard.wav"));
;Notes
*Plays a ''.wav" sound file from the given asset's folder.
*The sound is non directional and can be mono or stereo.
*This method does not return after the sound has finished playing, it returns with the length of the sound as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
 

==PlaySound==
{{MethodHeader|public native float PlaySound     ([[Class Asset|Asset]] asset, string wave, float vol, float near, float far, [[Class GameObject|GameObject]] target, string pt)     ([[Class Asset|Asset]] asset, string wave, float vol, float near, float far, [[Class GameObject|GameObject]] target, string pt, bool loop)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
*'''vol''' = Volume level to play the sound at (0 to 1)<- These values taken from TRS2019 world.gs file comments
*'''near''' = Distance from the target asset at which the sound will be played at maximum volume.
*'''far''' = Distance from the target asset at which the sound will become inaudible.
*'''target''' = GameObject to which the sound will be attached if a 3d sound is required, null for 2D.
*'''pt''' = Name of attachment point in the target object if a 3d sound is required, null for 2D.
*'''loop''' = (Optional) If true the sound will loop continuously.
;Returned Value
* Sound length in seconds for Trainz before TS12
* Undefined for TS12 and TANE
;Syntax
// Play the sound and continues script execution.
World.PlaySound(soundAsset,"sounds/allaboard.wav",1.0,10.0,100.0,Station,"a.loudspeaker");
// Wait until sound has completed before continuing (pre-TS12 only!)
Sleep(World.PlaySound(soundAsset,"sounds/allaboard.wav",1000.0,10.0,100.0,Station,"a.loudspeaker");
;Notes
*Plays a ''.wav'' sound file from the given asset's folder.
*If the sound is to be directional a mono sound file is required.
*This method does not return after the sound has finished playing: it returns as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
*If you want to wait for the sound to complete playing before moving on, wrap the PlaySound() call up in a Sleep() call. '''Note!''' This works only in Trainz versions before TS12. For newer versions, TS12 and TANE, you can hard-code the duration of the sound, or store it in the extensions container of the config.txt file.
*The sound volume will be at a maximum for a camera position at or less than the value of the ''near'' parameter and will reduce with distance until the hearing position reaches ''far'', when the sound will be inaudible.
 

==RemoveDriverCharacter==
{{MethodHeader|public native void RemoveDriverCharacter([[Class DriverCharacter|DriverCharacter]] driver)}}
;Parameters
*'''driver''' = DriverCharacter to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCharacter(dave);
;Notes
*In multiplayer, this will only succeed on the server.
 

==RemoveDriverCommand==
{{MethodHeader|public native void RemoveDriverCommand([[Class DriverCommand|DriverCommand]] command)}}
;Parameters
*'''command''' = DriverCommand to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCommand(driverCommand);
;Notes
*In multiplayer, this will only succeed on the server.
 

==RestartSession==
{{MethodHeader|public native bool RestartSession()}}
;Parameters
;Returned Value
*True if successful, false otherwise.
;Syntax
World.RestartSession();
;Notes
*Valid in Driver mode only.
*In multiplayer, this will only succeed on the server.
 

==SetBadWeatherFog==
{{MethodHeader|public obsolete native void SetBadWeatherFog(float distance)}}
;Parameters
*'''distance''' = Bad weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetBadWeatherFog(0.5);
;Notes
*Obsolete in TRS19
 

==SetCamera==
{{MethodHeader|public native bool SetCamera([[Class MapObject|MapObject]] focus) public native void SetCamera([[Class Junction|Junction]] focus) public native void SetCamera([[Class Vehicle|Vehicle]] focus, int cameraMode) public native void SetCamera([[Class Train|Train]] focus, int cameraMode)}}
;Parameters
*'''focus''' = Object on which the camera is to be focused.
*''cameraMode''' = One of the [[#Camera_View_Modes|Camera View Mode]] constants defining the view which should be assigned to the camera.
;Returned Value
*The first variant returns a boolean to indicate success or failure.
*Remaining variants do not return a value
;Syntax
World.SetCamera(train.GetVehicles[0],World.CAMERA_TRACKING); // sets the camera to track the first vehicle in the train.
;Notes
*Junction alias removed in TRS19?
 

==SetCameraAngle==
{{MethodHeader|public void SetCameraAngle(float yaw, float pitch, float radius) public obsolete void SetCameraAngle(int yaw, int pitch, float radius)}}
;Parameters
*'''yaw''' = Camera rotation in radians (float) or degrees (int), 90 is a direct front view.
*'''pitch''' = Camera angle relative to the horizon in radians (float), or degrees (int), 0 is horizontal, 90 points vertically upwards.
*'''radius''' = Distance in metres to the object in focus.
;Returned Value
*None
;Syntax
World.SetCameraAngle(90,0,25); // Sets the camera to a direct frontal view at 25 metres from the currently focused object.
;Notes
*''Radius'' is measured from the object origin point (0,0,0). If there's no target object this will be the distance to the ground.
*Note difference in units of ''yaw'' and ''pitch'' depending in the method signature used.
*The integer version of this method call is obsolete in TRS19.
 

==SetCameraFlags==
{{MethodHeader|public native void SetCameraFlags(int flags)}}
;Parameter
*'''flags''' integer value defining what the user is permitted to do with the game camera.
;Returned Value
*None
;Syntax
// User is permitted to select External or Tracking views only.
World.SetCameraFlags(World.CAMERA_EXTERNAL | World.CAMERA_TRACKING);
;Notes
*Use any combination of [[#Camera_Flags|Camera Flags]] and [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetCameraMode==
{{MethodHeader|public void SetCameraMode(int mode)}}
;Parameter
*'''mode''' = Camera mode to select.
;Returned Value
*None
;Syntax
World.SetCameraMode(World.CAMERA_TRACKING);
;Notes
*Use one of the [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetEditingCamera==
{{MethodHeader|public void SetEditingCamera([[Class GameObject|GameObject]] actor, bool bIsActorEditingCamera)}}
;Parameter
*'''actor''' = The script who is intended to edit the camera position.
*'''bIsActorEditingCamera''' = True to begin editing, or False to end the editing operation.
;Returned Value
*None
;Syntax
World.SetEditingCamera(myScript, true);
;Notes
*Hints to the caching systems that the camera position is in the process of being changed. This may reduce the amount of streaming that will occur until the change is complete.
*This is intended for use-cases where the decision to move the camera happens in advance of the actual call to [[#SetCamera|SetCamera()]] or etc., for example when the new camera target needs to be streamed in first.
*There is no advantage in calling this unless your code then sleeps/waits before undoing the call.
*It is not required to call this before using SetCamera() etc.
*A boolean state is stored per actor; multiple calls to enable editing on a single actor do not need to be matched to multiple calls to disable editing.
*It is counterproductive to call this when transitioning the camera over a short distance (ie. where the source and target locations can see each other). If jumping to a new location, followed by a visual camera transition at the new location, camera editing may be enabled around the target-selection for the jump, and the jump itself, but should be disabled before proceeding with the transition.
*Added in TRS19?
 

==SetGameDate==
{{MethodHeader|public void SetGameTime(int year, int month, int date)}}
;Parameters
*'''year''' = The year to set (1970-2038)
*'''month''' = The month to set (1-12)
*'''day''' = The day to set (1-31)
;Returned Value
*None
;Syntax
World.SetGameTime(2000, 12, 25); // sets date to 25 December 2000
;Notes
*In multiplayer, this will only succeed on the server.
*Added in ...?
 

==SetGameTime==
{{MethodHeader|public void SetGameTime(float time)}}
;Parameters
*'''time''' = new gane time to set.
;Returned Value
*None
;Syntax
World.SetGameTime(0.5); // sets time to midnight
;Notes
*Game time is normalised to a value between 0.0 and 1.0
*0.0 = midday
*0.25 = 6 p.m.
*0.5 = midnight
*0.75 = 6 a.m.
*1.0 = midday again
*Use the [[#Time_Values|Time Value]] constants to convert human readable times to normalised values.
 

==SetGameTimeRate==
{{MethodHeader|public native void SetGameTimeRate(float rate)}}
;Parameters
*'''rate''' = New time rate to set.
;Returned Value
*None
;Syntax
World.SetGameTimeRate(World.TIME_RATE_8X); // sets game time to advance by 8 minutes per minute of real world time.
;Notes
*Use one of the [[#Time_Rate_Constants|Time Rate Constants]] to define the parameter.
*In multiplayer, this will only succeed on the server.
 

==SetGoodWeatherFog==
{{MethodHeader|public obsolete native void SetGoodWeatherFog(float distance)}}
;Parameters
*'''distance''' = Good weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetGoodWeatherFog(0.5);
;Notes
*Obsolete in TRS19
 

==SetGroundDrawDistance==
{{MethodHeader|public obsolete native void SetGroundDrawDistance(float distance)}}
;Parameters
*'''distance''' = Ground draw distance in metres.
;Returned Value
*None
;Syntax
World.SetGroundDrawDistance(1000.0);
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==SetLayerVisible==
{{MethodHeader|public native void IsLayerVisible(string layerName, bool visible)}}
;Parameter
*layerName = Name of the layer to check
*visible = Whether to set the layer visible or not
;Returned Value
*None
;Syntax
World.IsLayerVisible("MyLayer", False);
;Notes
*Show/Hide a route/session layer.
*In multiplayer, this will only succeed on the server.
*Added in ...?
 

==SetSceneryDrawDistance==
{{MethodHeader|public obsolete native void SetSceneryDrawDistance(float distance)}}
;Parameters
*'''distance''' = unused.
;Returned Value
*None
;Notes
* Does nothing. Included for script compatibility only.
 

==SetTargetObserver==
{{MethodHeader|public void SetTargetObserver([[Class GameObject|GameObject]] observer)}}
;Parameters
*'''observer''' = The game object to receive targeting messages.
;Returned Value
*None
;Syntax
SetTargetObserver(self);
;Notes
* It is unlikely a script programmer would ever need to use this method.
* Causes the specified object to receive "Track", "LeftClick" messages when a track is clicked. Causes the specified object to receive "Interface-Event", "Left-Click" messages when a targetable MapObject is clicked. May cause the functionality of a left mouse click to change from what the user is expecting, so should be used with caution. Used in modal scripts to allow the user to indicate a location for train placement, etc. As there is only a single observer at any given time, the script must take care to only call this function when entering placement mode at the user's request.
 

==SetWeather==
{{MethodHeader|public native void SetWeather(int type, int changeability)}}
;Parameters
*'''type''' = Weather conditions as defined by one of the [[#Weather_Type_Constants|Weather Type Constants]].
*'''change''' = Weather variation as defined by one of the [[#Weather_Changeability_Constants|Weather Changeability Constants]].
;Returned Value
*None
;Syntax
World.SetWeather(World.WEATHER_TYPE_HEAVY_SNOW,World.WEATHER_CHANGEABILITY_EXTREME); // April in Paris.
;Notes
 

==SetWorldEditModeEnabled==
{{MethodHeader|public native bool SetWorldEditModeEnabled(int editFlags, bool enable)}}
;Parameters
*'''editFlags''' = Bitmask specifying which modes to alter, see PERMIT_EDIT_*
*''cameraMode''' = Whether to enable or disable the mode
;Returned Value
*Whether the change was completely successful
;Syntax
World.SetWorldEditModeEnabled(World.PERMIT_EDIT_TRAINS | World.PERMIT_EDIT_CONSISTS, True); // Enable player editing of trains and consists
;Notes
*This does not affect scripts which may alter the world, only the availability of the player world editing tools (i.e, the Surveyor tabs).
*Added in TRS19?
 

==SynchronouslyLoadGameObjectByID==
{{MethodHeader|public [[Class GameObject|GameObject]] SynchronouslyLoadGameObjectByID([[Class GameObjectID|GameObjectID]] objectID)}}
;Parameters
*'''objectID''' = The ID of the object to find.
;Returned Value
* The object, if it exists.
;Syntax
GameObject my_object = World.SynchronouslyLoadGameObjectByID(objectID);
if (my_object Interface.Print("Object exists and has been loaded if required");
;Notes
*This function is usable only by script 'thread' functions and will throw an exception if called incorrectly.
*Added in TRS19
 

==UpdatePositionToGroundHeight==
{{MethodHeader|public native bool UpdatePositionToGroundHeight([[Class WorldCoordinate|WorldCoordinate]] position)}}
;Parameters
*'''position''' (in, out) = Position object to update with the ground height at it's location
;Returned Value
* True if the ground position was updated
;Syntax
if (World.UpdatePositionToGroundHeight(position) Interface.Print("Position was updated");
;Notes
*This updates the input ''position'' object with the ground height at that location.
*This process may fail if the ground data at the specified location is not currently loaded.
*Added in TRS19?
 

==UpdatePositionToSurfaceHeight==
{{MethodHeader|public native bool UpdatePositionToSurfaceHeight([[Class WorldCoordinate|WorldCoordinate]] position)}}
;Parameters
*'''position''' (in, out) = Position object to update with the water height at it's location
;Returned Value
* True if the ground position was updated
;Syntax
if (World.UpdatePositionToGroundHeight(position) Interface.Print("Position was updated");
;Notes
*This updates the input ''position'' object with the water height at that location. If no water is present, the position is adjusted to the ground height.
*This process may fail if the ground data at the specified location is not currently loaded.
*Added in TRS19?
 

==UserSetCamera==
{{MethodHeader|public native bool UserSetCamera([[Class GameObject|GameObject]] target)}}
;Parameters
*'''target''' = GameObject to set focus to.
;Returned Value
*True if successful, false otherwise.
;Syntax
World.UserSetCamera(Router,GetGameObject("Junction 5"));
;Notes
 

==UserSetCameraMode==
{{MethodHeader|public native void UserSetCameraMode(int mode)}}
;Parameters
*'''mode''' = One of the [[#Camera_View_Modes|Camera View Modes]]
;Returned Value
*None
;Syntax
World.UserSetCameraMode(World.CAMERA_ROAMING); // switches to roaming view if permitted.
;Notes
*This method respects the current [[#Camera_Flags|Camera Flag]] settings, disallowing any change which the flags do not permit.
 

==UserSetCameraPosition==
{{MethodHeader|public native bool UserSetCamera([[Class WorldCoordinate|WorldCoordinate]] camPos)}}
;Parameters
*'''camPos''' = World coordinates to set camera to
;Returned Value
*True if successful, false otherwise.
;Syntax
World.UserSetCamera(Router,GetGameObject("Junction 5"));
;Notes
* For camera modes which do not need to target specific objects, this allows the camera to be set to an arbitrary world position.
*Added in TRS19?
 

==Categories==
[[Category:Script Class]]

Class AssetCategory

2020-12-28T16:22:21Z

Danny252: Created page with "*API Hierarchy **AssetCategory AssetCategory is a static class used to define the types of searchable categories for assets and objects..."

*[[TrainzScript Library Reference|API Hierarchy]]
**AssetCategory
 
AssetCategory is a static class used to define the types of searchable categories for assets and objects.

Cateogory codes may also be combined to narrow your search by using the semicolon (;) character. For example you can search for grass/tree splines by using "Flora;Spline". You can also broaden a search to include multiple category lists using the vertical bar (|) character. Each vertical bar acts as an OR operator on the lists. For example you can search for flora or fauna splines using "Spline;Flora|Spline;Fauna"(i.e. *NOT* "Spline;Flora|Fauna" which would match all flora splines, and any fauna tagged object/spline/etc).

Content creators can also add custom category codes to their assets via the category-class tag. Such codes are prefixed with the '#' character (e.g. "#CITY"). These may be used freely to allow you to tag and search for assets which may support a specific 3rd party library, feature, etc.

Note that there may exist other category codes which are not listed here, but use of those is considered unsupported and may break without notice in any future version of Trainz.
 

==Constants==
*These constants are used to define various values and can be used as mnenomics.
*These constants can be used to search for assets in the game world via [[Class World#GetNamedObjectList|World.GetNamedObjectList()]].
*If accessed from scripts the values must be prefixed ''AssetCategory.'', for example:
AsyncObjectSearchResult search_result = World.GetNamedObjectList(AssetCategory.Locomotive);

 

===Map Object, Track, and Spline Constants===
----
{{TableHeader|width=95%|margin=15px}}
|width=375|public define string Bridge = "BRG"
|-
|public define string Building = "BD"
|-
|public define string Crossing = "FIXD;CROS"
|-
|public define string Fauna = "FA"
|-
|public define string FixedTrack = "FIXD"
|-
|public define string Flora = "FL"
|-
|public define string Industry = "IND"
|-
|public define string InterlockingTower = "IT"
|-
|public define string Junction = "TO;?WX"
|-
|public define string Mesh = "CMP;MESH"
|-
|public define string People = "PP"
|-
|public define string Road = "RD"
|-
|public define string Scenery = "SY"
|-
|public define string SceneryWithTrack = "SWT"
|-
|public define string Signal = "TO;?WA"
|-
|public define string Spline = "SPLN"
|-
|public define string Track = "TK"
|-
|public define string Trackmark = "?WM"
|-
|public define string TrackBridge = "TK;BRG"
|-
|public define string TrackTunnel = "TK;TUN"
|-
|public define string TrackObject = "TO"
|-
|public define string Trigger = "?WT"
|-
|public define string Tunnel = "TUN"
|-
|public define string Turntable = "FIXD;TURN"
|-
|public define string RoadVehicle = "VE"
|}

===Train Category Constants===
----
{{TableHeader|width=95%|margin=15px}}
|width=375|public define string Caboose = "TR;TV;CAB"
|-
|public define string Consist = "CON"
|-
|public define string Locomotive = "TR;TV;LOCO"
|-
|public define string MailTrainCar = "TR;TV;MAIL"
|-
|public define string MonorailVehicle = "TR;TV;MNR"
|-
|public define string PassengerTrainCar = "TR;TV;PAX"
|-
|public define string RollingStock = "TR;TV;ROLL"
|-
|public define string Tram = "TR;TV;TRM"
|-
|public define string TrainCar = "TR;TV"
|-
|public define string TrainCarDiesel = "TR;TV;DIES"
|-
|public define string TrainCarElectric = "TR;TV;ELEC"
|-
|public define string TrainCarSteam = "TR;TV;STEM"
|-
|public define string TrainCarTender = "TR;TV;TEND"
|-
|public define string TrainCarComponent = "TR;CMP"
|-
|public define string TrainEngine = "TR;CMP;ESPC"
|}
 

===Route and Session Category Constants===
----
{{TableHeader|width=95%|margin=15px}}
|width=375|public define string Region = "REGN"
|-
|public define string Route = "RT"
|-
|public define string SaveGame = "SG"
|-
|public define string Session = "SS"
|-
|public define string SessionArcade = "SS;ARCD"
|-
|public define string SessionTutorial = "SS;TUT"
|-
|public define string TestTrackTest= "TC"
|}

TrainzScript Library Reference

2020-12-28T16:01:36Z

Danny252: Add AssetCategory

The following is a list of all classes provided by Auran for use with the Trainz game runtime environment. Some of these classes may not be available from other runtime environments. Please see the [[TrainzScript Language Reference]] for a list of the "core" TrainzScript classes that are present in all runtime environments. This list may not be complete, but will be extended in future.

''Classes marked with an asterisk have no parent class.''

*[[class AssetCategory|AssetCategory]] *
*[[class GSObject|GSObject]] *
**[[class Asset|Asset]]
**[[class DLCInfo|DLCInfo]]
**[[class GameObjectID|GameObjectID]]
**[[class GameObject|GameObject]]
***[[class AsyncObjectSearchResult|AsyncObjectSearchResult]]
***[[class AsyncTrainzAssetSearchObject|AsyncTrainzAssetSearchObject]]
***[[class Browser|Browser]]
***[[class BrowserInterface|BrowserInterface]]
***[[class CabinControl|CabinControl]]
***[[class ConstructorsBase|ConstructorsBase]]
****[[class Constructors|Constructors]]
***[[class DLCStore|DLCStore]]
***[[class DriverCommand|DriverCommand]]
***[[class DriverCommands|DriverCommands]]
***[[class HTMLPropertyHandler|HTMLProprtyHandler]]
***[[class Interface|Interface]]
***[[class InterlockingTowerPath|InterlockingTowerPath]]
***[[class JunctionBaseGameObject|JunctionBaseGameObject]] (Additional parent class: [[class JunctionBase|JunctionBase]] *)
***[[class NavPoints|NavPoints]]
***[[class ChatChannel|ChatChannel]]
***[[class OnlineAccess|OnlineAccess]]
***[[class OnlineGroup|OnlineGroup]]
***[[class Track|Track]]
***[[class TrackCircuitBlock|TrackCircuitBlock]]
***[[class Train|Train]]
***[[class TrainzAssetSearch|TrainzAssetSearch]]
***[[class TrainzGameObject|TrainzGameObject]]
****[[class GameplayMenuBase|GameplayMenuBase]]
*****[[class GameplayMenu|GameplayMenu]]
*****[[class GameplayMenuMobile|GameplayMenuMobile]]
****[[class Library|Library]] (Additional parent class: [[class PropertyObject|PropertyObject]] *)
*****[[class OAChat|OAChat]]
*****[[class Servlet|Servlet]]
*****[[class SessionVariables|SessionVariables]]
*****[[class WaybillManager|WaybillManager]]
****[[class MeshObject|MeshObject]] (Additional parent class: [[class PropertyObject|PropertyObject]] *)
*****[[class Bogey|Bogey]]
*****[[class Cabin|Cabin]]
*****[[class MapObject|MapObject]]
******[[class InterlockingTower|InterlockingTower]]
******[[class SceneryWithTrack|SceneryWithTrack]]
*******[[class Buildable|Buildable]]
********[[class Industry|Industry]]
*********[[class BaseIndustry|BaseIndustry]]
**********[[class GenericPassengerStation|GenericPassengerStation]]
*********[[class BasePortal|BasePortal]]
*********[[class GenericIndustry|GenericIndustry]]
*******[[class Crossing|Crossing]]
*******[[Class_Turntable|TurnTable]]
******[[class Trackside|Trackside]]
*******[[class CarSignal|CarSignal]]
*******[[class Junction|Junction]] (Additional parent class: [[class JunctionBase|JunctionBase]] *)
*******[[class Signal|Signal]]
*******[[class TrackMark|TrackMark]]
*******[[class Trigger|Trigger]]
*******[[class Vehicle|Vehicle]]
********[[class Locomotive|Locomotive]]
****[[class ModulScript|ModulScript]]
*****[[class DriverCharacter|DriverCharacter]]
****[[class ScenarioBehavior|ScenarioBehavior]]
*****[[class ConditionalScenarioBehavior|ConditionalScenarioBehavior]]
*****[[class ScenarioBehaviorTemplate|ScenarioBehaviorTemplate]]
***[[class TrainzScriptBase|TrainzScriptBase]]
****[[class World|World]]
***[[class World1|World1]]
**[[class HTMLBuffer|HTMLBuffer]]
**[[class IndustryTrainController|IndustryTrainController]]
**[[class KUID|KUID]]
**[[class KUIDList|KUIDList]]
**[[class LoadingReport|LoadingReport]]
**[[class Menu|Menu]]
**[[class Permit|Permit]]
**[[class ProductFilter|ProductFilter]]
**[[class ProductQueue|ProductQueue]]
**[[class SecurityToken|SecurityToken]]
**[[class Soup|Soup]]
**[[class StringTable|StringTable]]
**[[class TrackPathDisplay|TrackPathDisplay]]
**[[class TrainTimeTable|TrainTimeTable]]
*[[class GSTrackSearch|GSTrackSearch]] *
*[[class Math|Math]] *
*[[class Router|Router]] *
*[[class Str|Str]] *
*[[class TrainUtil|TrainUtil]] *

=Categories=
[[Category:TrainzScript]]

Class World

2020-12-28T15:10:07Z

Danny252: Add reference links to other classes

*[[TrainzScript Library Reference|API Hierarchy]]
**World
 
*World is a static class used to access various aspects of the Trainz environment.
 

==Constants==
*These constants are used to define various values and can be used as mnenomics.
*If accessed from scripts the values must be prefixed ''World.'', for example:
World.SetWeather(World.WEATHER_TYPE_LIGHT_SNOW,World.WEATHER_CHANGEABILITY_PERIODIC);
 

===Camera View Modes===
----
*These values can be used either to choose the current camera viewing mode through World.[[#SetCameraMode|SetCameraMode()]], or to restrict certain camera modes from being accessed through methods such as World.[[#SetCamera|SetCamera()]].

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_INTERNAL = 1||Internal cabin camera view.
|-
|public define int CAMERA_EXTERNAL = 2||External train camera view
|-
|public define int CAMERA_TRACKING = 4||External tracking camera view.
|-
|public define int CAMERA_ROAMING = 128||Roaming camera view.
|}
 

===Camera Flags===
----
*These flags are used in addition to the Camera Mode Flags to allow or disallow specific camera actions.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_SWITCH_VIEWS = 8||User permitted to swap between the camera views.
|-
|public define int CAMERA_SWITCH_VEHICLES = 16||User permitted to swap vehicles within the current train.
|-
|public define int CAMERA_SWITCH_TRAINS = 32||User permitted to swap to other trains which are in the consist menu.
|-
|public define int CAMERA_LOCKED = 64||User is NOT permitted to adjust camera (i.e. zoom, pan etc.).
|-
|public define int CAMERA_NORMAL = * ||Normal camera mode where everything is permitted.
|-
|colspan=2|* NOTE: CAMERA_NORMAL = CAMERA_INTERNAL | CAMERA_EXTERNAL | CAMERA_TRACKING | CAMERA_SWITCH_VIEWS | CAMERA_SWITCH_VEHICLES | CAMERA_SWITCH_TRAINS
|}
 

===Weather Type Constants===
----
*Define the current state of the weather in Trainz.
*A variety of weather conditions are supported and can be changed by using one of these values with the World.[[#SetWeather|SetWeather()]] method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_TYPE_CLEAR = 0||Clear weather, no clouds, rain or snow.
|-
|public define int WEATHER_TYPE_CLOUDY = 1||Cloudy weather, no rain.
|-
|public define int WEATHER_TYPE_DRIZZLE = 2||Drizzle, light rain.
|-
|public define int WEATHER_TYPE_RAIN = 3||Rainy weather.
|-
|public define int WEATHER_TYPE_STORMY = 4||Stormy weather that includes lightning and thunder.
|-
|public define int WEATHER_TYPE_LIGHT_SNOW = 5||Snowing lightly.
|-
|public define int WEATHER_TYPE_MEDIUM_SNOW = 6||Medium level snow fall.
|-
|public define int WEATHER_TYPE_HEAVY_SNOW = 7||Heavy snow fall.
|}
 

===Weather Changeability Constants===
----
*Define the changeability settings for the weather.
*Weather changeability refers to variability of weather conditions rather than to a specific weather type.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_CHANGEABILITY_NONE = 0||Weather remains static.
|-
|public define int WEATHER_CHANGEABILITY_PERIODIC = 1||Periodic changes in weather.
|-
|public define int WEATHER_CHANGEABILITY_EXTREME = 2||Extreme and frequent changes in weather.
|}
 

===Time Values===
----
*Time constants defined in seconds.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float TIME_SECOND = 1.0f||One second.
|-
|public define float TIME_MINUTE = TIME_SECOND * 60.0f||One minute, 60.0 seconds.
|-
|public define float TIME_HOUR = TIME_MINUTE * 60.0f||One hour, 60.0 minutes, 3600.0 seconds.
|-
|public define float TIME_DAY = TIME_HOUR * 24.0f||One day, 24 hours, 1440.0 minutes, 86400.0 seconds.
|}
 

===Time Rate Constants===
----
*Values that define the time rates relative to normal time.
*These constants can be used to set the time rate that Trainz runs out through the World.[[#SetGameTimeRate|SetGameTimeRate()]] method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int TIME_RATE_1X = 0||Real time (i.e. time in Trainz passes at the same rate as in the real world)
|-
|public define int TIME_RATE_2X = 1||Time passes at twice normal speed.
|-
|public define int TIME_RATE_4X = 2||
|-
|public define int TIME_RATE_8X = 3||
|-
|public define int TIME_RATE_16X = 4||
|-
|public define int TIME_RATE_32X = 5||
|-
|public define int TIME_RATE_60X = 6||
|-
| public define int TIME_RATE_120X = 7||
|-
| public define int TIME_RATE_240X = 8||
|-
|public define int TIME_RATE_360X = 9||
|-
|public define int TIME_RATE_480X = 10||
|-
|public define int TIME_RATE_720X = 11||
|-
|public define int TIME_RATE_960X = 12||
|-
|public define int TIME_RATE_1200X = 13||
|-
|public define int TIME_RATE_1440X = 14||
|}
 

===Trainz Modules===
----
*Trainz module mode constants.
*These values define the various module environments that Trainz can be in.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NO_MODULE = 0||Trainz not running in a module.
|-
|public define int SURVEYOR_MODULE = 1||Trainz is currently running in Surveyor.
|-
|public define int DRIVER_MODULE = 2||Trainz is currently running in Driver.
|}
 

==Related Messages==
* [[TrainzScript Message Reference]] 
* [[Camera Messages]] 
* [[Interface Messages]] 
* [[ModuleInit Message]] 
 

==AddDriverCharacter==
{{MethodHeader|public native [[Class DriverCharacter|DriverCharacter]] AddDriverCharacter([[Class Asset|Asset]] driverCharacterAsset)}}
;Parameters
*'''driverCharacterAsset''' = Asset containing character to be added.
;Returned Value
*Reference to the DriverCharacter if successful, null otherwise.
;Syntax
DriverCharacter Casey = World.AddDriverCharacter(CaseyJones);
;Notes
 

==AddDriverCommand==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]] AddDriverCommand([[Class Asset|Asset]] driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.AddDriverCommand(accelerate);
;Notes
 

==CreateBehavior==
{{MethodHeader|public native [[Class ScenarioBehavior|ScenarioBehavior]] CreateBehavior([[Class KUID|KUID]] kuid, [[Class Soup|Soup]] initialProperties)}}
;Parameters
*'''kuid''' = KUID of scenario.
'''initialProperties''' = Soup object containing initial properties for scenario.
;Returned Value
*Reference to the ScenarioBehavior created if successful, null otherwise.
;Syntax
ScenarioBehavior scenario = World.CreateBehavior(scenarioAsset, scenarioSoup);
;Notes
*The returned ScenarioBehavior object may be ended by releasing all references to it (resetting all references to null).
 

==CreateTrain==
{{MethodHeader|public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, string trackmarkName, bool direction) public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class TrackMark|TrackMark]] trackmark, bool direction) public native [[Class Train|Train]] CreateTrain([[Class KUID|KUID]][ ] consist, [[Class Buildable|Buildable]] buildable, string trackName, float position, bool direction)}}
;Parameters
*'''consist''' = An array of vehicle KUIDs used to describe the required Train object.
*'''trackmarkName''' = Name of Trackmark at which the consist is to be formed.
*'''buildable''' = Buildable on which the consist is to be formed.
*'''trackName''' = Name of track within Buildable object.
*'''position''' = Distance at which the Train is to be placed relative to the start of the track.
*'''trackmark''' = Reference to Trackmark at which the consist is to be formed.
*'''direction''' = Orientation of Train relative to direction of track or trackmark.
;Returned Value
*Reference to the Train created if successful, null otherwise.
;Syntax
Train train = World.CreateTrain(consist, buildable, "Track 1", 10.0, true);
;Notes
*These methods create a train from a list of vehicles in a consist array.
*Depending on the variant of the method used, the train can be created at a Trackmark, specified by name or reference, or at a Buildable or Industry object.
*It is the responsibility of the script programmer to ensure that sufficient track exists at the given location to allow the train to be created.
 

==DeleteTrain==
{{MethodHeader|public native void DeleteTrain([[Class Train|Train]] train)}}
;Parameters
*'''train''' = train to be deleted from map.
;Returned Value
*None
;Syntax
World.DeleteTrain(flyingScotsman);
;Notes
*Once a train has been deleted, care should be taken to avoid using its reference.
 

==DeleteVehicle==
{{MethodHeader|public native void DeleteVehicle([[Class Vehicle|Vehicle]] vehicle)}}
;Parameters
*'''vehicle''' = vehicle to be deleted from its train.
;Returned Value
*None
;Syntax
World.DeleteVehicle(vehicles[vehicles.size()-1]);
;Notes
*Use Train.GetVehicles() to obtain an array of vehicles for a given train.
*Use Vehicle.GetMyTrain() to obtain a train reference for a given vehicle.
 

==FindAsset==
{{MethodHeader|public native [[Class Asset|Asset]] FindAsset([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of Asset to return.
;Returned Value
*Given a valid KUID parameter, this method return an Asset reference if successful, null otherwise.
;Syntax
Asset asset = World.FindAsset(kuid);
;Notes
*See also Asset.FindAsset()
 

==FindDriverCommand==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]] FindDriverCommand([[Class Asset|Asset]] driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.FindDriverCommand(accelerate);
;Notes
 

==GetAssetList==
{{MethodHeader|public native [[Class Asset|Asset]][ ] GetAssetList(string kind)}}
;Parameters
*'''kind''' = String representing the Kind of asset to return.
;Returned Value
*A list of all assets of the given ''kind''
;Syntax
Asset[] Libraries = World.GetAssetList("Library");
;Notes
*All installed assets of the given ''kind'' are returned, irrespective of whether or not they are in use on the current map.
 

==GetBadWeatherFog==
{{MethodHeader|public native float GetBadWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Bad weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetBadWeatherFog();
;Notes
 

==GetBehaviors==
{{MethodHeader|public native [[Class ScenarioBehavior|ScenarioBehavior]][ ] GetBehaviors(void)}}
;Parameters
*None
;Returned Value
*A list of top-level behaviors or rules on the currently loaded route.
;Syntax
ScenarioBehavior[] rules = World.GetBehaviors();
;Notes
 

==GetCameraPositionX==
{{MethodHeader|public native float GetCameraPositionX(void)}}
;Parameters
*None
;Returned Value
*X Coordinate of the current camera position.
;Syntax
float X = World.GetCameraPositionX();
*Notes
 

==GetCameraPositionY==
{{MethodHeader|public native float GetCameraPositionY(void)}}
;Parameters
*None
;Returned Value
*Y Coordinate of the current camera position.
;Syntax
float Y = World.GetCameraPositionY();
*Notes
 

==GetCameraPositionZ==
{{MethodHeader|public native float GetCameraPositionZ(void)}}
;Parameters
*None
;Returned Value
*Z Coordinate of the current camera position.
;Syntax
float Z = World.GetCameraPositionZ();
*Notes
 

==GetCurrentModule==
{{MethodHeader|public native int GetCurrentModule(void)}}
;Parameters
*None
;Returned Value
*An integer representing the current Trainz module.
;Syntax
int module = World.GetCurrentModule();
;Notes
* See [[#Trainz Modules|Trainz Modules]] for details of the constants associated with this method.
* See [[ModuleInit Message]] for further details.
 

==GetDriverCharacterList==
{{MethodHeader|public native [[Class DriverCharacter|DriverCharacter]][ ] GetDriverCharacterList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCharacter objects installed in the current world.
;Syntax
DriverCharacter[] drivers = World.GetDriverCharacterList();
;Notes
 

==GetDriverCommandList==
{{MethodHeader|public native [[Class DriverCommand|DriverCommand]][ ] GetDriverCommandList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCommand objects installed in the current world.
;Syntax
DriverCommand[] commands = World.GetDriverCommandList();
;Notes
 

==GetGameTime==
{{MethodHeader|public native float GetGameTime(void)}}
;Parameters
*None
;Returned value
*Current game time.
;Syntax
float Now = World.GetGameTime();
;Notes
*The returned time is normalised to a value between 0.0 and 1.0
*0.0 = midday.
*0.5 = midnight
*Use the [[#Time_Values|Time Value]] constants to convert the normalised values to human readable times.
 

==GetGoodWeatherFog==
{{MethodHeader|public native float GetGoodWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Good weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetGoodWeatherFog();
;Notes
 

==GetGroundDrawDistance==
{{MethodHeader|public native float GetGroundDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Ground draw distance in metres.
;Syntax
float dist = World.GetGroundDrawDistance();
;Notes
 

==GetIndustryList==
{{MethodHeader|public native [[Class GameObject|GameObject]][ ] GetIndustryList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the Industry objects for the current route.
;Syntax
GameObject[] Industries = World.GetIndustryList();
;Notes
*This function is obsolete and should not be used.
 

==GetJunctionList==
{{MethodHeader|public native [[Class Junction|Junction]][ ] GetJunctionList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackside junction objects for the current route.
;Syntax
Junction[] junctions = World.GetJunctionList();
;Notes
*This function is obsolete and should not be used.
*Junction objects attached to fixed track junctions are not returned by this method.
 

==GetLibrary==
{{MethodHeader|public native [[Class Library|Library]] GetLibrary([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of script library asset to load.
;Returned Value
*A reference to the script library asset if successful, null otherwise.
;Syntax
Library codelib = World.GetLibrary(LibraryKUID);
;Notes
*The [[Class Library|Library]] asset is initialised when this method is first called in a session.
*Since only one instance can exist, subsequent calls return a reference to the existing Library object.
*See [[Class Library|Library]] for notes on how to use this method.
 

==GetSceneryDrawDistance==
{{MethodHeader|public native float GetSceneryDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Undefined.
;Notes
*Included for legacy script compatibility only. Has no effect.
 

==GetSeconds==
{{MethodHeader|public native float GetSeconds(void)}}
;Parameters
*None
;Returned Value
*The current value of a floating point number incrementing once per second in real time.
;Syntax
float start = World.GetSeconds();
// do stuff
float finish = World.GetSeconds();
float period = finish - start;
;Notes
*Each call will return a float value containing the current value of an internal counter.
*Subtracting a later value from a value saved at an earlier call will enable the delay between the two calls to be established.
 

==GetSignalList==
{{MethodHeader|public native [[Class Signal|Signal]][ ] GetSignalList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the signal objects for the current route.
;Syntax
Signal[] signals = World.GetSignalList();
;Notes
*This function is obsolete and should not be used.
 

==GetStringTable==
{{MethodHeader|public native [[Class StringTable|StringTable]] GetStringTable(void)}}
;Parameters
*None
;Returned Value
*The StringTable for the current session.
;Syntax
StringTable data = World.GetStringTable();
;Notes
 

==GetSurveyorSavedConsist==
{{MethodHeader|public native [[Class Soup|Soup]] GetSurveyorSavedConsistList(string name)}}
;Parameters
*'''name''' = Name of the consist to retrieve.
;Returned Value
*Returns a Soup definition of the named consist if it exists, null otherwise.
;Syntax
Soup consist = World.GetSurveyorSavedConsist("Brighton Belle");
;Notes
*Remember that the returned data is in a Soup format, which is not the same thing as a Train.
*TrainUtil.CreateTrainFormSoup() can be used to create a train from the returned Soup.
*This method only works in Surveyor.
 

==GetSurveyorSavedConsistList==
{{MethodHeader|public native string[ ] GetSurveyorSavedConsistList()}}
;Parameters
*None
;Returned Value
*An array of names of all the saved consist objects in Surveyor.
;Syntax
string[] consists = World.GetSurveyorSavedConsistList();
;Notes
*This method only works in Surveyor.
 

==GetTrackmarkList==
{{MethodHeader|public native [[Class TrackMark|TrackMark]][ ] GetTrackmarkList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackmark objects for the current route.
;Syntax
Trackmark[] trackmarks = World.GetTrackmarkList();
;Notes
*This function is obsolete and should not be used.
 

==GetTrainList==
{{MethodHeader|public native [[Class Train|Train]][ ] GetTrainList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trains for the current route.
;Syntax
Train[] trains = World.GetTrainList();
;Notes
*This function is obsolete and should not be used.
 

==GetTrainzBuild==
{{MethodHeader|public native int GetTrainzBuild(void)}}
;Parameters;
*None
;Returned Value
*Gets the current build number of Trainz.
;Syntax
int build = World.GetTrainzBuild();
;Notes
*The value returned corresponds to the build number you can see in the bottom-right side of the main Trainz menu screen.
 

==GetTrainzVersion==
{{MethodHeader|public native float GetTrainzVersion(void)}}
;Parameters
*None
;Returned Value
*The TRS version number.
;Syntax
float version = World.GetTrainzVersion();
;Notes
*The value returned corresponds to the version number of Content manager (for example 4.6).
 

==GetTriggerList==
{{MethodHeader|public native [[Class Trigger|Trigger]][ ] GetTriggerList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trigger objects for the current route.
;Syntax
Trigger[] triggers = World.GetTriggerList();
;Notes
*This function is obsolete and should not be used.
*This method does not return scenery triggers, ie those attached to SceneryWithTrack objects and their descendants.
 

==GetVehicleList==
{{MethodHeader|public native [[Class Vehicle|Vehicle]][ ] GetVehicleList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the vehicles in the current route.
;Syntax
Vehicle[] vehicles = World.GetVehicleList();
;Notes
*This function is obsolete and should not be used.
 

==GetWeatherChangeability==
{{MethodHeader|public native int GetWeatherChangeability(void)}}
;Parameter
*None
;Returned Value
*One of the [[#Weather_Changeability_Constants|Weather Changeability Constants]] denoting the variability of weather conditions.
;Syntax
int variability = World.GetWeatherChangeability();
;Notes
 

==GetWeatherType==
{{MethodHeader|public native int GetWeatherType(void)}}
;Parameter
*None
;Returned Value
*One of the [[#Weather_Type_Constants|Weather Type Constants]] denoting the current weather conditions.
;Syntax
int weather = World.GetWeatherType();
;Notes
 

==LoadMap==
{{MethodHeader|public native bool LoadMap([[Class KUID|KUID]] kuid)}}
;Parameters
*'''kuid''' = KUID of map to load.
;Returned Value
*True if successful, false otherwise.
;Syntax
if (World.LoadMap(mapKUID) Interface.Print("Map loaded OK");
else Interface.Print("Map load failed");
;Notes
 

==Play2DSound==
{{MethodHeader|public float Play2DSound([[Class Asset|Asset]] asset, string wave)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
;Returned Value
* Undefined.
;Syntax
// Play the sound and continues script execution.
World.Play2DSound(soundAsset,"sounds/allaboard.wav");
// Wait until sound has completed before continuing (pre-TS12 only!)
Sleep(World.Play2DSound(soundAsset,"sounds/allaboard.wav"));
;Notes
*Plays a ''.wav" sound file from the given asset's folder.
*The sound is non directional and can be mono or stereo.
*This method does not return after the sound has finished playing, it returns with the length of the sound as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
 

==PlaySound==
{{MethodHeader|public native float PlaySound     ([[Class Asset|Asset]] asset, string wave, float vol, float near, float far, [[Class GameObject|GameObject]] target, string pt)     ([[Class Asset|Asset]] asset, string wave, float vol, float near, float far, [[Class GameObject|GameObject]] target, string pt, bool loop)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
*'''vol''' = Volume level to play the sound at (0 to 1)<- These values taken from TRS2019 world.gs file comments
*'''near''' = Distance from the target asset at which the sound will be played at maximum volume.
*'''far''' = Distance from the target asset at which the sound will become inaudible.
*'''target''' = GameObject to which the sound will be attached if a 3d sound is required, null for 2D.
*'''pt''' = Name of attachment point in the target object if a 3d sound is required, null for 2D.
*'''loop''' = (Optional) If true the sound will loop continuously.
;Returned Value
* Sound length in seconds for Trainz before TS12
* Undefined for TS12 and TANE
;Syntax
// Play the sound and continues script execution.
World.PlaySound(soundAsset,"sounds/allaboard.wav",1.0,10.0,100.0,Station,"a.loudspeaker");
// Wait until sound has completed before continuing (pre-TS12 only!)
Sleep(World.PlaySound(soundAsset,"sounds/allaboard.wav",1000.0,10.0,100.0,Station,"a.loudspeaker");
;Notes
*Plays a ''.wav'' sound file from the given asset's folder.
*If the sound is to be directional a mono sound file is required.
*This method does not return after the sound has finished playing: it returns as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
*If you want to wait for the sound to complete playing before moving on, wrap the PlaySound() call up in a Sleep() call. '''Note!''' This works only in Trainz versions before TS12. For newer versions, TS12 and TANE, you can hard-code the duration of the sound, or store it in the extensions container of the config.txt file.
*The sound volume will be at a maximum for a camera position at or less than the value of the ''near'' parameter and will reduce with distance until the hearing position reaches ''far'', when the sound will be inaudible.
 

==RemoveDriverCharacter==
{{MethodHeader|public native void RemoveDriverCharacter([[Class DriverCharacter|DriverCharacter]] driver)}}
;Parameters
*'''driver''' = DriverCharacter to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCharacter(dave);
;Notes
 

==RemoveDriverCommand==
{{MethodHeader|public native void RemoveDriverCommand([[Class DriverCommand|DriverCommand]] command)}}
;Parameters
*'''command''' = DriverCommand to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCommand(driverCommand);
;Notes
 

==SetBadWeatherFog==
{{MethodHeader|public native void SetBadWeatherFog(float distance)}}
;Parameters
*'''distance''' = Bad weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetBadWeatherFog(0.5);
;Notes
 

==SetCamera==
{{MethodHeader|public native bool SetCamera([[Class MapObject|MapObject]] focus) public native void SetCamera([[Class Junction|Junction]] focus) public native void SetCamera([[Class Vehicle|Vehicle]] focus, int cameraMode) public native void SetCamera([[Class Train|Train]] focus, int cameraMode)}}
;Parameters
*'''focus''' = Object on which the camera is to be focused.
*''cameraMode''' = One of the [[#Camera_View_Modes|Camera View Mode]] constants defining the view which should be assigned to the camera.
;Returned Value
*The first variant returns a boolean to indicate success or failure.
*Remaining variants do not return a value
'Syntax
World.SetCamera(train.GetVehicles[0],World.CAMERA_TRACKING); // sets the camera to track the first vehicle in the train.
 

==SetCameraAngle==
{{MethodHeader|public void SetCameraAngle(int yaw, int pitch, float radius)}}
;Parameters
*'''yaw''' = Camera rotation in degrees, 90 is a direct front view.
*'''pitch''' = Camera angle relative to the horizon, 0 is horizontal, 90 points vertically upwards.
*'''radius''' = Distance in metres to the object in focus.
;Returned Value
*None
;Syntax
World.SetCameraAngle(90,0,25); // Sets the camera to a direct frontal view at 25 metres from the currently focused object.
;Notes
*''Radius'' is measured from the object origin point (0,0,0).
 

==SetCameraFlags==
{{MethodHeader|public native void SetCameraFlags(int flags)}}
;Parameter
*'''flags''' integer value defining what the user is permitted to do with the game camera.
;Returned Value
*None
;Syntax
// User is permitted to select External or Tracking views only.
World.SetCameraFlags(World.CAMERA_EXTERNAL | World.CAMERA_TRACKING);
;Notes
*Use any combination of [[#Camera_Flags|Camera Flags]] and [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetCameraMode==
{{MethodHeader|public void SetCameraMode(int mode)}}
;Parameter
*'''mode''' = Camera mode to select.
;Returned Value
*None
;Syntax
World.SetCameraMode(World.CAMERA_TRACKING);
;Notes
*Use one of the [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetGameTime==
{{MethodHeader|public void SetGameTime(float time)}}
;Parameters
*'''time''' = new gane time to set.
;Returned Value
*None
;Syntax
World.SetGameTime(0.5); // sets time to midnight
;Notes
*Game time is normalised to a value between 0.0 and 1.0
*0.0 = midday.
*0.5 = midnight
*Use the [[#Time_Values|Time Value]] constants to convert human readable times to normalised values.
 

==SetGameTimeRate==
{{MethodHeader|public native void SetGameTimeRate(float rate)}}
;Parameters
*'''rate''' = New time rate to set.
;Returned Value
*None
;Syntax
World.SetGameTimeRate(World.TIME_RATE_8X); // sets game time to advance by 8 minutes per minute of real world time.
;Notes
*Use one of the [[#Time_Rate_Constants|Time Rate Constants]] to define the parameter.
 

==SetGoodWeatherFog==
{{MethodHeader|public native void SetGoodWeatherFog(float distance)}}
;Parameters
*'''distance''' = Good weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetGoodWeatherFog(0.5);
;Notes
 

==SetGroundDrawDistance==
{{MethodHeader|public native void SetGroundDrawDistance(float distance)}}
;Parameters
*'''distance''' = Ground draw distance in metres.
;Returned Value
*None
;Syntax
World.SetGroundDrawDistance(1000.0);
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==SetSceneryDrawDistance==
{{MethodHeader|public native void SetSceneryDrawDistance(float distance)}}
;Parameters
*'''distance''' = unused.
;Returned Value
*None
;Notes
* Does nothing. Included for script compatibility only.
 

==SetTargetObserver==
{{MethodHeader|public void SetTargetObserver([[Class GameObject|GameObject]] observer)}}
;Parameters
*'''observer''' = The game object to receive targeting messages.
;Returned Value
*None
;Syntax
SetTargetObserver(self);
;Notes
* Causes the specified object to receive "Track", "LeftClick" messages when a track is clicked. Causes the specified object to receive "Interface-Event", "Left-Click" messages when a targetable MapObject is clicked. May cause the functionality of a left mouse click to change from what the user is expecting, so should be used with caution. Used in modal scripts to allow the user to indicate a location for train placement, etc. As there is only a single observer at any given time, the script must take care to only call this function when entering placement mode at the user's request.
 

==SetWeather==
{{MethodHeader|public native void SetWeather(int type, int changeability)}}
;Parameters
*'''type''' = Weather conditions as defined by one of the [[#Weather_Type_Constants|Weather Type Constants]].
*'''change''' = Weather variation as defined by one of the [[#Weather_Changeability_Constants|Weather Changeability Constants]].
;Returned Value
*None
;Syntax
World.SetWeather(World.WEATHER_TYPE_HEAVY_SNOW,World.WEATHER_CHANGEABILITY_EXTREME); // April in Paris.
;Notes
 

==UserSetCamera==
{{MethodHeader|public native bool UserSetCamera([[Class GameObject|GameObject]] target)}}
;Parameters
*'''target''' = GameObject to set focus to.
;Returned Value
*True if successful, false otherwise.
;Syntax
World.UserSetCamera(Router,GetGameObject("Junction 5"));
;Notes
 

==UserSetCameraMode==
{{MethodHeader|public native void UserSetCameraMode(int mode)}}
;Parameters
*'''mode''' = One of the [[#Camera_View_Modes|Camera View Modes]]
;Returned Value
*None
;Syntax
World.UserSetCameraMode(World.CAMERA_ROAMING); // switches to roaming view if permitted.
;Notes
*This method respects the current [[#Camera_Flags|Camera Flag]] settings, disallowing any change which the flags do not permit.
 

==Categories==
[[Category:Script Class]]

Class TrainUtil

2020-12-28T14:57:28Z

Danny252: Add reference links to other classes

*[[TrainzScript Language Reference|API Hierarchy]]
**TrainUtil
 

*TrainUtil is a static utility class containing a miscellany of methods.
 

==AlreadyThereStr==
{{MethodHeader|public bool AlreadyThereStr(string[ ] target, string search)}}
;Parameters
*'''target''' = Array of strings to search.
*'''search''' = String to look for.
;Returned Value
*Boolean indicating whether or not the string ''search'' exists in the ''target'' array.
;Syntax
string[] target = Str.Tokens("one two three");
bool found = TrainUtil.AlreadyThereStr(target,"four"); // the result will be false
;Notes
*As is usual in Trainzscript string methods the search is case sensitive.
 

==AreInTrain==
{{MethodHeader|public bool AreInTrain([[Class Train|Train]] train, [[Class Vehicle|Vehicle]][ ] vehicles)}}
;Parameters
*'''train''' = Train to search.
*'''vehicles''' = Array of vehicle to look for.
;Returned Value
*True if all of the vehicles in the array are found in the train, false otherwise.
;Syntax
bool allPresent = TrainUtil.AreInTrain(train,vehicles);
;Notes
*See also [[#IsInTrain|IsInTrain()]]
 

==CompareStrLists==
{{MethodHeader|public bool CompareStrLists(string[ ] list1, string[ ] list2)}}
;Parameters
*'''list1,list2''' = String arrays.
;Returned Value
*True if the lists are identical, same strings in each index position, same total count. False otherwise.
;Syntax
bool identical = TrainUtil.CompareStrLists(address1,address2);
;Notes
 

==CreateTrainFromSoup==
{{MethodHeader|public [[Class Train|Train]] CreateTrainFromSoup([[Class Soup|Soup]] trainSoup, string trackmarkName, bool direction)}}
;Parameters
*'''trainSoup''' = Consist definition in the form returned by [[Class World#GetSurveyorSavedConsist|World.GetSurveyorSavedConsist()]].
*'''trackmarkName''' = Name of the trackmark where the train is to be placed.
*'''direction''' = True denotes that the train direction should match that of the trackmark.
;Returned Value
*A reference to the newly created train if successful, null otherwise.
;Syntax
Train train = TrainUtil.CreateTrainFromSoup(BrightonBelle,"Victoria Station",true);
;Notes
*It is the script programmer's responibility to ensure that sufficient track exists.
 

==DoCoupleUp==
{{MethodHeader|public [[Class Train|Train]] DoCoupleUp([[Class Train|Train]] train, [[Class Train|Train]] coupleTo)}}
*'''train''' = First train.
*'''coupleTo''' = Train to couple with.
;Returned Value
*A reference to the newly extended train.
;Syntax
Train newTrain = TrainUtil.DoCoupleUp(train, newSection);
;Notes
 

==DoDecouple==
{{MethodHeader|public [[Class Train|Train]] DoDecouple([[Class Train|Train]] train, int count)}}
;Parameters
*'''train''' = Train reference.
*'''count''' = Number of wagons to detach from the rear of the train.
;Returned Value
*A reference to the remaining consist (front section) if successful, null otherwise.
;Syntax
train = TrainUtil.DoDecouple(train,4); // drop four cars from the rear of the train, ''train'' will be null if this fails.
;Notes
*It is assumed that the train is stopped and already in position.
*The method will wait for the operation to be completed.
 

==GetAfter==
{{MethodHeader|public string GetAfter(string target, string search)}}
;Parameters
*'''target''' = String to operate on.
*'''search''' = String containing delimiter characters.
;Returned Value
*Substring of ''target'' to the right of the characters in ''search''.
;Syntax
string result = TrainUtil.GetAfter("Afternoon", "er"); // result is "noon"
;Notes
*The method starts at the end of the string and works backwards until any of the characters in ''search'' are encountered.
*Once any character in ''search'' is found the substring after that character is returned.
*If ''search'' is not found the result will be an empty string.
 

==GetUpTo==
{{MethodHeader|public string GetUpTo(string target, string search)}}
;Parameters
*'''target''' = String to operate on.
*'''search''' = String containing delimiter characters.
;Returned Value
*Substring of ''target'' to the left of the characters in ''search''.
;Syntax
string result = TrainUtil.GetUpTo("Before noon"," no"); // result is "Before"
;Notes
*The method starts at the beginning of the string and works forwards until any of the characters in ''search'' are encountered.
*Once any character in ''search'' is found the substring before that character is returned.
*If ''search'' is not found the result will be an empty string.
 

==HasPrefix==
{{MethodHeader|public bool HasPrefix(string target, string prefix)}}
;Parameters
*'''target''' = String to operate on.
*'''prefix''' = String containing prefix to search for.
;Returned Value
*True if ''target'' starts with ''prefix'', false otherwise.
;Syntax
bool IsPrefixed = TrainUtil.HasPrefix("ante","antecedent"); // returns true
;Notes
 

==HasSufix==
{{MethodHeader|public bool HasSufix(string target, string suffix)}}
;Parameters
*'''target''' = String to operate on.
*'''suffix''' = String containing suffix to search for.
;Returned Value
*True if ''target'' ends with ''suffix'', false otherwise.
;Syntax
bool IsSuffixed = TrainUtil.HasSufix("dent","antecedent"); // returns true
;Notes
*This will not work if the method identifier is correctly spelled!
 

==IsInTrain==
{{MethodHeader|public bool IsInTrain([[Class Train|Train]] train, [[Class Vehicle|Vehicle]] vehicle)}}
;Parameters
*'''train''' = Train reference.
*'''vehicle''' = Vehicle reference.
;Returned Value
*True if ''vehicle'' is included in ''train'', false otherwise.
;Syntax
bool brakeVanPresent = TrainUtil.IsInTrain(train,brakeVan);
;Notes
*See also [[#AreInTrain|AreInTrain()]]
 

==IsPartTrainInTrigger==
{{MethodHeader|public bool IsPartTrainInTrigger([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, [[Class Trigger|Trigger]] trigger)}}
;Parameters
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''trigger''' = Reference to the trigger to query.
;Returned Value
*True if any part of the train is in the trigger area, false otherwise.
;Syntax
bool arrived = TrainUtil.IsPartTrainInTrigger(me,train,trigger);
;Notes
 

==IsTrainInTrigger==
{{MethodHeader|public bool IsTrainInTrigger([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, [[Class Trigger|Trigger]] trigger)}}
;Parameters
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''trigger''' = Reference to the trigger to query.
;Returned Value
*True if the train is in the trigger area, false otherwise.
;Syntax
bool arrived = TrainUtil.IsTrainInTrigger(me,train,trigger);
;Notes
 

==RandBool==
{{MethodHeader|public bool RandBool(void)}}
;Parameters
*None
;Returned Value
*True or false at random.
;Syntax
if(TrainUtil.RandBool()) DoItAtRandom();
;Notes
 

==RunTurnTable==
Is this still valid?
{{MethodHeader|public void RunTurnTable([[Class GameObject|GameObject]] runningThread, [[Class Train|Train]] train, string turntable)}}
*'''runningThread''' = Thread that called this method.
*'''train''' = Reference to a train.
*'''turntable''' = Name of turntable.
;Returned Value
*None
;Syntax
TrainUtil.RunTurnTable(me,train,"Turntabel 1");
;Notes
*???????
 

==StrSubst==
{{MethodHeader|public string StrSubst(string target, string remove, string replace)}}
;Parameters
*'''target''' = String to operate on.
*'''remove''' = Substring to remove.
*'''replace''' = Replacement substring.
;Returned Value
*Returns the string target with ''replace'' substituted for ''remove'', if the method fails an empty string is returned.
;Syntax
string s = "Gnomes are your friends";
s = TrainUtil.StrSubst(s,"friends","enemies"); // returns "Gnomes are your enemies"
;Notes
*''remove'' must exist as a substring of ''target'', otherwise and empty string will be returned.
*''remove'' and ''replace'' do not have to be the same length.
*Only the first instance of ''remove'' will be substituted.
 

==WaitUntilHas==
Is this still valid?
{{MethodHeader|public void WaitUntilHas([[Class Vehicle|Vehicle]] loco, ShuntTrack tracking)}}
;Parameters
*'''loco''' = Consist locomotive.
*'''tracking''' = Tracking array.
;Returned Value
*None
;Syntax

;Notes
*Waits until all of the vehicles tracked by the tracking array are in the train of the given loco.
 

==Related Methods==

==Categories==
[[Category:Script Class]]

Class World

2020-12-28T14:56:04Z

Danny252: Change link to library reference, not language reference

*[[TrainzScript Library Reference|API Hierarchy]]
**World
 
*World is a static class used to access various aspects of the Trainz environment.
 

==Constants==
*These constants are used to define various values and can be used as mnenomics.
*If accessed from scripts the values must be prefixed ''World.'', for example:
World.SetWeather(World.WEATHER_TYPE_LIGHT_SNOW,World.WEATHER_CHANGEABILITY_PERIODIC);
 

===Camera View Modes===
----
*These values can be used either to choose the current camera viewing mode through World.SetCameraMode(), or to restrict certain camera modes from being accessed through methods such as World.SetCamera().

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_INTERNAL = 1||Internal cabin camera view.
|-
|public define int CAMERA_EXTERNAL = 2||External train camera view
|-
|public define int CAMERA_TRACKING = 4||External tracking camera view.
|-
|public define int CAMERA_ROAMING = 128||Roaming camera view.
|}
 

===Camera Flags===
----
*These flags are used in addition to the Camera Mode Flags to allow or disallow specific camera actions.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_SWITCH_VIEWS = 8||User permitted to swap between the camera views.
|-
|public define int CAMERA_SWITCH_VEHICLES = 16||User permitted to swap vehicles within the current train.
|-
|public define int CAMERA_SWITCH_TRAINS = 32||User permitted to swap to other trains which are in the consist menu.
|-
|public define int CAMERA_LOCKED = 64||User is NOT permitted to adjust camera (i.e. zoom, pan etc.).
|-
|public define int CAMERA_NORMAL = * ||Normal camera mode where everything is permitted.
|-
|colspan=2|* NOTE: CAMERA_NORMAL = CAMERA_INTERNAL | CAMERA_EXTERNAL | CAMERA_TRACKING | CAMERA_SWITCH_VIEWS | CAMERA_SWITCH_VEHICLES | CAMERA_SWITCH_TRAINS
|}
 

===Weather Type Constants===
----
*Define the current state of the weather in Trainz.
*A variety of weather conditions are supported and can be changed by using one of these values with the World.SetWeather() method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_TYPE_CLEAR = 0||Clear weather, no clouds, rain or snow.
|-
|public define int WEATHER_TYPE_CLOUDY = 1||Cloudy weather, no rain.
|-
|public define int WEATHER_TYPE_DRIZZLE = 2||Drizzle, light rain.
|-
|public define int WEATHER_TYPE_RAIN = 3||Rainy weather.
|-
|public define int WEATHER_TYPE_STORMY = 4||Stormy weather that includes lightning and thunder.
|-
|public define int WEATHER_TYPE_LIGHT_SNOW = 5||Snowing lightly.
|-
|public define int WEATHER_TYPE_MEDIUM_SNOW = 6||Medium level snow fall.
|-
|public define int WEATHER_TYPE_HEAVY_SNOW = 7||Heavy snow fall.
|}
 

===Weather Changeability Constants===
----
*Define the changeability settings for the weather.
*Weather changeability refers to variability of weather conditions rather than to a specific weather type.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_CHANGEABILITY_NONE = 0||Weather remains static.
|-
|public define int WEATHER_CHANGEABILITY_PERIODIC = 1||Periodic changes in weather.
|-
|public define int WEATHER_CHANGEABILITY_EXTREME = 2||Extreme and frequent changes in weather.
|}
 

===Time Values===
----
*Time constants defined in seconds.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float TIME_SECOND = 1.0f||One second.
|-
|public define float TIME_MINUTE = TIME_SECOND * 60.0f||One minute, 60.0 seconds.
|-
|public define float TIME_HOUR = TIME_MINUTE * 60.0f||One hour, 60.0 minutes, 3600.0 seconds.
|-
|public define float TIME_DAY = TIME_HOUR * 24.0f||One day, 24 hours, 1440.0 minutes, 86400.0 seconds.
|}
 

===Time Rate Constants===
----
*Values that define the time rates relative to normal time.
*These constants can be used to set the time rate that Trainz runs out through the World.SetGameTimeRate() method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int TIME_RATE_1X = 0||Real time (i.e. time in Trainz passes at the same rate as in the real world)
|-
|public define int TIME_RATE_2X = 1||Time passes at twice normal speed.
|-
|public define int TIME_RATE_4X = 2||
|-
|public define int TIME_RATE_8X = 3||
|-
|public define int TIME_RATE_16X = 4||
|-
|public define int TIME_RATE_32X = 5||
|-
|public define int TIME_RATE_60X = 6||
|-
| public define int TIME_RATE_120X = 7||
|-
| public define int TIME_RATE_240X = 8||
|-
|public define int TIME_RATE_360X = 9||
|-
|public define int TIME_RATE_480X = 10||
|-
|public define int TIME_RATE_720X = 11||
|-
|public define int TIME_RATE_960X = 12||
|-
|public define int TIME_RATE_1200X = 13||
|-
|public define int TIME_RATE_1440X = 14||
|}
 

===Trainz Modules===
----
*Trainz module mode constants.
*These values define the various module environments that Trainz can be in.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NO_MODULE = 0||Trainz not running in a module.
|-
|public define int SURVEYOR_MODULE = 1||Trainz is currently running in Surveyor.
|-
|public define int DRIVER_MODULE = 2||Trainz is currently running in Driver.
|}
 

==Related Messages==
* [[TrainzScript Message Reference]] 
* [[Camera Messages]] 
* [[Interface Messages]] 
* [[ModuleInit Message]] 
 

==AddDriverCharacter==
{{MethodHeader|public native DriverCharacter AddDriverCharacter(Asset driverCharacterAsset)}}
;Parameters
*'''driverCharacterAsset''' = Asset containing character to be added.
;Returned Value
*Reference to the DriverCharacter if successful, null otherwise.
;Syntax
DriverCharacter Casey = World.AddDriverCharacter(CaseyJones);
;Notes
 

==AddDriverCommand==
{{MethodHeader|public native DriverCommand AddDriverCommand(Asset driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.AddDriverCommand(accelerate);
;Notes
 

==CreateBehavior==
{{MethodHeader|public native ScenarioBehavior CreateBehavior(KUID kuid, Soup initialProperties)}}
;Parameters
*'''kuid''' = KUID of scenario.
'''initialProperties''' = Soup object containing initial properties for scenario.
;Returned Value
*Reference to the ScenarioBehavior created if successful, null otherwise.
;Syntax
ScenarioBehavior scenario = World.CreateBehavior(scenarioAsset, scenarioSoup);
;Notes
*The returned ScenarioBehavior object may be ended by releasing all references to it (resetting all references to null).
 

==CreateTrain==
{{MethodHeader|public native Train CreateTrain(KUID[ ] consist, string trackmarkName, bool direction) public native Train CreateTrain(KUID[ ] consist, TrackMark trackmark, bool direction) public native Train CreateTrain(KUID[ ] consist, Buildable buildable, string trackName, float position, bool direction)}}
;Parameters
*'''consist''' = An array of vehicle KUIDs used to describe the required Train object.
*'''trackmarkName''' = Name of Trackmark at which the consist is to be formed.
*'''buildable''' = Buildable on which the consist is to be formed.
*'''trackName''' = Name of track within Buildable object.
*'''position''' = Distance at which the Train is to be placed relative to the start of the track.
*'''trackmark''' = Reference to Trackmark at which the consist is to be formed.
*'''direction''' = Orientation of Train relative to direction of track or trackmark.
;Returned Value
*Reference to the Train created if successful, null otherwise.
;Syntax
Train train = World.CreateTrain(consist, buildable, "Track 1", 10.0, true);
;Notes
*These methods create a train from a list of vehicles in a consist array.
*Depending on the variant of the method used, the train can be created at a Trackmark, specified by name or reference, or at a Buildable or Industry object.
*It is the responsibility of the script programmer to ensure that sufficient track exists at the given location to allow the train to be created.
 

==DeleteTrain==
{{MethodHeader|public native void DeleteTrain(Train train)}}
;Parameters
*'''train''' = train to be deleted from map.
;Returned Value
*None
;Syntax
World.DeleteTrain(flyingScotsman);
;Notes
*Once a train has been deleted, care should be taken to avoid using its reference.
 

==DeleteVehicle==
{{MethodHeader|public native void DeleteVehicle(Vehicle vehicle)}}
;Parameters
*'''vehicle''' = vehicle to be deleted from its train.
;Returned Value
*None
;Syntax
World.DeleteVehicle(vehicles[vehicles.size()-1]);
;Notes
*Use Train.GetVehicles() to obtain an array of vehicles for a given train.
*Use Vehicle.GetMyTrain() to obtain a train reference for a given vehicle.
 

==FindAsset==
{{MethodHeader|public native Asset FindAsset(KUID kuid)}}
;Parameters
*'''kuid''' = KUID of Asset to return.
;Returned Value
*Given a valid KUID parameter, this method return an Asset reference if successful, null otherwise.
;Syntax
Asset asset = World.FindAsset(kuid);
;Notes
*See also Asset.FindAsset()
 

==FindDriverCommand==
{{MethodHeader|public native DriverCommand FindDriverCommand(Asset driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.FindDriverCommand(accelerate);
;Notes
 

==GetAssetList==
{{MethodHeader|public native Asset[ ] GetAssetList(string kind)}}
;Parameters
*'''kind''' = String representing the Kind of asset to return.
;Returned Value
*A list of all assets of the given ''kind''
;Syntax
Asset[] Libraries = World.GetAssetList("Library");
;Notes
*All installed assets of the given ''kind'' are returned, irrespective of whether or not they are in use on the current map.
 

==GetBadWeatherFog==
{{MethodHeader|public native float GetBadWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Bad weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetBadWeatherFog();
;Notes
 

==GetBehaviors==
{{MethodHeader|public native ScenarioBehavior[ ] GetBehaviors(void)}}
;Parameters
*None
;Returned Value
*A list of top-level behaviors or rules on the currently loaded route.
;Syntax
ScenarioBehavior[] rules = World.GetBehaviors();
;Notes
 

==GetCameraPositionX==
{{MethodHeader|public native float GetCameraPositionX(void)}}
;Parameters
*None
;Returned Value
*X Coordinate of the current camera position.
;Syntax
float X = World.GetCameraPositionX();
*Notes
 

==GetCameraPositionY==
{{MethodHeader|public native float GetCameraPositionY(void)}}
;Parameters
*None
;Returned Value
*Y Coordinate of the current camera position.
;Syntax
float Y = World.GetCameraPositionY();
*Notes
 

==GetCameraPositionZ==
{{MethodHeader|public native float GetCameraPositionZ(void)}}
;Parameters
*None
;Returned Value
*Z Coordinate of the current camera position.
;Syntax
float Z = World.GetCameraPositionZ();
*Notes
 

==GetCurrentModule==
{{MethodHeader|public native int GetCurrentModule(void)}}
;Parameters
*None
;Returned Value
*An integer representing the current Trainz module.
;Syntax
int module = World.GetCurrentModule();
;Notes
* See [[#Trainz Modules|Trainz Modules]] for details of the constants associated with this method.
* See [[ModuleInit Message]] for further details.
 

==GetDriverCharacterList==
{{MethodHeader|public native DriverCharacter[ ] GetDriverCharacterList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCharacter objects installed in the current world.
;Syntax
DriverCharacter[] drivers = World.GetDriverCharacterList();
;Notes
 

==GetDriverCommandList==
{{MethodHeader|public native DriverCommand[ ] GetDriverCommandList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCommand objects installed in the current world.
;Syntax
DriverCommand[] commands = World.GetDriverCommandList();
;Notes
 

==GetGameTime==
{{MethodHeader|public native float GetGameTime(void)}}
;Parameters
*None
;Returned value
*Current game time.
;Syntax
float Now = World.GetGameTime();
;Notes
*The returned time is normalised to a value between 0.0 and 1.0
*0.0 = midday.
*0.5 = midnight
*Use the [[#Time_Values|Time Value]] constants to convert the normalised values to human readable times.
 

==GetGoodWeatherFog==
{{MethodHeader|public native float GetGoodWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Good weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetGoodWeatherFog();
;Notes
 

==GetGroundDrawDistance==
{{MethodHeader|public native float GetGroundDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Ground draw distance in metres.
;Syntax
float dist = World.GetGroundDrawDistance();
;Notes
 

==GetIndustryList==
{{MethodHeader|public native GameObject[ ] GetIndustryList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the Industry objects for the current route.
;Syntax
GameObject[] Industries = World.GetIndustryList();
;Notes
*This function is obsolete and should not be used.
 

==GetJunctionList==
{{MethodHeader|public native Junction[ ] GetJunctionList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackside junction objects for the current route.
;Syntax
Junction[] junctions = World.GetJunctionList();
;Notes
*This function is obsolete and should not be used.
*Junction objects attached to fixed track junctions are not returned by this method.
 

==GetLibrary==
{{MethodHeader|public native Library GetLibrary(KUID kuid)}}
;Parameters
*'''kuid''' = KUID of script library asset to load.
;Returned Value
*A reference to the script library asset if successful, null otherwise.
;Syntax
Library codelib = World.GetLibrary(LibraryKUID);
;Notes
*The [[Class Library|Library]] asset is initialised when this method is first called in a session.
*Since only one instance can exist, subsequent calls return a reference to the existing Library object.
*See [[Class Library|Library]] for notes on how to use this method.
 

==GetSceneryDrawDistance==
{{MethodHeader|public native float GetSceneryDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Undefined.
;Notes
*Included for legacy script compatibility only. Has no effect.
 

==GetSeconds==
{{MethodHeader|public native float GetSeconds(void)}}
;Parameters
*None
;Returned Value
*The current value of a floating point number incrementing once per second in real time.
;Syntax
float start = World.GetSeconds();
// do stuff
float finish = World.GetSeconds();
float period = finish - start;
;Notes
*Each call will return a float value containing the current value of an internal counter.
*Subtracting a later value from a value saved at an earlier call will enable the delay between the two calls to be established.
 

==GetSignalList==
{{MethodHeader|public native Signal[ ] GetSignalList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the signal objects for the current route.
;Syntax
Signal[] signals = World.GetSignalList();
;Notes
*This function is obsolete and should not be used.
 

==GetStringTable==
{{MethodHeader|public native StringTable GetStringTable(void)}}
;Parameters
*None
;Returned Value
*The StringTable for the current session.
;Syntax
StringTable data = World.GetStringTable();
;Notes
 

==GetSurveyorSavedConsist==
{{MethodHeader|public native Soup GetSurveyorSavedConsistList(string name)}}
;Parameters
*'''name''' = Name of the consist to retireiev.
;Returned Value
*Returns a Soup definition of the named consist if it exists, null otherwise.
;Syntax
Soup consist = World.GetSurveyorSavedConsist("Brighton Belle");
;Notes
*Remember that the returned data is in a Soup format, which is not the same thing as a Train.
*TrainUtil.CreateTrainFormSoup() can be used to create a train from the returned Soup.
*This method only works in Surveyor.
 

==GetSurveyorSavedConsistList==
{{MethodHeader|public native string[ ] GetSurveyorSavedConsistList()}}
;Parameters
*None
;Returned Value
*An array of names of all the saved consist objects in Surveyor.
;Syntax
string[] consists = World.GetSurveyorSavedConsistList();
;Notes
*This method only works in Surveyor.
 

==GetTrackmarkList==
{{MethodHeader|public native TrackMark[ ] GetTrackmarkList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackmark objects for the current route.
;Syntax
Trackmark[] trackmarks = World.GetTrackmarkList();
;Notes
*This function is obsolete and should not be used.
 

==GetTrainList==
{{MethodHeader|public native Train[ ] GetTrainList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trains for the current route.
;Syntax
Train[] trains = World.GetTrainList();
;Notes
*This function is obsolete and should not be used.
 

==GetTrainzBuild==
{{MethodHeader|public native int GetTrainzBuild(void)}}
;Parameters;
*None
;Returned Value
*Gets the current build number of Trainz.
;Syntax
int build = World.GetTrainzBuild();
;Notes
*The value returned corresponds to the build number you can see in the bottom-right side of the main Trainz menu screen.
 

==GetTrainzVersion==
{{MethodHeader|public native float GetTrainzVersion(void)}}
;Parameters
*None
;Returned Value
*The TRS version number.
;Syntax
float version = World.GetTrainzVersion();
;Notes
*The value returned corresponds to the version number of Content manager (for example 4.6).
 

==GetTriggerList==
{{MethodHeader|public native Trigger[ ] GetTriggerList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trigger objects for the current route.
;Syntax
Trigger[] triggers = World.GetTriggerList();
;Notes
*This function is obsolete and should not be used.
*This method does not return scenery triggers, ie those attached to SceneryWithTrack objects and their descendants.
 

==GetVehicleList==
{{MethodHeader|public native Vehicle[ ] GetVehicleList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the vehicles in the current route.
;Syntax
Vehicle[] vehicles = World.GetVehicleList();
;Notes
*This function is obsolete and should not be used.
 

==GetWeatherChangeability==
{{MethodHeader|public native int GetWeatherChangeability(void)}}
;Parameter
*None
;Returned Value
*One of the [[#Weather_Changeability_Constants|Weather Changeability Constants]] denoting the variability of weather conditions.
;Syntax
int variability = World.GetWeatherChangeability();
;Notes
 

==GetWeatherType==
{{MethodHeader|public native int GetWeatherType(void)}}
;Parameter
*None
;Returned Value
*One of the [[#Weather_Type_Constants|Weather Type Constants]] denoting the current weather conditions.
;Syntax
int weather = World.GetWeatherType();
;Notes
 

==LoadMap==
{{MethodHeader|public native bool LoadMap(KUID kuid)}}
;Parameters
*'''kuid''' = KUID of map to load.
;Returned Value
*True if successful, false otherwise.
;Syntax
if (World.LoadMap(mapKUID) Interface.Print("Map loaded OK");
else Interface.Print("Map load failed");
;Notes
 

==Play2DSound==
{{MethodHeader|public float Play2DSound(Asset asset, string wave)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
;Returned Value
* Undefined.
;Syntax
// Play the sound and continues script execution.
World.Play2DSound(soundAsset,"sounds/allaboard.wav");
// Wait until sound has completed before continuing (pre-TS12 only!)
Sleep(World.Play2DSound(soundAsset,"sounds/allaboard.wav"));
;Notes
*Plays a ''.wav" sound file from the given asset's folder.
*The sound is non directional and can be mono or stereo.
*This method does not return after the sound has finished playing, it returns with the length of the sound as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
 

==PlaySound==
{{MethodHeader|public native float PlaySound     (Asset asset, string wave, float vol, float near, float far, GameObject target, string pt)     (Asset asset, string wave, float vol, float near, float far, GameObject target, string pt, bool loop)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
*'''vol''' = Volume level to play the sound at (0 to 1)<- These values taken from TRS2019 world.gs file comments
*'''near''' = Distance from the target asset at which the sound will be played at maximum volume.
*'''far''' = Distance from the target asset at which the sound will become inaudible.
*'''target''' = GameObject to which the sound will be attached if a 3d sound is required, null for 2D.
*'''pt''' = Name of attachment point in the target object if a 3d sound is required, null for 2D.
*'''loop''' = (Optional) If true the sound will loop continuously.
;Returned Value
* Sound length in seconds for Trainz before TS12
* Undefined for TS12 and TANE
;Syntax
// Play the sound and continues script execution.
World.PlaySound(soundAsset,"sounds/allaboard.wav",1.0,10.0,100.0,Station,"a.loudspeaker");
// Wait until sound has completed before continuing (pre-TS12 only!)
Sleep(World.PlaySound(soundAsset,"sounds/allaboard.wav",1000.0,10.0,100.0,Station,"a.loudspeaker");
;Notes
*Plays a ''.wav'' sound file from the given asset's folder.
*If the sound is to be directional a mono sound file is required.
*This method does not return after the sound has finished playing: it returns as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
*If you want to wait for the sound to complete playing before moving on, wrap the PlaySound() call up in a Sleep() call. '''Note!''' This works only in Trainz versions before TS12. For newer versions, TS12 and TANE, you can hard-code the duration of the sound, or store it in the extensions container of the config.txt file.
*The sound volume will be at a maximum for a camera position at or less than the value of the ''near'' parameter and will reduce with distance until the hearing position reaches ''far'', when the sound will be inaudible.
 

==RemoveDriverCharacter==
{{MethodHeader|public native void RemoveDriverCharacter(DriverCharacter driver)}}
;Parameters
*'''driver''' = DriverCharacter to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCharacter(dave);
;Notes
 

==RemoveDriverCommand==
{{MethodHeader|public native void RemoveDriverCommand(DriverCommand command)}}
;Parameters
*'''command''' = DriverCommand to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCommand(driverCommand);
;Notes
 

==SetBadWeatherFog==
{{MethodHeader|public native void SetBadWeatherFog(float distance)}}
;Parameters
*'''distance''' = Bad weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetBadWeatherFog(0.5);
;Notes
 

==SetCamera==
{{MethodHeader|public native bool SetCamera(MapObject focus) public native void SetCamera(Junction focus) public native void SetCamera(Vehicle focus, int cameraMode) public native void SetCamera(Train focus, int cameraMode)}}
;Parameters
*'''focus''' = Object on which the camera is to be focused.
*''cameraMode''' = One of the [[#Camera_View_Modes|Camera View Mode]] constants defining the view which should be assigned to the camera.
;Returned Value
*The first variant returns a boolean to indicate success or failure.
*Remaining variants do not return a value
'Syntax
World.SetCamera(train.GetVehicles[0],World.CAMERA_TRACKING); // sets the camera to track the first vehicle in the train.
 

==SetCameraAngle==
{{MethodHeader|public void SetCameraAngle(int yaw, int pitch, float radius)}}
;Parameters
*'''yaw''' = Camera rotation in degrees, 90 is a direct front view.
*'''pitch''' = Camera angle relative to the horizon, 0 is horizontal, 90 points vertically upwards.
*'''radius''' = Distance in metres to the object in focus.
;Returned Value
*None
;Syntax
World.SetCameraAngle(90,0,25); // Sets the camera to a direct frontal view at 25 metres from the currently focused object.
;Notes
*''Radius'' is measured from the object origin point (0,0,0).
 

==SetCameraFlags==
{{MethodHeader|public native void SetCameraFlags(int flags)}}
;Parameter
*'''flags''' integer value defining what the user is permitted to do with the game camera.
;Returned Value
*None
;Syntax
// User is permitted to select External or Tracking views only.
World.SetCameraFlags(World.CAMERA_EXTERNAL | World.CAMERA_TRACKING);
;Notes
*Use any combination of [[#Camera_Flags|Camera Flags]] and [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetCameraMode==
{{MethodHeader|public void SetCameraMode(int mode)}}
;Parameter
*'''mode''' = Camera mode to select.
;Returned Value
*None
;Syntax
World.SetCameraMode(World.CAMERA_TRACKING);
;Notes
*Use one of the [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetGameTime==
{{MethodHeader|public void SetGameTime(float time)}}
;Parameters
*'''time''' = new gane time to set.
;Returned Value
*None
;Syntax
World.SetGameTime(0.5); // sets time to midnight
;Notes
*Game time is normalised to a value between 0.0 and 1.0
*0.0 = midday.
*0.5 = midnight
*Use the [[#Time_Values|Time Value]] constants to convert human readable times to normalised values.
 

==SetGameTimeRate==
{{MethodHeader|public native void SetGameTimeRate(float rate)}}
;Parameters
*'''rate''' = New time rate to set.
;Returned Value
*None
;Syntax
World.SetGameTimeRate(World.TIME_RATE_8X); // sets game time to advance by 8 minutes per minute of real world time.
;Notes
*Use one of the [[#Time_Rate_Constants|Time Rate Constants]] to define the parameter.
 

==SetGoodWeatherFog==
{{MethodHeader|public native void SetGoodWeatherFog(float distance)}}
;Parameters
*'''distance''' = Good weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetGoodWeatherFog(0.5);
;Notes
 

==SetGroundDrawDistance==
{{MethodHeader|public native void SetGroundDrawDistance(float distance)}}
;Parameters
*'''distance''' = Ground draw distance in metres.
;Returned Value
*None
;Syntax
World.SetGroundDrawDistance(1000.0);
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==SetSceneryDrawDistance==
{{MethodHeader|public native void SetSceneryDrawDistance(float distance)}}
;Parameters
*'''distance''' = unused.
;Returned Value
*None
;Notes
* Does nothing. Included for script compatibility only.
 

==SetTargetObserver==
{{MethodHeader|public void SetTargetObserver(GameObject observer)}}
;Parameters
*'''observer''' = The game object to receive targeting messages.
;Returned Value
*None
;Syntax
SetTargetObserver(self);
;Notes
* Causes the specified object to receive "Track", "LeftClick" messages when a track is clicked. Causes the specified object to receive "Interface-Event", "Left-Click" messages when a targetable MapObject is clicked. May cause the functionality of a left mouse click to change from what the user is expecting, so should be used with caution. Used in modal scripts to allow the user to indicate a location for train placement, etc. As there is only a single observer at any given time, the script must take care to only call this function when entering placement mode at the user's request.
 

==SetWeather==
{{MethodHeader|public native void SetWeather(int type, int changeability)}}
;Parameters
*'''type''' = Weather conditions as defined by one of the [[#Weather_Type_Constants|Weather Type Constants]].
*'''change''' = Weather variation as defined by one of the [[#Weather_Changeability_Constants|Weather Changeability Constants]].
;Returned Value
*None
;Syntax
World.SetWeather(World.WEATHER_TYPE_HEAVY_SNOW,World.WEATHER_CHANGEABILITY_EXTREME); // April in Paris.
;Notes
 

==UserSetCamera==
{{MethodHeader|public native bool UserSetCamera(GameObject target)}}
;Parameters
*'''target''' = GameObject to set focus to.
;Returned Value
*True if successful, false otherwise.
;Syntax
World.UserSetCamera(Router,GetGameObject("Junction 5"));
;Notes
 

==UserSetCameraMode==
{{MethodHeader|public native void UserSetCameraMode(int mode)}}
;Parameters
*'''mode''' = One of the [[#Camera_View_Modes|Camera View Modes]]
;Returned Value
*None
;Syntax
World.UserSetCameraMode(World.CAMERA_ROAMING); // switches to roaming view if permitted.
;Notes
*This method respects the current [[#Camera_Flags|Camera Flag]] settings, disallowing any change which the flags do not permit.
 

==Categories==
[[Category:Script Class]]

Class Math

2020-12-28T14:50:46Z

Danny252: /* Related Methods */ Add link to RandBool

*[[TrainzScript Language Reference|API Hierarchy]]
**Math
 

*Math is a static class proving mathematical utility functions.
*When used in game code these methods must be prefixed ''Math.'' to reference the class.

==Abs==
{{MethodHeader|public int Abs(int number)}}
;Parameters
*'''number''' = integer value to be processed.
;Returned Value
*The absolute value of ''number''.
;Syntax
int answer = Math.Abs(-1); // returns 1
int answer = Math.Abs(1); // returns 1
;Notes
 

==Fabs==
{{MethodHeader|public float Fabs(float number)}}
;Parameters
*'''number''' = floating point value to be processed.
;Returned Value
*The absolute value of ''number''.
;Syntax
float answer = Math.Fabs(-1.0); // returns 1.0
float answer = Math.Fabs(1.0); // returns 1.0
;Notes
 

==Fmax==
{{MethodHeader|public float Fmax(float number1, float number2)}}
;Parameters
*'''number1, number2''' = floating point values to be compared.
;Returned Value
*The greater of the two parameters.
;Syntax
float answer = Math.Fmax(1.0,2.0); // returns 2.0
;Notes
 

==Fmin==
{{MethodHeader|public float Fmin(float number1, float number2)}}
;Parameters
*'''number1, number2''' = floating point values to be compared.
;Returned Value
*The lesser of the two parameters.
;Syntax
float answer = Math.Fmin(1.0,2.0); // returns 1.0
;Notes
 

==Rand==
{{MethodHeader|public native int Rand(int lower, int upper) public native float Rand(float lower, float upper)}}
;Parameters
*'''lower''' = minimum value to be returned (inclusive)
*'''upper''' = maximum value to be returned (exclusive)
;Returned Value
*A random floating point or integer value within the specified range.
;Syntax
int random = Math.Rand(1,10); // returns a random number between 1 and 9 (see below)
float random = Math.Rand(1.0,10.0); // returns a random number between 1.0 and 9.9999999... (see below)
;Notes
*Rand operates on floating point numbers but if both parameters are integers it will return an integer result.
*If either parameter is a float then the result will also be a float.
*The lower bound is inclusive and is therefore included in the set of possible return values.
*The upper bound is exclusive and is never included.
*In the case of an integer result the returned value is rounded down to an integral value. Because of this the call ''Math.Rand(1,10) will return a result between 1 and 9.
 

==Sqrt==
{{MethodHeader|public native float Sqrt(float number)}}
;Parameters
*'''number''' = floating point value to find the square root of.
;Returned Value
*The square root of the parameter.
;Syntax
float root = Math.Sqrt(64.0); // returns 8.0
;Notes
 

==Related Methods==

[[Class TrainUtil#RandBool|TrainUtil.RandBool()]]

[[Class Str#ToInt|Str.ToInt()]]

[[Class Str#ToFloat|Str.ToFloat()]]

[[Class Str#UnpackInt|Str.UnpackInt()]]

[[Class Str#UnpackFloat|Str.UnpackFloat()]]

==Categories==
[[Category:Script Class]]

Saving and Restoring Data, Using Properties.

2020-12-28T14:45:58Z

Danny252: Add reference links, add navigation links

Apart from ''Init()'' there are several other standard methods which you can include which will be called at the appropriate time by the game. Two of the most important are ''GetProperties()'' which is called when Trainz needs to retrieve any useful data which your object might wish to save to the session file, and ''SetProperties()'' which is called when your object might want to read or update any data which has been saved by the game.

* ''[[Class PropertyObject#SetProperties|SetProperties]]()'' is called at the start of a Surveyor or Driver session and whenever the Object Property dialogue is saved. It is also used by the Undo system.
* ''[[Class PropertyObject#GetPropertirs|GetProperties]]()'' is called when the Object Property dialogue is opened and when the current session is saved and exited.

To demonstrate this we have a further script:

include "MapObject.gs"

class Tutorial isclass MapObject {

string Now;
string Then;

string GetTime(float GameTime) {
string result = "Good Afternoon";
if (GameTime >= 0.25) result = "Good Evening";
if (GameTime >= 0.5) result = "Good Morning";
return result;
}

public void Init(void) {
inherited();
Now = GetTime(World.GetGameTime());
AddHandler(me,"Reminder","","ReminderHandler");
PostMessage(me,"Reminder",Now,5.0);
}

public void SetProperties(Soup soup) {
inherited(soup);
Then = soup.GetNamedTag("last");
}

public Soup GetProperties(void) {
Soup soup = inherited();
soup.SetNamedTag("last",Now);
return soup;
}

void ReminderHandler(Message msg) {
if (Then != "") {
Str.TrimLeft(Then,"Good ");
Then = "\nLast time we met was in the " + Then;
}
Interface.ShowPopupHelp("Hello World, " + msg.minor,GetAsset(),Interface.GetTimeStamp())
//Exception("Hello World, " + msg.minor + Then + "\n\n");// use this in old versions
}

};

'''''string Now;''''' 
'''''string Then;''''' 
* The declaration of ''Now'' has been moved from ''Init()'' to the body of the script.
* A second declaration, ''Then'' has been added in the same place.
* Declaring them here makes them ''global'', meaning that they can be used by any method within the script.

'''''public void SetProperties([[Class Soup|Soup]] soup) {''''' 
* This is the standard declaration of ''[[Class PropertyObject#SetProperties|SetProperties]]()''
* The method is public, since it needs to be called from outside the current script.
* It requires one parameter of type [[Class Soup|Soup]] (a Trainz database), which is supplied by the game.
* This database contains all the data about our object which has previously been saved to disc.

'''''inherited(soup);''''' 
* As with ''Init()'' the equivalent function in the parent ''[[Class MapObject|MapObject]]'' must be called first.
* The ''Soup'' which the game has supplied is passed on to allow the parent to extract any data that it might need.

'''''Then = soup.[[Class Soup#GetNamedTag|GetNamedTag]]("last");''''' 
* We need to know whether it was morning, afternoon or evening the last time that the session was saved.
* ''GetNamedTag("last")'' retrieves this data from the ''Soup'' by specifying the key that will have been used to save it.
* The first time that we place our asset the tag will not contain any data and will return an empty string.

'''''public [[Class Soup|Soup]] GetProperties(void) {''''' 
* This is the standard declaration of ''[[Class PropertyObject#GetProperties|GetProperties]]()''
* This is a public function which returns a ''Soup'' but requires no parameters.

'''''Soup soup = inherited();''''' 
* The equivalent function within the parent MapObject class must be called first.
* A ''Soup'' database is declared and the contents of the parent's ''Soup'' are assigned to it.

'''''soup.[[Class Soup#SetNamedTag|SetNamedTag]]("last",Now);''''' 
* Once the parent has provided its data we need to add our own information to the database.
* We can do this by creating or updating information referenced by the tag name "last", so we set this item to be the current value of ''Now''.

'''''return soup;''''' 
* Having added our data we send the modified database back to the game to be written to disk.

'''''ReminderHandler'''''
* This method has been amended to look at the value of the global variable ''Then'' which has been retrieved from the session files via the ''SetProperties()'' method.
* If the value of ''Then'' is not an empty string it is chopped and formatted so that it can be included in our ''ShowPopupHelp()'' or ''Exception()'' message. 

To test this out:
* Modify the script as before.
* Load TRS and start a new map in Surveyor.
* Place a copy of your object, wait for the message which will be the same as before.
* Quit the map making sure to save the Surveyor session.
* Reload and wait for the message.
* This time it should look like this: 

[[Image:The Last Time.jpg]] 

From now on every time the session is saved and reloaded your object will remember the time of day when it was last saved. Rather than just saving Morning, Afternoon and Evening we could have updated the actual game time throughout the session and used the same mechanism to save the time when the session is closed down. We could also use similar techniques to reset the clock on reloading the session.

You have now used the most important of the standard method calls and learned how to send messages and how to save and retrieve data. Now we can move on to creating an asset and making it do something useful.

== Navigation ==

* Previous Tutorial: [[Talking to Yourself, Sending Messages.]]
* Next Tutorial: [[Setting Up the Asset.]]
* Back to [[Getting Started in TrainzScript]]

Talking to Yourself, Sending Messages.

2020-12-28T14:40:42Z

Danny252: Correct previous tutorial link

Apart from sitting around waiting for the game engine to call your methods, there is another way of making your script wake up and do something useful, and that is to send it a message. Messages are an important part of Trainz and are constantly being exchanged in the background between the game and its constituent objects.

You can find more details of how the system works in the [[TrainzScript Message Reference]] or (if you have logging enabled) you can open ''jetlog.txt'' in your ''\Program Files\Auran\TRS####\'' folder and see a record of the messages that were sent in your last game session. For now we will just send a message to ourself to do something at a future time.

One of the problems with the way that TRS calls the ''Init()'' method is that there is no guarantee that every object in the map is initialised at exactly the same moment. As a result it is unsafe to carry out tasks in ''Init()'' which depend on information being available about other objects. It can therefore be quite useful to delay some of our initialisation until later, when we can be sure that all of the data we might need will be available.

In practice no delay is necessary to accomplish this because TRS does not start to process messages until all object initialisation is complete but we will use a five second pause so that we can be sure of what is going on.

Here is a modification to the script:

include "MapObject.gs"

class Tutorial isclass MapObject {

string GetTime(float GameTime) {
string result = "Good Afternoon";
if (GameTime >= 0.25) result = "Good Evening";
if (GameTime >= 0.5) result = "Good Morning";
return result;
}

public void Init(void) {
inherited();
string Now = GetTime(World.GetGameTime());
AddHandler(me,"Reminder","","ReminderHandler");
PostMessage(me,"Reminder",Now,5.0);
}

void ReminderHandler(Message msg) {
Interface.ShowPopupHelp("Hello World, " + msg.minor,GetAsset(),Interface.GetTimeStamp())
//Exception("Hello World, " + msg.minor + "\n\n");// use this instead of ShowPopupHelp in old versions
}

};

'''''[[Class GameObject#AddHandler|AddHandler]](me,"Reminder","","ReminderHandler");''''' 
* ''AddHandler'' sets up a mechanism to listen for messages.
* Messages usually consist of two text strings separated by a comma, known as the ''Major'' and the ''Minor'' of the message.
* The second and third parameters specify the major and minor.
* Since the third parameter is an empty string this handler will ignore it, in this case we are listening for any message which starts with the word ''Reminder''
* The last parameter specifies the method to which the message will be sent for processing, in this case ''ReminderHandler''.

'''''[[Class GameObject#PostMessage|PostMessage]](me,"Reminder",Now,5.0);''''' 
* ''PostMessage'' sends a message
* ''me'' is the message destination, in this case we are sending a message to ourself.
* ''Reminder'' is the message major
* ''Now'', the result of our call to ''GetTime()'' is the message minor.
* ''5.0'' is the number of seconds that the game should delay before actually dispatching the message.

'''''void ReminderHandler(Message msg) {'''''
* ''ReminderHandler'' is the method name that we specified in our call to ''AddHandler'' and is the function that will process our message.
* Message handlers always take one parameter of the predefined Message type.
* The ShowPopupHelp or Exception call is the same as before, it has simply been moved from Init() to ''ReminderHandler''

Modify the script as before and load your asset into Trainz. The result should be exactly the same as last time except that there will be a five second delay between placing the object and receiving the message.

In practice you can send messages to other objects and you can listen for, and react to, messages from other objects. Sending a message to yourself can be a very useful device though and it should be helpful to see the whole of the process in one object script.

== Navigation ==

* Previous Tutorial: [[Getting Information From the Game, Writing Your Own Methods.]]
* Next Tutorial: [[Saving and Restoring Data, Using Properties.]]
* Back to [[Getting Started in TrainzScript]]

Getting Information From the Game, Writing Your Own Methods.

2020-12-28T14:40:08Z

Danny252: Add navigation links

Although we can't control when scripts are called by the game, we can control what happens when the various standard methods are actually executed. We could add pages of code to our ''Init()'' method to do all sorts of things, but it makes life more manageable if we write our own methods to carry out a specific task and have them called by ''Init()''.

Reopen ''Tutorial.gs'' and edit it, or copy and paste, to look like this:

include "MapObject.gs"

class Tutorial isclass MapObject {

string GetTime(float GameTime) {
string result = "Good Afternoon";
if (GameTime >= 0.25) result = "Good Evening";
if (GameTime >= 0.5) result = "Good Morning";
return result;
}

public void Init(void) {
inherited();
string Now = GetTime(World.GetGameTime());
Interface.ShowPopupHelp("Hello World, " + Now,GetAsset(),Interface.GetTimeStamp())
//Exception("Hello World, " + Now + "\n\n"); // use this instead of ShowPopupHelp in old builds
}

};

You will have created a new method called ''GetTime()'' and added a call to that method in ''Init()''. 
Looking at the code as before:

'''''string GetTime(float GameTime) {''''' 
* This is the method prototype which defines the information required and the data which will be returned to the caller.
* This method will not be accessible to external scripts so the ''public'' qualifier is not required
* ''string'' indicates that the method will return data as a character string.
* ''GetTime'' is the name of the method.
* ''(float GameTime)'' means that the method will need one float (real number) as a parameter.

'''''string result = "Good Afternoon"''''' 
declares a string variable and assigns a value to it.

'''''if (GameTime >= 0.25) result = "Good Evening";''''' 
looks at the value of the float parameter and alters the value of result if it is 0.25 or more.

'''''if (GameTime >= 0.5) result = "Good Morning";''''' 
does the same thing for a ''GameTime'' value of 0.5 or more.

'''''return result;''''' 
sends the value back to the caller as a string.

'''''}''''' 
indicates that the method code is complete.

You will notice that ''Init()'' has also has been amended.

'''''string Now = GetTime(World.GetGameTime());''''' 
* declares a string variable and assigns the value to be returned by our new method.
* ''[[Class World|World]].[[Class World#GetGameTime|GetGameTime()]]'' is a built-in function that provides a value between 0 and 1, representing the time in Trainz.
* This value is sent directly to the ''GetTime'' function to provide the parameter which it needs to decide whether it is morning, afternoon or evening.
* The character string produced by ''GetTime'' is assigned to ''Now'' and then added into our message.

Save ''Tutorial.gs'' and recommit the asset. When you open Surveyor and place a new copy of your asset (or reopen a map with a copy included) this should be the result:

[[Image:GoodMorning.jpg]]
 

* Your message might of course be different if you have Surveyor set to a different time.
* It would have been perfectly possible for GetTime to have returned a properly formatted time such as 23:15:34. 

==Navigation==

* Previous Tutorial: [[Hello World, Setting Up An Asset Script.]]
* Next Tutorial: [[Talking to Yourself, Sending Messages.]]
* Back to [[Getting Started in TrainzScript]]

Talking to Yourself, Sending Messages.

2020-12-28T14:39:07Z

Danny252: Add reference links, add navigation links

Apart from sitting around waiting for the game engine to call your methods, there is another way of making your script wake up and do something useful, and that is to send it a message. Messages are an important part of Trainz and are constantly being exchanged in the background between the game and its constituent objects.

You can find more details of how the system works in the [[TrainzScript Message Reference]] or (if you have logging enabled) you can open ''jetlog.txt'' in your ''\Program Files\Auran\TRS####\'' folder and see a record of the messages that were sent in your last game session. For now we will just send a message to ourself to do something at a future time.

One of the problems with the way that TRS calls the ''Init()'' method is that there is no guarantee that every object in the map is initialised at exactly the same moment. As a result it is unsafe to carry out tasks in ''Init()'' which depend on information being available about other objects. It can therefore be quite useful to delay some of our initialisation until later, when we can be sure that all of the data we might need will be available.

In practice no delay is necessary to accomplish this because TRS does not start to process messages until all object initialisation is complete but we will use a five second pause so that we can be sure of what is going on.

Here is a modification to the script:

include "MapObject.gs"

class Tutorial isclass MapObject {

string GetTime(float GameTime) {
string result = "Good Afternoon";
if (GameTime >= 0.25) result = "Good Evening";
if (GameTime >= 0.5) result = "Good Morning";
return result;
}

public void Init(void) {
inherited();
string Now = GetTime(World.GetGameTime());
AddHandler(me,"Reminder","","ReminderHandler");
PostMessage(me,"Reminder",Now,5.0);
}

void ReminderHandler(Message msg) {
Interface.ShowPopupHelp("Hello World, " + msg.minor,GetAsset(),Interface.GetTimeStamp())
//Exception("Hello World, " + msg.minor + "\n\n");// use this instead of ShowPopupHelp in old versions
}

};

'''''[[Class GameObject#AddHandler|AddHandler]](me,"Reminder","","ReminderHandler");''''' 
* ''AddHandler'' sets up a mechanism to listen for messages.
* Messages usually consist of two text strings separated by a comma, known as the ''Major'' and the ''Minor'' of the message.
* The second and third parameters specify the major and minor.
* Since the third parameter is an empty string this handler will ignore it, in this case we are listening for any message which starts with the word ''Reminder''
* The last parameter specifies the method to which the message will be sent for processing, in this case ''ReminderHandler''.

'''''[[Class GameObject#PostMessage|PostMessage]](me,"Reminder",Now,5.0);''''' 
* ''PostMessage'' sends a message
* ''me'' is the message destination, in this case we are sending a message to ourself.
* ''Reminder'' is the message major
* ''Now'', the result of our call to ''GetTime()'' is the message minor.
* ''5.0'' is the number of seconds that the game should delay before actually dispatching the message.

'''''void ReminderHandler(Message msg) {'''''
* ''ReminderHandler'' is the method name that we specified in our call to ''AddHandler'' and is the function that will process our message.
* Message handlers always take one parameter of the predefined Message type.
* The ShowPopupHelp or Exception call is the same as before, it has simply been moved from Init() to ''ReminderHandler''

Modify the script as before and load your asset into Trainz. The result should be exactly the same as last time except that there will be a five second delay between placing the object and receiving the message.

In practice you can send messages to other objects and you can listen for, and react to, messages from other objects. Sending a message to yourself can be a very useful device though and it should be helpful to see the whole of the process in one object script.

== Navigation ==

* Previous Tutorial: [[Hello World, Setting Up An Asset Script.]]
* Next Tutorial: [[Saving and Restoring Data, Using Properties.]]
* Back to [[Getting Started in TrainzScript]]

Hello World, Setting Up An Asset Script.

2020-12-28T14:37:56Z

Danny252: /* Next Tutorial */ Add navigation links

__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"''''' 
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]] {''''' 
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) {''''' 
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()]];''''' 
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]]());''''' 
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.

[[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]]

Hello World, Setting Up An Asset Script.

2020-12-28T14:33:43Z

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

__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"''''' 
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]] {''''' 
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) {''''' 
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()]];''''' 
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]]());''''' 
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.

[[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>

== Next Tutorial ==

[[Getting Information From the Game, Writing Your Own Methods.]]

Operators

2020-12-28T14:23:16Z

Danny252: Document float->int cast rounding behaviour. Document string concatenation (addition)

The operator sections set out below follow the language's preference rules. The earlier the operator appears in the list, the higher the precedence and the earlier the listed operators will be evaluated.

* [[TrainzScript Language Reference]]
** [[Comments & Delineation]]
** [[TrainzScript Keywords]]
** [[Operators]]
** [[Types]]

__NOEDITSECTION__
==Operators (1), Grouping & Indexing==
{{MethodHeader|( )}}
*Expression grouping.
*In common with most programming languages Trainzscript carries out arithmetical operations in the order defined by operator precedence rules.
*''3 + 2 * 12 - 7'' would return 20, because multiplication is of higher precedence than addition and subtraction.
*You can force the compiler to change this sequence and make your intentions crystal clear by declaring this as ''((3 + 2) * 12) - 7''.

{{MethodHeader|[ i ]}}
*Array and string indexing.
*Arrays are zero based and ''arrayName[0]'' will represent the first element.
*Similarly ''arrayName[arrayName.size() - 1]'' will represent the last element.
*A call to a value outside the range ''[0 … size()-1]'' will generate an exception.
*This notation can also be used to return a single character from a string.

intArray[intArray.size()] = 5 // will add the new value of 5 to the end of the array.

{{MethodHeader|[ i , j ]}}
*Array and String range index.
*The expression ''string[0,string.size()]'' will return the entire string.
*The integers i and j are best thought of as 'cursor' positions where i is the first element and j is one beyond the last element.
*If i is omitted the range will start at the beginning of the array (index 0).
*If j is omitted the range will end after the end of the array (.size()).
*To return a single element other than the first or last, both i and j are required.
*Given the declaration ''string s = "abcde"''
s[,3] = "abc"
s[2,3] = "c"
s[2,] = "cde"

intArray[2,3] = null // will delete the third element of the array.

{{MethodHeader|[ i , ]}}
*Indexes from i to the end of the string or array inclusively.
s[2,] = "cde"

{{MethodHeader|[ , j ]}}
*Indexes from the start of the string or array to element j-1 inclusively.
s[,3] = "abc"

{{MethodHeader|.}}
*Dereference operator
GetAsset().GetConfigSoup();
*The ''GetConfigSoup()'' method to be called is the method defined for the class ''GetAsset()''.

{{MethodHeader|!}}
*Not Operator
!true = false
!vehicle = null

==Operators (2), Incremental and Unary Operators==
{{MethodHeader|++}}
*Increments a numeric value by 1.
*Often used for control variables in loops:
for(n = 0; n < list.size(); n++) {
DoStuffWith(n);
}
*Increments n by 1 on each pass through the loop.

{{MethodHeader|--}}
*Decrements a numeric value by 1.
*Often used for control variables in loops:
n = list.size() - 1;
while(n >= 0) {
DoStuffWith(n);
n--;
}
*Decrements n by 1 on each pass through the loop.

{{MethodHeader|+}}
*Unary plus.
*Used to denote that a value is positive.

{{MethodHeader|-}}
*Unary minus.
*Used to denote that a value is negative.

==Operators (3), Casts==
{{MethodHeader|<h5>(bool)</h5>}}
*Boolean type cast.
(bool) 0 = false
(bool) 0.0 = false
(bool) n = true //where n is greater than zero

{{MethodHeader|<h5>(int)</h5>}}
*Integer type cast. Floats will be truncated (rounded down).
(int) 5.0 = 5
(int) 5.1 = 5
(int) 5.6 = 5
(int) true = 1

{{MethodHeader|<h5>(float)</h5>}}
*Float type cast.
(float) 100 = 100.0
(float) false = 0.0

{{MethodHeader|<h5>(string)</h5>}}
*String type cast.
(string) 1 = "1"
(string) 0.99 = "0.99"
(string) false = "false";

{{MethodHeader|(''reference'')}}
*Class type cast.
How is this used and how is it different from cast<Class>?

{{MethodHeader|<h5>cast</h5>}}
*Dynamic cast.
*Returns null if the reference cannot be converted to the class specified by className.
*Note that ancestors of the specified class will be returned.
Vehicle vehicle = cast<Vehicle>msg.src;

MeshObject meshObject;
GameObject gameObject = cast<GameObject>meshObject; // returns meshObject if the object exists, null otherwise

{{MethodHeader|<h5>size()</h5>}}
*Returns the number of members of an array or the length of a string.
*In the case of an array this does not necessarily mean that all (or any) of the members actually contain values.
given string s = "abcde";
s.size() = 5;

int[] numbers = new int[5]; // creates an empty array of 5 integers
numbers.size() = 5;

{{MethodHeader|<h5>copy()</h5>}}
*Creates a copy of an array or string.
*This is different from a simple assignment which points a variable to the same memory address as an existing variable.
*Array.copy() or string.copy() creates an additional copy of the data.
int[] numbers = new int[5];
int[] moreNumbers;

moreNumbers.copy(numbers); // duplicates numbers

{{MethodHeader|<h5>isclass()</h5>}}
*Used in the declaration of a new class identifier
class MyScript isclass Vehicle {
classMethods();
};
*Used to test whether a given reference is to a specific class.
given the declaration:
TrackLoadInfo info = new TrackLoadInfo();

info.isclass(TrackLoadInfo); // returns true

{{MethodHeader|<h5>new</h5>}}
*Creates a new instance of the specified type.
int[] numbers = new int[4]; // creates an integer array containing 4 members.
TrackLoadInfo info = new TrackLoadInfo(); // creates a new instance of the TrackLoadInfo class.
*new does not initialise the members.
*GameObject classes cannot be created using new.

==Operators (4), Multiplication & Division==
{{MethodHeader|*}}
*Multiplication.
*If both terms are integers the result will be an integer.
*If either term is a float the result will be a float.
2 * 5 = 10;
2 * 5.0 = 10.0;

{{MethodHeader|/}}
*Division.
*If both terms are integers the result will be an integer, possibly with a remainder.
*If either term is a float the result will be a float.
10 / 5 = 2;
10 / 5.0 = 2.0;
10 / 6 = 1;

{{MethodHeader|%}}
*Remainder or modulus operator.
*Returns the remainder from an integer division.
5 % 2 = 1;
105 % 50 = 5;
105 % 100 = 5;

==Operators (5), Addition & Subtraction==
{{MethodHeader|+}}
*Addition
*If both terms are integers the result will be an integer.
*If either term is a float the result will be a float.
*If either term is a string the result will be a string.
1 + 1 = 2;
1 + 1.0 = 2.0;
"a" + "b" = "ab";
"a" + 1 = "a1";

{{MethodHeader|-}}
*Subtraction
*If both terms are integers the result will be an integer.
*If either term is a float the result will be a float.
2 - 1 = 1;
2 - 1.0 = 1.0;

==Operators (6), Shifts==
{{MethodHeader|<<}}
*Shift Left
*Bitwise operator moves all of the binary values to the left by the number of places specified in the second term.
*Binary zero is appended.
*Provided there is no overflow the result is a doubling of the value for each shift.
8 << 1 = 16
8 << 2 = 32

{{MethodHeader|>>}}
*Shift Right
*Bitwise operator moves all of the binary values one place to the right by the number of places specified in the second term.
*Binary zero is prepended and any displaced bits are discarded.
*The result is an integral halving of the value for each shift.
8 >> 1 = 4
9 >> 2 = 2

==Operators (7), Comparisons==
{{MethodHeader|<}}
* Is less than.
*Comparison operator which can be used on string, float, integer and bool values.
*Returns true if the first term is less than the second.
1 < 2 = true;
false < false = false;
"abc" < "def" = true;

{{MethodHeader|<=}}
*Is less than or equal.
*Comparison operator which can be used on string, float, integer and bool values.
*Returns true if the first term is less than or equal to the second.
1 <= 2 = true;
false <= false = true;
"abc" <= "def" = true;

{{MethodHeader|>}}
*Is greater than.
*Comparison operator which can be used on string, float, integer and bool values.
*Returns true if the first term is greater than the second.
1 > 2 = false;
true > false = true;
"abc" > "def" = false;

{{MethodHeader|>=}}
*Is greater than or equal.
*Comparison operator which can be used on string, float, integer and bool values.
*Returns true if the first term is greater than or equal to the second.
1 >= 2 = false;
true >= true = true;
"abc" >= "def" = false;

==Operators (8), Equality==
{{MethodHeader|==}}
*Is equal.
*Comparison operator which can be used on string, float, integer and bool values and on object references.
*Returns true if the first and second terms are equal or if they evaluate to the same object.
int a = 0;
int b = 0;
a == b; // returns true
*Note that ''a = b'' is an assignment and will always return true. Mistyping '''''=''''' for '''''==''''' is one of the most common semantic errors in Trainzscript.

{{MethodHeader|!=}}
*Is not equal.
*Comparison operator which can be used on string, float, integer and bool values and on object references.
*Returns true if the first and second terms are not equal and do not evaluate to the same object.
int a = 0;
int b = 0;
a != b; // returns false

==Operators (9), Bitwise Operators==
{{MethodHeader|&}}
*Bitwise AND
*Performs a bit by bit comparison of two integers and returns a new value.
*Each bit in the result is set if BOTH of the corresponding bits in the arguments are set
0000 1111
& 0001 0111
= 0000 0111

15 & 23 = 7

{{MethodHeader|^}}
*Bitwise XOR
*Performs a bit by bit comparison of two integers and returns a new value.
*Each bit in the result is set if EITHER BUT NOT BOTH of the corresponding bits in the arguments are set
0000 1111
^ 0001 0111
= 0001 1000

15 ^ 23 = 24

{{MethodHeader|¦}}
*Bitwise OR
*Performs a bit by bit comparison of two integers and returns a new value.
*Each bit in the result is set if EITHER of the corresponding bits in the arguments are set
0000 1111
| 0001 0111
= 0001 1111

15 | 23 = 31

{{MethodHeader|~}}
*Bitwise Inverse
*Takes the binary representation of the integer and inverts each bit.
*Useful in masking out values from bitfields (eg. flags &= ~SOME_FLAG; switches off the SOME_FLAG bit from 'flags')
~0011 1101 = 1100 0010
~1000 0100 = 0111 1011

~0 = -1
~255 = -256
~5 = -6

==Operators (10), Logical Operators==
{{MethodHeader|<h5>and</h5>}}
*Logical AND
*Enables multiple boolean expressions to be combined.
if (msg.minor == "Enter" and doorsOpen)

{{MethodHeader|<h5>or</h5>}}
*Logical OR
*Enables multiple boolean expressions to be combined.
if (msg.minor == "Enter" or doorsOpen)
if ((msg.minor == "Enter" and doorsOpen) or (msg.minor == "Leave" and !doorsOpen))

==Operators (11), Assignment==
{{MethodHeader|=}}
*Assignment Operator
a = 1;
Train train = World.GetTrainList()[0];

The assignment operator sets the variable on the LHS of the expression to the same value as the variable on the RHS.

Note that string and array are object types, not primitive types. Therefore, like all objects, assignment of a string or array object means that the variable on the LHS of the assignment expression refers to the same object (that is, the same string or the same array) as the variable on the RHS. A new copy of the object is not created. If the intention is to make an assignment to a new object that is a copy of the original, you should use the .copy() method of the string or array objects, or the .clone() method (if available) of other objects.

{{MethodHeader|,}}
*Expression or parameter separator.

=Categories=
[[Category:TrainzScript]]

TrainzScript Keywords

2020-12-28T14:09:00Z

Danny252: Add links between language reference pages

* [[TrainzScript Language Reference]]
** [[Comments & Delineation]]
** [[TrainzScript Keywords]]
** [[Operators]]
** [[Types]]

 

==Keywords==
__NOEDITSECTION__
{{MethodHeader|<h4>break</h4>}}
*Exits from current code block (''[[#for|for]], [[#wait|wait]], [[#switch|switch]], [[#while|while]]'')
*Execution will continue with the first statement after the loop.
// This loop will complete when n is greater than 5 or when n == list.size(), whichever occurs first

for (n = 0; n < list.size(); n++) {
if (n > 5) break;
}
 

{{MethodHeader|<h4>case</h4>}}
*Individual ''case'' statements are labels that the code will jump to dependent on the value of the integer expression following the keyword.
*The case statement is used in the switch control flow statement to declare an integer option and the action to be taken when execution is transferred to this label.
*This code will print the days of the week from Sunday to Saturday:
int i;
string dayOfWeek;
for(i = 0; i < 6; i++) {
switch(i) {
case 0 : dayOfWeek = "Sunday";
break;
case 1 : dayOfWeek = "Monday";
break;
case 2 : dayOfWeek = "Tuesday";
break;
case 3 : dayOfWeek = "Wednesday";
break;
case 4 : dayOfWeek = "Thursday";
break;
case 5 : dayOfWeek = "Friday";
break;
case 6 : dayOfWeek = "Saturday";
break;
default : dayOfWeek = "ERROR";
}
Interface.Print(dayOfWeek);
}
*''[[#Switch|switch]]'' transfers execution to the statement immedaitely following the appropriate ''case'' label.
*If there is no match execution continues after the ''[[#default|default]]'' label.
*Note that the list of statements following the ''case'' selector should normally terminate with ''[[#break|break]];'' (which exits from the ''[[#switch|switch]]'' statement) or ''[[#return|return]]'' (which exits from the entire method) to prevent the code from running on into the next section.
 

{{MethodHeader|<h4>class</h4>}}
*Class defines a new class declaration and the identity of the immediate parent:
class ChildClass isclass ParentClass {

class members...
class methods...

};
*More than one class declaration may be included in the same file.
 

{{MethodHeader|<h4>continue</h4>}}
*Jumps to the next iteration of a ''[[#for|for]], [[#while|while]]'' or ''[[#wait|wait]]'' loop For example:
int i;
for(i = 0; i < 10; ++i) {
if(i == 5)
continue;
Interface.Print(i);
}
*The above code will print 0 to 4, skip 5 and then print 6 to 9.
 

{{MethodHeader|<h4>default</h4>}}
*See ''[[#case|case]]''.
 

{{MethodHeader|<h4>define</h4>}}
*''define'' is used to declare a constant
*Constants must be initialised on declaration and cannot be changed in code.
define string firstDay = "Monday"; // declares a string variable available anywhere within the containing class
define public int daysInWeek = 7; // declares an integer variable which will also be available from outside the class.
 

{{MethodHeader|<h4>else</h4>}}
*see ''[[#if|if]]''
 

{{MethodHeader|<h4>false</h4>}}
*Boolean constant
!true = false
 

{{MethodHeader|<h4>final</h4>}}
*A class or method specifier that prevents users from overriding the declaration
final class Info {
string name;
string address;
}
*Given the above the declaration the following declaration would not be possible
class DetailedInfo isclass Info {
string telephone;
}
 

{{MethodHeader|<h4>for</h4>}}
*''for'' is a control flow loop statement.
*A ''for'' loop has four parts and takes the form: ''for(A; B; C) D'' where:
**A initialises a counter variable, and is executed before the looping begins
**B is the test condition, looping will continue while B is true
**C is the loop expression, and will be executed at the end of every loop
**D is the code body statement, usually a compound statement, and is executed on every loop.
int i;
Junction[] junctions = World.GetJunctionList();
for (i = 0; i < junctions.size(); i++) {
string name = junctions[i].GetName();
Interface.Print("Junction " + i + " is called " + name);
}
*Depending on the values of Parts A and B the loop may not execute at all.
 

{{MethodHeader|<h4>game</h4>}}
*Class specifier reserved for built-in predefined classes.
 

{{MethodHeader|<h4>goto</h4>}}
*The ''goto'' statement will branch to a label statement. For example:
int i = 5

A: // label statement
Interface.Print("hello");
if(i--) goto A;

*The above code will print hello 5 times. (zero evaluates as boolean false)
 

{{MethodHeader|<h4>if</h4>}}
*''if'' and ''else'' are keywords for the construction of ''if / then / else'' constructs used to control program flow
*Code following an ''if(condition)'' statement is executed only when the condition evaluates to true.
*In any other case execution branches to any immediately following ''else'' statement.
*''else'' and ''else if'' clauses are optional.
int i = Math.Rand(0, 3);

if (i == 0) {
Interface.Print("i is 0");
}
else if (i == 1) {
Interface.Print("i is 1");
}
else {
Interface.Print("i is 2");
}
 

{{MethodHeader|<h4>include</h4>}}
*Syntax: ''include "filename.gs"''
*This statement must appear before any class declarations and will include the contents of the specified script file.
*It is generally sufficient to include the *.gs filename related to the immediate parent of your script.
 

{{MethodHeader|<h4>inherited</h4>}}
*an inherited() statement is made within a method definition to call the corresponding method in the immediate parent of the class.
*inherited() returns the same type, and takes the same parameters as the parent method.
*Inheritance is central to Object Oriented Programming, you should not omit these calls.
 

{{MethodHeader|<h4>mandatory</h4>}}
*mandatory is a method specifier which indicates that, if the method is over-ridden the over-ridden method '''must''' call ''inherited''.
 

{{MethodHeader|<h4>me</h4>}}
*me refers to the current object, similar to ''self'' or ''this'' keywords in other languages.
*me is often understood if not stated, these statements would have the same effect:
me.SetMeshAnimationState();
SetMeshAnimationState()
 

{{MethodHeader|<h4>native</h4>}}
*A method specifier which indicates that the method is implemented by the game rather than in script code.
 

{{MethodHeader|<h4>null</h4>}}
*null is an uninitialised expression.
*Every reference that is not assigned to an object has the value null.
*Assigning null to an existing object will delete the reference to that object.
 

{{MethodHeader|<h4>on</h4>}}
*see [[#wait|wait]]()
 

{{MethodHeader|<h4>public</h4>}}
*A specifier indicating that the member or method is accessible from outside the current class.
 

{{MethodHeader|<h4>return</h4>}}
*Exits immediately from the current method, used when the method return type is void.
*or exit from the current method returning ''value'' to the calling routine.
*Value must match the method return type.
 

{{MethodHeader|<h4>static</h4>}}
*''static'' is a class specifier denoting that only one instance of the class may exist.
*Static classes cannot be created using the new operator.
*To access a static class refer to its members or methods using the class name as follows:
static class owner {

public string forename; // public member
public string surname; // public member
public string GetName(void) { // public method
return forename + " " + surname;
}

};

class postbox isclass MapObject {

public void Init(void) {
if (!owner.forename) owner.forename = "Fred";
if (!owner.surname) owner.surname = "Bloggs";
Interface.Print(owner.GetName());
}

}
*Since only one instance of owner may exist it will be created along with the first instance of the postbox obect
*Any future postboxes will find the members of the owner class already initialised and ready for use.
 

{{MethodHeader|<h4>switch</h4>}}
*See ''[[#case|case]]''.
 

{{MethodHeader|<h4>thread</h4>}}
*A ''thread'' is a method which runs independently of the main script code.
*''threads'' can be started and synchronised by standard methods or other threads but are allowed to wait for events or to carry out tasks requiring periods of inactivity without interrupting the main program flow.
*Threaded methods may only be declared in classes extending the GameObject class or its children.
*Many threads (up to 64) may be running on the same game object instance at a time.
class Tutorial isclass Buildable {

bool doorsOpen = false;

public void Init(void) {
inherited();
AddHandler(me,"Object","","ObjectHandler");
}

thread void RingTheBell(void) {
while (doorsOpen) {
Sleep(0.35 + World.Play2DSound(GetAsset(),"bell.wav"));
}
}

void ObjectHandler(Message msg) {
if (msg.minor == "Enter") {
doorsOpen = true;
RingTheBell();
}
else doorsOpen = false;
}

};
*In the above the ''thread RingTheBell'' is started on an ''Object,Enter'' message and will terminate on any other ''Object'' message, irrespective of other code within the class.
 

{{MethodHeader|<h4>true</h4>}}
*Boolean constant
!false = true
 

{{MethodHeader|<h4>void</h4>}}
*''void'' is a null type used in two situations:
*to indicate that a method requires no parameters
*to indicate that a method does not return a value
public void DoTheDo(void);
 

{{MethodHeader|<h4>wait</h4>}}
*''wait'' is a control flow statement that suspends execution of a thread pending receipt of a message of a given type.
*It can listen for multiple message types using the on statement.
*When a wait statement is executed, execution stops on the thread until one of the on conditions is met.
wait() {
on "hello", "world" : {
// code here will execute for any ''hello,world'' message and then continue to wait for other messages.
continue;
}
on "hi", "there" : {
// code here will execute for any ''hi,there'' message and then exit the loop.
break;
}
on "hey", "" :
{
// code here will execute for any message with a major type of
// "hey" this will break by default, terminating the wait() loop.
}
}
 

{{MethodHeader|<h4>while</h4>}}
*A ''while(condition)'' is a loop control method that will continue as long as its condition evaluates to true.
*Note that if the condition is initially false the loop will not run at all
int i = 5;
while (i > 0) {
Interface.Print("i is greater than zero");
}
 

=Categories=
[[Category:TrainzScript]]

Types

2020-12-28T14:08:52Z

Danny252: Add links between language reference pages

* [[TrainzScript Language Reference]]
** [[Comments & Delineation]]
** [[TrainzScript Keywords]]
** [[Operators]]
** [[Types]]
 

== Types ==

{{anchor|bool}}{{MethodHeader|bool}}
*Contains the Boolean constants ''true'' or ''false''
*Casting an integer of value 0 to a bool will result in ''false'', any other value will result in ''true''.
!false = true
(bool) 0 = false
 

{{anchor|int}}{{MethodHeader|int}}
*32 bit integer
*Range from -2147483647 .. 2147483647
Formats
100
+100
-100
0x0f (Tested only in T:ANE)
 

{{anchor|float}}{{MethodHeader|float}}
*32 bit floating number
Formats
1.0
1.0f
polish notation?
 

{{anchor|object}}{{MethodHeader|object}}
*''object'' is a base class which may be used to store references to objects of any class.
 

{{anchor|string}}{{MethodHeader|string}}
*Strings can be indexed as arrays.
*Strings support the following escape sequences
\r ?
\n New line
\t Tab character
\l ?
\a ?
\b ?
\\ Backslash
\" Double quote mark
\' Single quote mark
\0 ?
 

{{anchor|Array}}{{MethodHeader|Array Types}}
*Arrays are indexed lists of any base type or any class type including GameObjects.
*Arrays are declared using these statements
Train[] trains;
int[] Numbers = new int[n]; // where ''n'' is the number of items in the array.
*The keyword ''new'' creates the array but does not initialise any of the members
Numbers[3] = 256; // assigns a value to the array. Array indices start at zero
*Arrays may also be returned by methods
Signal[] signals = World.GetSignalList() // creates an array of signals from a built in method
Numbers[Numbers.size()] = 5; // adds a new value after the end of the array, increasing its size by 1
Numbers[0,1] = null; // deletes the first value from the array, decreasing its size by 1
 

=Categories=
[[Category:TrainzScript]]

Comments & Delineation

2020-12-28T14:08:48Z

Danny252: Add links between language reference pages

* [[TrainzScript Language Reference]]
** [[Comments & Delineation]]
** [[TrainzScript Keywords]]
** [[Operators]]
** [[Types]]
 
==Comments==
{{MethodHeader|//}}
*Single line comment, text before the next carriage return will be ignored by the compiler.

{{MethodHeader|/* */}}
*Block comment.
*Text between the two character pairs '/*' and '*/' will be ignored.
*This convention can be used to temporarily disable the execution of sections of code.
*Block comment tags cannot be nested but they can enclose single line comments.

==Delineation==
{{MethodHeader|:}}
*Marks the end of a label declaration.
*see ''on, switch, case, default, label''

{{MethodHeader|;}}
*Marks the end of a statement.

{{MethodHeader|{ } }}
*Delineates the extent of a compound statement or method declaration.

{{MethodHeader|{ };}}
*Delineates the extent of a class declaration.

=Categories=
[[Category:TrainzScript]]

Operators

2020-12-28T14:08:40Z

Danny252: Add links between language reference pages

The operator sections set out below follow the language's preference rules. The earlier the operator appears in the list, the higher the precedence and the earlier the listed operators will be evaluated.

* [[TrainzScript Language Reference]]
** [[Comments & Delineation]]
** [[TrainzScript Keywords]]
** [[Operators]]
** [[Types]]

__NOEDITSECTION__
==Operators (1), Grouping & Indexing==
{{MethodHeader|( )}}
*Expression grouping.
*In common with most programming languages Trainzscript carries out arithmetical operations in the order defined by operator precedence rules.
*''3 + 2 * 12 - 7'' would return 20, because multiplication is of higher precedence than addition and subtraction.
*You can force the compiler to change this sequence and make your intentions crystal clear by declaring this as ''((3 + 2) * 12) - 7''.

{{MethodHeader|[ i ]}}
*Array and string indexing.
*Arrays are zero based and ''arrayName[0]'' will represent the first element.
*Similarly ''arrayName[arrayName.size() - 1]'' will represent the last element.
*A call to a value outside the range ''[0 … size()-1]'' will generate an exception.
*This notation can also be used to return a single character from a string.

intArray[intArray.size()] = 5 // will add the new value of 5 to the end of the array.

{{MethodHeader|[ i , j ]}}
*Array and String range index.
*The expression ''string[0,string.size()]'' will return the entire string.
*The integers i and j are best thought of as 'cursor' positions where i is the first element and j is one beyond the last element.
*If i is omitted the range will start at the beginning of the array (index 0).
*If j is omitted the range will end after the end of the array (.size()).
*To return a single element other than the first or last, both i and j are required.
*Given the declaration ''string s = "abcde"''
s[,3] = "abc"
s[2,3] = "c"
s[2,] = "cde"

intArray[2,3] = null // will delete the third element of the array.

{{MethodHeader|[ i , ]}}
*Indexes from i to the end of the string or array inclusively.
s[2,] = "cde"

{{MethodHeader|[ , j ]}}
*Indexes from the start of the string or array to element j-1 inclusively.
s[,3] = "abc"

{{MethodHeader|.}}
*Dereference operator
GetAsset().GetConfigSoup();
*The ''GetConfigSoup()'' method to be called is the method defined for the class ''GetAsset()''.

{{MethodHeader|!}}
*Not Operator
!true = false
!vehicle = null

==Operators (2), Incremental and Unary Operators==
{{MethodHeader|++}}
*Increments a numeric value by 1.
*Often used for control variables in loops:
for(n = 0; n < list.size(); n++) {
DoStuffWith(n);
}
*Increments n by 1 on each pass through the loop.

{{MethodHeader|--}}
*Decrements a numeric value by 1.
*Often used for control variables in loops:
n = list.size() - 1;
while(n >= 0) {
DoStuffWith(n);
n--;
}
*Decrements n by 1 on each pass through the loop.

{{MethodHeader|+}}
*Unary plus.
*Used to denote that a value is positive.

{{MethodHeader|-}}
*Unary minus.
*Used to denote that a value is negative.

==Operators (3), Casts==
{{MethodHeader|<h5>(bool)</h5>}}
*Boolean type cast.
(bool) 0 = false
(bool) 0.0 = false
(bool) n = true //where n is greater than zero

{{MethodHeader|<h5>(int)</h5>}}
*Integer type cast.
(int) 5.0 = 5
(int) true = 1

{{MethodHeader|<h5>(float)</h5>}}
*Float type cast.
(float) 100 = 100.0
(float) false = 0.0

{{MethodHeader|<h5>(string)</h5>}}
*String type cast.
(string) 1 = "1"
(string) 0.99 = "0.99"
(string) false = "false";

{{MethodHeader|(''reference'')}}
*Class type cast.
How is this used and how is it different from cast<Class>?

{{MethodHeader|<h5>cast</h5>}}
*Dynamic cast.
*Returns null if the reference cannot be converted to the class specified by className.
*Note that ancestors of the specified class will be returned.
Vehicle vehicle = cast<Vehicle>msg.src;

MeshObject meshObject;
GameObject gameObject = cast<GameObject>meshObject; // returns meshObject if the object exists, null otherwise

{{MethodHeader|<h5>size()</h5>}}
*Returns the number of members of an array or the length of a string.
*In the case of an array this does not necessarily mean that all (or any) of the members actually contain values.
given string s = "abcde";
s.size() = 5;

int[] numbers = new int[5]; // creates an empty array of 5 integers
numbers.size() = 5;

{{MethodHeader|<h5>copy()</h5>}}
*Creates a copy of an array or string.
*This is different from a simple assignment which points a variable to the same memory address as an existing variable.
*Array.copy() or string.copy() creates an additional copy of the data.
int[] numbers = new int[5];
int[] moreNumbers;

moreNumbers.copy(numbers); // duplicates numbers

{{MethodHeader|<h5>isclass()</h5>}}
*Used in the declaration of a new class identifier
class MyScript isclass Vehicle {
classMethods();
};
*Used to test whether a given reference is to a specific class.
given the declaration:
TrackLoadInfo info = new TrackLoadInfo();

info.isclass(TrackLoadInfo); // returns true

{{MethodHeader|<h5>new</h5>}}
*Creates a new instance of the specified type.
int[] numbers = new int[4]; // creates an integer array containing 4 members.
TrackLoadInfo info = new TrackLoadInfo(); // creates a new instance of the TrackLoadInfo class.
*new does not initialise the members.
*GameObject classes cannot be created using new.

==Operators (4), Multiplication & Division==
{{MethodHeader|*}}
*Multiplication.
*If both terms are integers the result will be an integer.
*If either term is a float the result will be a float.
2 * 5 = 10;
2 * 5.0 = 10.0;

{{MethodHeader|/}}
*Division.
*If both terms are integers the result will be an integer, possibly with a remainder.
*If either term is a float the result will be a float.
10 / 5 = 2;
10 / 5.0 = 2.0;
10 / 6 = 1;

{{MethodHeader|%}}
*Remainder or modulus operator.
*Returns the remainder from an integer division.
5 % 2 = 1;
105 % 50 = 5;
105 % 100 = 5;

==Operators (5), Addition & Subtraction==
{{MethodHeader|+}}
*Addition
*If both terms are integers the result will be an integer.
*If either term is a float the result will be a float.
1 + 1 = 2;
1 + 1.0 = 2.0;

{{MethodHeader|-}}
*Subtraction
*If both terms are integers the result will be an integer.
*If either term is a float the result will be a float.
2 - 1 = 1;
2 - 1.0 = 1.0;

==Operators (6), Shifts==
{{MethodHeader|<<}}
*Shift Left
*Bitwise operator moves all of the binary values to the left by the number of places specified in the second term.
*Binary zero is appended.
*Provided there is no overflow the result is a doubling of the value for each shift.
8 << 1 = 16
8 << 2 = 32

{{MethodHeader|>>}}
*Shift Right
*Bitwise operator moves all of the binary values one place to the right by the number of places specified in the second term.
*Binary zero is prepended and any displaced bits are discarded.
*The result is an integral halving of the value for each shift.
8 >> 1 = 4
9 >> 2 = 2

==Operators (7), Comparisons==
{{MethodHeader|<}}
* Is less than.
*Comparison operator which can be used on string, float, integer and bool values.
*Returns true if the first term is less than the second.
1 < 2 = true;
false < false = false;
"abc" < "def" = true;

{{MethodHeader|<=}}
*Is less than or equal.
*Comparison operator which can be used on string, float, integer and bool values.
*Returns true if the first term is less than or equal to the second.
1 <= 2 = true;
false <= false = true;
"abc" <= "def" = true;

{{MethodHeader|>}}
*Is greater than.
*Comparison operator which can be used on string, float, integer and bool values.
*Returns true if the first term is greater than the second.
1 > 2 = false;
true > false = true;
"abc" > "def" = false;

{{MethodHeader|>=}}
*Is greater than or equal.
*Comparison operator which can be used on string, float, integer and bool values.
*Returns true if the first term is greater than or equal to the second.
1 >= 2 = false;
true >= true = true;
"abc" >= "def" = false;

==Operators (8), Equality==
{{MethodHeader|==}}
*Is equal.
*Comparison operator which can be used on string, float, integer and bool values and on object references.
*Returns true if the first and second terms are equal or if they evaluate to the same object.
int a = 0;
int b = 0;
a == b; // returns true
*Note that ''a = b'' is an assignment and will always return true. Mistyping '''''=''''' for '''''==''''' is one of the most common semantic errors in Trainzscript.

{{MethodHeader|!=}}
*Is not equal.
*Comparison operator which can be used on string, float, integer and bool values and on object references.
*Returns true if the first and second terms are not equal and do not evaluate to the same object.
int a = 0;
int b = 0;
a != b; // returns false

==Operators (9), Bitwise Operators==
{{MethodHeader|&}}
*Bitwise AND
*Performs a bit by bit comparison of two integers and returns a new value.
*Each bit in the result is set if BOTH of the corresponding bits in the arguments are set
0000 1111
& 0001 0111
= 0000 0111

15 & 23 = 7

{{MethodHeader|^}}
*Bitwise XOR
*Performs a bit by bit comparison of two integers and returns a new value.
*Each bit in the result is set if EITHER BUT NOT BOTH of the corresponding bits in the arguments are set
0000 1111
^ 0001 0111
= 0001 1000

15 ^ 23 = 24

{{MethodHeader|¦}}
*Bitwise OR
*Performs a bit by bit comparison of two integers and returns a new value.
*Each bit in the result is set if EITHER of the corresponding bits in the arguments are set
0000 1111
| 0001 0111
= 0001 1111

15 | 23 = 31

{{MethodHeader|~}}
*Bitwise Inverse
*Takes the binary representation of the integer and inverts each bit.
*Useful in masking out values from bitfields (eg. flags &= ~SOME_FLAG; switches off the SOME_FLAG bit from 'flags')
~0011 1101 = 1100 0010
~1000 0100 = 0111 1011

~0 = -1
~255 = -256
~5 = -6

==Operators (10), Logical Operators==
{{MethodHeader|<h5>and</h5>}}
*Logical AND
*Enables multiple boolean expressions to be combined.
if (msg.minor == "Enter" and doorsOpen)

{{MethodHeader|<h5>or</h5>}}
*Logical OR
*Enables multiple boolean expressions to be combined.
if (msg.minor == "Enter" or doorsOpen)
if ((msg.minor == "Enter" and doorsOpen) or (msg.minor == "Leave" and !doorsOpen))

==Operators (11), Assignment==
{{MethodHeader|=}}
*Assignment Operator
a = 1;
Train train = World.GetTrainList()[0];

The assignment operator sets the variable on the LHS of the expression to the same value as the variable on the RHS.

Note that string and array are object types, not primitive types. Therefore, like all objects, assignment of a string or array object means that the variable on the LHS of the assignment expression refers to the same object (that is, the same string or the same array) as the variable on the RHS. A new copy of the object is not created. If the intention is to make an assignment to a new object that is a copy of the original, you should use the .copy() method of the string or array objects, or the .clone() method (if available) of other objects.

{{MethodHeader|,}}
*Expression or parameter separator.

=Categories=
[[Category:TrainzScript]]

Class InterlockingTowerPath

2020-12-28T13:51:22Z

Danny252: Add standard API hierarchy

The InterlockingTowerPath class is the script representation of an individual Interlocking Tower "Path". In this context a path represents the track that a train can take through an Interlocking Tower controlled area. It is defined by a number of trackside objects (signals, junctions and crossings) and the state that those objects must be in to allow the train passage through that path. Each path has an entry and exit signal. When a train approaches an entry signal the Interlocking Tower (and related libraries) will attempt to assign it a specific path, so that it may pass the signal.

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****InterlockingTowerPath

==Related Classes==
* [[Class InterlockingTower|InterlockingTower]]
* [[Class Signal|Signal]]
* [[Class Junction|Junction]]
* [[Class Crossing|Crossing]]
* [[Class TrackCircuitBlock|TrackCircuitBlock]]
* [[Class TrackPathDisplay|TrackPathDisplay]]

==Common functions==
Below is a list of some of the basic common functions on the InterlockingTower script class. This list is not intended to be comprehensive, merely provide an overview.

 {{MethodHeader|public mandatory void Init(InterlockingTower tower, SecurityToken token)}}
;Description
Initialises the path with the parameters defined, if possible. Will throw an exception and return false if the request is invalid.
;Parameters
*tower - The calling interlocking tower.
*token - A SecurityToken from the owning InterlockingTower, with sufficient rights to activate the path.

 {{MethodHeader|public void SetPathName(string pathName)}}
;Description
Sets the identifying path name. This should be unique within the owning tower.
;Parameters
*pathName - The new identifying name for the tower path.

 {{MethodHeader|public string GetPathName()}}
;Description
Returns the identifying path name for this tower path.

 {{MethodHeader|public string GetLocalisedPathName()}}
;Description
Returns the localised path name for this tower path. Localised names are stored in the string-table for the route or session. There is no interface to set this and it must be done by the session creator.

 {{MethodHeader|public bool IsObjectInPathDefinition(MapObject obj, int childIndex, bool bIncludeExternalRequirements)}}
;Description
Returns whether a given object is part of the definition of this path.
;Parameters
*obj - The path object (junction, signal, etc) to search for.
*childIndex - The index of a child object, or -1 for the object itself.
*bIncludeExternalRequirements - Whether to also check the external requirement list.
;Returns
*bool - true if the object was found, false otherwise

 {{MethodHeader|public bool IsObjectOnPath(MapObject obj)}}
;Description
Performs a track search and returns whether the passed object is on the path somewhere. Avoid calling this often as it can be quite intensive.
;Parameters
*obj - The map object to search the path for.
;Returns
*bool - Whether the object was found on the path.

 {{MethodHeader|public bool IsObjectOnOrBeyondPath(MapObject obj)}}
;Description
Returns whether a given object is on this path, or lies on the track beyond the exit signal. Note that searching beyond the path will follow the currently set junction directions.
;Parameters
*obj - The map object to search the path for.
;Returns
*bool - Whether the object was found on the path, or within the search range beyond the path.

 {{MethodHeader|public int GetPathClearMethod()}}
;Description
Returns the currently set path clear method, which is one of the ITP_CLEAR_* defines.

 {{MethodHeader|public void SetPathClearMethod(int clearMethod)}}
;Description
Alters the path clear method for this path.
;Parameters
*clearMethod - The new clearing method to set, one of the ITP_CLEAR_* defines.

 {{MethodHeader|bool CanTransitionPathToState(int state)}}
;Description
Returns whether this path is in a state where it's possible to begin to transition to the state passed. When creating a custom tower script this is an ideal place to perform extra checks for path state changes.
;Parameters
*state - The state we want to transition to.
;Returns
*bool - true if the path is able to transition to the requested state, false otherwise.

 {{MethodHeader|public void ActivatePath(SecurityToken token)}}
;Description
Begins activating the path, if possible. Will post a message to the owning tower of type "InterlockingTowerPath","Active" when the path is set.
;Parameters
*token - A [[SecurityToken]] from the owning tower with rights "path-control".

 {{MethodHeader|public void CancelPath(SecurityToken token)}}
;Description
Begins cancelling the path, if possible. Will post a message to the owner of type "InterlockingTowerPath","Cancelled" when the path is cancelled. This will return all controlled objects to their original state if appropriate, based on m_clearState.
;Parameters
*token - A [[SecurityToken]] from the owning tower with rights "path-control".

 {{MethodHeader|public void SetPanicState(SecurityToken token)}}
;Description
Instantly drops all controlled signals along this path. Does not change junction or crossing state. Used to simulate an emergency situation of some kind. To transition out of a panic state call either ActivatePath or CancelPath.
;Parameters
*token - A [[SecurityToken]] from the owning tower with rights "path-control".

 {{MethodHeader|public void AddTrain(SecurityToken token, Train train)}}
;Description
Adds the train passed to this path. Does not perform any validation on this operation and will warrant all requests from a valid source.
;Parameters
*token - A [[SecurityToken]] from the owning tower with rights "path-control".

 {{MethodHeader|public void RemoveTrain(SecurityToken token, Train train)}}
;Description
Removed the train passed from this path. Performs no validation on the operation and will warrant all requests from a valid source.
;Parameters
*token - A [[SecurityToken]] from the owning tower with rights "path-control".

 {{MethodHeader|public bool IsOccupiedByTrain(Train train, bool bRequireHasClearedEntrySignal)}}
;Description
Returns whether the path is known to be occupied by a specific train. Does not perform any track searching and is reliant on the owning tower correctly calling AddTrain/RemoveTrain.
;Parameters
*train - The train to check for.
*bRequireHasClearedEntrySignal - If true, return true only if the train has cleared the entry signal and is occupying the path, otherwise it's sufficient that the tower has merely 'added' the train.
;Returns
*bool - Whether the train has been added to the path and, optionally, has passed the entry signal.

 {{MethodHeader|public void EnablePathVisualisation(bool enable, bool bShouldIncludeAllTCBs)}}
;Description
Enables/disables visualisation of this path in the game world, using [[TrackPathDisplay]].
;Parameters
*enable - true to enable the path visualisation, false to disable it
*bShouldIncludeAllTCBs - Whether to also add path visualisations for every occupied [[TrackCircuitBlock]].

Class InterlockingTower

2020-12-28T13:51:13Z

Danny252: Add standard API hierarchy

The InterlockingTower class is the script representation of an in game Interlocking Tower (aka Signal Tower). Interlocking Towers are used to define track "paths" that trains can travel down.

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****[[Class TrainzGameObject|TrainzGameObject]]
*****[[Class MeshObject|MeshObject]]
*****[[Class PropertyObject|PropertyObject]] *
******[[Class MapObject|MapObject]]
*******InterlockingTower

==Related Classes==
* [[Class InterlockingTowerPath|InterlockingTowerPath]]
* [[Class Signal|Signal]]
* [[Class Junction|Junction]]
* [[Class Crossing|Crossing]]
* [[Class TrackCircuitBlock|TrackCircuitBlock]]
* [[Class TrackPathDisplay|TrackPathDisplay]]

==Common functions==
Below is a list of some of the basic common functions on the InterlockingTower script class. This list is not intended to be comprehensive, merely provide an overview.

 {{MethodHeader|public InterlockingTowerPath CreateNewPath()}}
;Description
Creates a new blank path for use by this tower. Any script which needs to create a path should call this function. Any tower which needs to customise the class can then just override this to create their type.
;Returns
*InterlockingTowerPath - A newly created and initialised [[InterlockingTowerPath]] object.

 {{MethodHeader|public string[] GetLocalisedPathNames()}}
;Description
Returns a list of the current (localised) path names.
;Returns
*string[] - A string array, containing the localised names of every path.

 {{MethodHeader|public InterlockingTowerPath FindPathByName(string pathName)}}
;Description
Finds and returns an interlocking path by name, or localised name (for the current language).
;Parameters
*pathName - The name (or localised name) of the path to find.
;Returns
*InterlockingTowerPath - The found [[InterlockingTowerPath]], or null if no match was found.

 {{MethodHeader|public InterlockingTowerPath[] GetConflictingPaths(InterlockingTowerPath path)}}
;Description
Builds an array of tower paths which have conflicts with the path passed. This will include any other path which shares an object in its path definition or external requirements.
;Parameters
*path - The [[InterlockingTowerPath]] to examine and find conflicts for.
;Returns
*InterlockingTowerPath[] - An array of tower paths which conflict with the path passed. If no conflicts are found this will be an empty array (i.e. not null).

 {{MethodHeader|public mandatory void SetAIState(int aiState)}}
;Description
Alters the current state of the towers automatic path selection processing.
;Parameters
*aiState - The new AI state for the tower, see PATH_ASSIGNMENT_* defines.
;Note
This function is 'mandatory', meaning that any overriding function must call the inherited() in order to compile.

 {{MethodHeader|public void AssignPathToTrain(Train train, string pathName)}}
;Description
Requests a specific path for the specified train. This will create a queue entry for the train if one doesn't already exist, set it's state to queued and set the path to that requested. The path may not be prepared immediately, if there are conflicting queued entries.
;Parameters
*train - The train to assign the path to.
*pathName - The name of the path to assign.

 {{MethodHeader|public void CancelPathForTrain(Train train, string pathName)}}
;Description
Cancels a specific path for the train passed. If the train is not known, or there is no InterlockingTrainPath entry for this train and signal, then no action will be taken.
;Parameters
*train - The train to cancel the path for.
*pathName - The name of the path to cancel.

 {{MethodHeader|public void SetPanicStateForPath(string pathName)}}
;Description
Sets as specific path to a panic state, dropping all signals immediately, regardless of any occupying or approaching trains.
;Parameters
*pathName - The name of the path to set to a panic/emergency state.

 {{MethodHeader|public void SetTrainAsPassing(Train train, Signal entrySignal)}}
;Description
Sets a train's state for a specific entry signal to STATE_PASSING, so the tower knows the train is not entering the interlocking, and will ignore it until it leaves the area. If the train is not known, or there is no InterlockingTrainPath entry for this train and signal, then no action will be taken.
;Parameters
*train - The train to set as passing.
*entrySignal - The path entry signal that the train is passing.

Class Constructors

2020-12-28T13:47:30Z

Danny252: Change link to library reference, not language reference

*[[TrainzScript Library Reference|API Hierarchy]]
**Constructors
 

*A static class providing the ability to create instances of certain other classes from script.
*Trainzscript does not normally allow game classs to be created in script, these methods allow for exceptions to this rule.
*The implementation is liable to change.
 

==GetTrainzAsset==
{{MethodHeader|public native Asset GetTrainzAsset(void)}}
;Parameters
*None
;Returned Value
*The global Trainz asset.
;Notes
*This method is used mainly by the built-in classes.
 

==GetTrainzStrings==
{{MethodHeader|public native StringTable GetTrainzStrings(void)}}
;Parameters
*None
;Returned Value
*The global Trainz StringTable.
;Notes
*This method is used mainly by the built-in classes.
 

==NewBrowser==
{{MethodHeader|public native Browser NewBrowser(void)}}
;Parameters
*None
;Returned Value
*A new empty Browser object.
;Syntax
Browser browser = Constructors.NewBrowser();
;Notes
 

==NewDriverCommand==
{{MethodHeader|public native DriverCommand NewDriverCommand(Asset command)}}
;Parameters
*'''command''' = reference to a ''DriverCommand'' asset from which the new command instance will be constructed.
;Returned Value
*A new DriverCommand instance for script use.
;Notes
*This method does not add a new command to the list of available driver commands returned by World.GetDriverCommandList() but simply creates a script instance for private use.
 

==NewDriverCommands==
{{MethodHeader|public native DriverCommands NewDriverCommands(void)}}
;Parameters
*None
;Returned Value
*A new empty DriverCommands list.
;Notes
 

==NewKUIDList==
{{MethodHeader|public native KUIDList NewKUIDList(void)}}
;Parameters
*None
;Returned Value
*A new KUIDList object, empty and unlocked.
;Syntax
KUIDList consist = Constructors.NewKUIDList();
;Notes
 

==NewMenu==
{{MethodHeader|public native Menu NewMenu(void)}}
;Parameters
*None
;Returned Value
*A new empty Menu object.
;Syntax
Menu menu = Constructors.NewMenu();
;Notes
*The menu returned is for setup purposes only, this method does not create any visual representation.
 

==NewProductFilter==
{{MethodHeader|public native ProdutFilter NewProducFilter(void)}}
;Parameters
*None
;Returned Value
*A new ProdutFlter object, empty and unlocked.
;Syntax
ProductFilter filter = Constructors.NewProductFilter();
;Notes
 

==NewSoup==
{{MethodHeader|public native Soup NewSoup(void)}}
;Parameters
*None
;Returned Value
*A new Soup object, empty and unlocked.
;Syntax
Soup soup = Constructors.NewSoup();
;Notes
 

==Categories==
[[Category:Script Class]]

Class JunctionBase

2020-12-28T13:47:17Z

Danny252: Change link to library reference, not language reference

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****[[Class TrainzGameObject|TrainzGameObject]]
****[[Class PropertyObject|PropertyObject]] *
*****[[Class MeshObject|MeshObject]]
******[[Class MapObject|MapObject]]
*******JunctionBase *

 
*Interface methods to control and obtain information about the status of Junction objects.
*This class relates equally to switch levers controlling spline track junctions and to the junction nodes attached to Fixed Track Junction objects.
 

==Constants & Messages==

===Junction States===
*These values define the directions possible through a junction object.
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int DIRECTION_LEFT = 0 ||Left junction direction.
|-
|public define int DIRECTION_FORWARD = 1 ||Forward junction direction (straight on for three way points).
|-
|public define int DIRECTION_RIGHT = 2 ||Right junction direction.
|-
|public define int DIRECTION_BACKWARD = -1 ||Backward junction direction (leading approach).
|-
|public define int DIRECTION_NONE = 3 ||No junction direction or error condition.
|}
 

==Related Messages==
*Messages sent to and from Junction objects are listed below:
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''
|-
|Junction||Toggled||Junction||Broadcast
|-
|[[Object Messages|Junction]]||Enter||Junction||Train
|-
|[[Object Messages|Junction]]||InnerEnter||Junction||Train
|-
|[[Object Messages|Junction]]||Stopped||Junction||Train
|-
|[[Object Messages|Junction]]||InnerLeave||Junction||Train
|-
|[[Object Messages|Junction]]||Leave||Junction||Train
|-
|[[Object Messages|Object]]||Enter||Train||Junction
|-
|[[Object Messages|Object]]||InnerEnter||Train||Junction
|-
|[[Object Messages|Object]]||Stopped||Train||Junction
|-
|[[Object Messages|Object]]||InnerLeave||Train||Junction
|-
|[[Object Messages|Object]]||Leave||Train||Junction
|}
 

==Methods==

===AllowManualControl===
{{MethodHeader|public native voidAllowManualControl(bool allow)}}
;Parameters
*'''allow''' = True to allow the user to toggle the junction, false otherwise.
;Returned Value
*None
;Syntax;
AllowManualControl(true);
;Notes
 

===GetDebugString===
{{MethodHeader|public string GetDebugString(void)}}
;Parameters
*None
;Returned Value
*A string that contains the node ID and name of the MapObject associated with this junction. If successful, the returned string will include the node ID and name of the MapObject. Otherwise an error string will be returned instead.
;Syntax;
Interface.Print(GetDebugString());
;Notes
 

===GetDirection===
{{MethodHeader|public native int GetDirection(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Junction States|Junction State]] constants indicating the current direction of the junction.
;Syntax;
int direction = GetDirection();
;Notes
 

===GetDirectionToTrain===
{{MethodHeader|public native int GetDirectionToTrain(Train train)}}
;Parameters
*'''train''' = A reference to a train located within 15 track stretches of the junction.
;Returned Value
*One of the [[#Junction States|Junction State]] constants indicating the track on which the train was found.
;Syntax;
int approachPath = GetDirectionToTrain(train);
;Notes
*DIRECTION_NONE is returned if the train is not within range.
 

===GetGameObject===
{{MethodHeader|public native GameObject GetGameObject(void)}}
;Parameters
*None
;Returned Value
*A reference to the GameObject associated with this junction.
;Syntax;
GameObject go = junction.GetGameObject();
;Notes
*For a trackside spline junction this method returns the junction lever object.
*For an embedded junction in a fixed track junction the object returned is the embedded junction node.
*In either case null is returned on failure.
 

===GetManualControl===
{{MethodHeader|public native bool GetManualControl(void)}}
;Parameters
*None
;Returned Value
*True if the user is allowed to toggle this junction, false otherwise.
;Syntax;
bool locked = !GetManualControl();
;Notes
 

===GetMapObject===
{{MethodHeader|public native MapObject GetMapObject(void)}}
;Parameters
*None
;Returned Value
*A reference to the MapObject associated with this junction.
;Syntax;
MapObject mo = junction.GetMapObject();
;Notes
*For a trackside spline junction this method returns the junction lever object.
*For an embedded junction in a fixed track piece the object returned is the fixed track parent object.
*In either case null is returned on failure.
 

===JunctionInnerReEnter===
{{MethodHeader|public native bool JunctionInnerReEnter(int node)}}
;Parameters
*'''node''' = Node Id of train as returned by Train.GetId().
;Returned Value
*None
;Syntax;
junction.JunctionInnerReEnter(train);
;Notes
*The effect of this method is to cause a new ''Junction,InnerEnter'' message to be sent to the Junction if any part of the train is within the inner trigger radius.
 

===JunctionReEnter===
{{MethodHeader|public native bool JunctionReEnter(int node)}}
;Parameters
*'''node''' = Node Id of train as returned by Train.GetId().
;Returned Value
*None
;Syntax;
junction.JunctionReEnter(train);
;Notes
*The effect of this method is to cause a new ''Junction,Enter'' message to be sent to the Junction if any part of the train is within the default outer trigger radius.
 

===RequestPermit===
{{MethodHeader|public native Permit RequestPermit(GameObject obj)}}
;Parameters
*'''obj''' = Object requesting the [[Class Permit|Permit]].
;Returned Value
*Returns a Permit for ''obj'' to control the junction.
;Syntax;
Permit permit = RequestPermit(train);
;Notes
*Although a Permit is always returned, it may not necessarily be granted.
 

===RequestTrackPermit===
{{MethodHeader|public native Permit RequestTrackPermit(GameObject obj, int direction)}}
;Parameters
*'''obj''' = Object requesting the [[Class Permit|Permit]].
*'''direction''' = One of the [[#Junction States|Junction State]] constants indicating the direction of the track relative to the current junction.
;Returned Value
*Returns a Permit for ''obj'' to control the specified track.
;Syntax;
Permit permit = RequestTrackPermit(train, DIRECTION_LEFT);
;Notes
*Although a Permit is always returned, it may not necessarily be granted.
 

===SetDirection===
{{MethodHeader|public native bool SetDirection (int direction)}}
;Parameters
*'''direction''' = New direction to set.
;Returned Value
*True if the junction is changed, False if the direction is unchanged or if the specified direction was invalid for this junction.
;Syntax;
if (junction.SetDirection(DIRECTION_LEFT)) Interface.Print("Junction now set to the left");
;Notes
*This method switches the junction unconditionally, disregarding any Permits that may exist.
 

===SwitchForTrain===
{{MethodHeader|public native bool SwitchForTrain(Train train, int direction)}}
;Parameters
*'''train''' = Train that is to pass over the junction.
*'''direction''' = One of the [[#Junction States|Junction State]] constants indicating the current position of the train relative junction.
;Returned Value
*True if the junction is changed, False if the direction is unchanged or if the specified direction was invalid for this junction.
;Syntax;
junction.SwitchForTrain(train,DIRECTION_BACKWARD);
;Notes
*The new direction must be on the opposite side of the junction to the train's current position.
*This method switches the junction unconditionally, disregarding any Permits that may exist.
 

==Related Methods==
[[Class SceneryWithTrack#GetAttachedJunctions|SceneryWithTrack.GetAttachedJunctions()]] 
[[Class World#GetJunctionList|World.GetJunctionList()]] 
 

==Categories==
[[Category:Script Class]]

Class Train

2020-12-28T13:47:13Z

Danny252: Change link to library reference, not language reference

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****Train

 
*A train is a collection of vehicles in TRS.
*They act as a single entity and may be controlled using this class.
*A train is placed on a track in script by using [[Class World#CreateTrain|World.CreateTrain()]] or [[Class TrainUtil#CreateTrainFromSoup|TrainUtil.CreateTrainFromSoup()]].
*Trainz will automatically create a Train object for each consist that appears in the game.
*When an existing train is uncoupled and split up into two separate consists a new train object is created.
*Similarly when two trains couple one of the train objects is destroyed.
 

==Messages==
*Messages sent to and from Train objects are listed below:
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''
|-
|Schedule||Abort||Train||Train
|-
|Schedule||Complete||Train||Broadcast
|-
|Schedule||Touch||Train||Train
|-
|[[Train Messages|Train]]||Deleted||Train||
|-
|[[Signal Messages|Train]]||Entered red signal notify||Train||Broadcast
|-
|[[Signal Messages|Train]]||Entered red signal||Signal||Train
|-
|[[Object Messages|Train]]||EnterTrack||Track||Train
|-
|[[Object Messages|Train]]||InnerEnterTrack||Track||Train
|-
|[[Object Messages|Train]]||InnerLeaveTrack||Track||Train
|-
|[[Object Messages|Train]]||LeaveTrack||Track||Train
|-
|[[Train Messages|Train]]||Over advisory speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Over floating speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Over speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||ReachedTarget||Train||Train
|-
|[[Train Messages|Train]]||SlowingForTarget||Train||Train
|-
|[[Train Messages|Train]]||StartedMoving||Train||Train
|-
|[[Train Messages|Train]]||StoppedMoving||Train||Train
|-
|[[Train Messages|Train]]||Under advisory speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Under floating speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Under speed limit||Train||Broadcast
|}
 

==Constants==
 
===Train Control Modes===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CONTROL_MANUAL = 1||User controls train, script can change settings.
|-
|public define int CONTROL_AUTOPILOT = 2||Autopilot controls train.
|-
|public define int CONTROL_AUTOMANUAL = 3||User controls train, autopilot takes over when train is not currently 'focused'.
|-
|public define int CONTROL_SCRIPT = 4||Only the script can control the train.
|}
 
===Train Physics Modes===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int PHYSICS_DCC = 1||DCC mode.
|-
|public define int PHYSICS_SIMULATION = 2||Cab mode.
|}
 
===Reverser Traction Modes===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int TRACTION_FORWARD = 2||Reverse is in forward setting.
|-
|public define int TRACTION_NEUTRAL = 1||Reverser is in neutral.
|-
|public define int TRACTION_REVERSE = 0||Reverser is in reverse.
|}
 
===Train Brake Modes===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float TRAIN_BRAKE_RELEASE = 0.0||Train brakes are released.
|-
|public define float TRAIN_BRAKE_INITIAL = 1.0||Train brakes are in initial mode.
|-
|public define float TRAIN_BRAKE_APPLICATION = 2.0||Train brakes are applied.
|-
|public define float TRAIN_BRAKE_HANDLE_OFF = 3.0||Train brake handle is off.
|-
|public define float TRAIN_BRAKE_EMERGENCY = 4.0||Train brakes are in emergency stop position.
|-
|public define float TRAIN_BRAKE_LAP = 5.0||Train brakes are in the lap position, not available for all trains.
|}
 
===Dynamic Brake States===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int DYNAMIC_BRAKE_TRACTION = 0||Dynamic brakes in traction mode.
|-
|public define int DYNAMIC_BRAKE_NEUTRAL = 1 ||Dynamic brakes in neutral.
|-
|public define int DYNAMIC_BRAKE_BRAKE = 2 ||Dynamic brakes are on.
|}
 

===Found Results===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int RESULT_NONE = 0||Item not found.
|-
|public define int RESULT_FORWARD = 1||Item is in front of train.
|-
|public define int RESULT_INSIDE = 2||Item is within the train, ie between the front and the rear limits.
|-
|public define int RESULT_BACKWARD = 3||Item is behind the train.
|}
 
===Measurement Conversion Multipliers===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float KPH_TO_MPS = 0.278||Kilometres per hour -> Metres per second.
|-
|public define float MPH_TO_MPS = 0.447||Miles per hour -> Metres per second.
|-
|public define float MPH_TO_KPH = 1.609||Miles per hour -> Kilometres per hour.
|}
 

==Members==
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public Browser timeTableInfo||A publicly accessible Browser object for timetable information.
|}
 
==Methods==
 

===AddVelocity===
{{MethodHeader|public native void AddVelocity(float velocity)}}
;Parameters
*'''velocity''' = Velocity to add to the current speed of the train.
;Returned Value
*None
;Syntax
train.AddVelocity(5.0);
;Notes
*Velocity parameter must be in metres per second and may be negative.
*Use the [[#Measurement Conversion Multipliers|Measurement Conversion Multipliers]] to convert from other units.
 

===ClearTrainTimetable===
{{MethodHeader|public void ClearTrainTimetable(ScenarioBehavior rule)}}
;Parameters
*'''rule''' = rule that called [[#SetTrainTimetable|SetTrainTimetable()]] on this train.
;Returned Value
*None
;Syntax
train.ClearTimeTable(timetableRule);
;Notes
*Clears the train timetable of this train.
*Having cleared the TrainTimetable, it is now safe again to set another TrainTimetable for this train through [[#SetTrainTimetable|SetTrainTimetable()]].
*This method must only be called by the rule which called SetTrainTimetable() in the first place.
*It is the responsibility of the caller to post a (TrainTimetable, Touch) message after calling this function.
 

===DecTrainBusy===
{{MethodHeader|public void DecTrainBusy(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.DecTrainBusy();
;Notes
*Decrements this train's busy count.
*See [[#IsTrainBusy|IsTrainBusy()]] for further details.
 

===Derail===
{{MethodHeader|public native void Derail(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.Derail();
;Notes
*Deliberately derails the train.
 

===EnablePhysics===
{{MethodHeader|public native void EnablePhysics(bool enable)}}
;Parameters
*'''enable''' = True to enable physics calculations for this train, false to disable
;Returned Value
*None
;Syntax
train.EnablePhysics(false);
;Notes
*Turning physics off for scenic rolling stock that the player cannot interact with can boost performance.
*There is no point in doing physic calculations for idle rollingstock.
 

===GetActiveDriver===
{{MethodHeader|public native DriverCharacter GetActiveDriver(void)}}
;Parameters
*None
;Returned Value
*The active driver of this train, null if there is no driver assigned.
;Syntax
DriverCharacter driver = train.GetActiveDriver();
;Notes
*There may be more than one driver on a train but there is only one active driver and an individual Locomotive may only have one driver assigned.
 

===GetAdvisoryLimit===
{{MethodHeader|public native float GetAdvisoryLimit(void)}}
;Parameters
*None
;Returned Value
*The current advisory speed limit set by script.
;Syntax
float speed = train.GetAdvisoryLimit();
;Notes
 

===GetAllowsUserContol===
{{MethodHeader|public native bool GetAllowsUserControl(void)}}
;Parameters
*None
;Returned Value
*True if this train allows the user to control it directly through DCC or Cabin interfaces, false otherwise.
;Syntax
bool canDrive =train.getAllowsUserControl();
;Notes
 

===GetAutopilotMode===
{{MethodHeader|public native int GetAutopilot Mode(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Train Control Modes|Train Control Mode]] constants defining the method by which the train is currently controlled.
;Syntax
int controlMode = train.GetAutopilotMode();
;Notes
 

===GetAutopilotStopJunctionBase===
{{MethodHeader|public native JunctionBase GetAutopilotStopJunctionBase(void)}}
;Parameters
*None
;Returned Value
*The junction object that is preventing the autopilot from taking this train any further, null if the train is not stopped by a junction.
;Syntax
JunctionBase junction = train GetAutopilotStopJunctionBase();
;Notes
 

===GetAutopilotStopTrain===
{{MethodHeader|public native Train GetAutopilotStopTrain(void)}}
;Parameters
*None
;Returned Value
*The train that is preventing the autopilot from taking this train any further, null if the train is not being held up by another train.
;Syntax
Train otherTrain = train.GetAutopilotStopTrain();
;Notes
 

===GetAutopilotTargetSlowing===
{{MethodHeader|public native bool GetAutopilotTargetSlowing(void)}}
;Parameters
*None
;Returned Value
*True if the autopilot is slowing down for its target destination, false otherwise.
;Syntax
bool isSlowing = train.GetAutopilotTargetSlowing();
;Notes
 

===GetDCCThrottle===
{{MethodHeader|public native float GetDCCThrottle(void)}}
;Parameters
*None
;Returned Value
*The DCC throttle setting for this train when using DCC physics.
;Syntax
float throttle = GetDCCThrottle();
;Notes
*The returned value will be in the range [-1.0 .. 1.0] where -1.0 is full throttle in reverse, 0.0 is stationary and 1.0 is full throttle forward.
 

===GetFrontmostLocomotive===
{{MethodHeader|public native Locomotive GetFrontmostLocomotive(void)}}
;Parameters
*None
;Returned Value
*Returns a reference to the frontmost locomotive in the train.
;Syntax
Loco = Train.GetFrontmostLocomotive();
;Notes
*The ''front'' of the train is defined relative to the train's current heading.??
*The train's heading may not correspond to its physical appearance and can change during game play.
 

===GetHeadlightState===
{{MethodHeader|public native bool GetHeadlightState(void)}}
;Parameters
*None
;Returned Value
*True if headlights are turned on, false otherwise.
;Syntax
bool lights = train.GetHeadlightState();
;Notes
*Only the frontmost locomotive will display headlighs.
 

===GetLastVisitedBuildable===
{{MethodHeader|public Buildable GetLastVisitedBuildable(void)}}
;Parameters
*None
;Returned Value
*The last [[Class Buildable|Buildable]] object visited by this train, null if there have been no such visits.
;Syntax
Buildable buildable = train.GetLastVisitedBuildable();
;Notes
 

===GetLastVisitedIndustry===
{{MethodHeader|public Industry GetLastVisitedIndustry(void)}}
;Parameters
*None
;Returned Value
*The last Industry object visited by this train, null if there have been no such visits.
;Syntax
Industry industry = train.GetLastVisitedIndustry();
;Notes
 

===GetLastVisitedTrack===
{{MethodHeader|public Track GetLastVisitedTrack(void)}}
;Parameters
*None
;Returned Value
*The last track segment visited by this train.
;Syntax
Track track = train.GetLastVisitedTrack();
;Notes
*Note that the returned value may be null. How is that possible?
 

===GetHighBeams===
{{MethodHeader|public bool GetHighBeams(void)}}
;Parameters
*None
;Returned Value
*True if the frontmost locomotive's high beams are on, false otherwise.
;Syntax
bool High_Lights = train.GetHighBeams();
;Notes
*See also [[Class Vehicle#GetHighBeams|Vehicle.GetHighBeams()]]
 

===GetMaximumCouplingStressVehicle===
{{MethodHeader|public native Vehicle GetMaximumCouplingStressVehicle(void)}}
;Parameters
*None
;Returned Value
*The Vehicle in this consist that is experiencing the greatest level of coupling stress.
;Syntax
Vehicle vehicle = GetMaximumCouplingStressVehicle();
;Notes
 

===GetPantographState===
{{MethodHeader|public native int GetPantographState(void)}}
;Parameters
*None
;Returned Value
*The state of the pantographs of the electric locomotives in this train.
;Syntax
int pantoState = train.GetPantographState();
;Notes
*The returned value will be in the range [0..3] where:
**0 = Both pantographs down.
**1 = Front pantograph up.
**2 = Rear pantograph up.
**3 = Both pantographs up.
 

===GetPhysicsModel===
{{MethodHeader|public native int GetPhysicsModel(void)}}
;Parameters
*None
;Returned Value
*The mode of control chosen by the player to drive the locomotive
;Syntax
int Mode = train.GetPhysicsModel();
;Notes
*The returned value will be :
**2 = CabinControl
**1 = DCCMode
 

===GetSmoothedVelocity===
{{MethodHeader|public native float GetSmoothedVelocity(void)}}
;Parameters
*None
;Returned Value
*Returns a smoothed velocity, intended for human consumption.
;Syntax
float speed = train.GetSmoothedVelocity();
;Notes
*If you require an accurate velocity readout for physics operations, use [[#GetVelocity|GetVelocity()]].
*''In practice, even when the train stops completely, it does not report an absolute zero.''
 

===GetSpeedLimit===
{{MethodHeader|public native float GetSpeedLimit(void)}}
;Parameters
*None
;Returned Value
*The current sign posted speed limit.
;Syntax
float permittedSpeed = train.GetSpeedLimit();
;Notes
*The speed limit is dependent on trackside signs placed in Surveyor as well as the direction of the train.
*A default value applies to track that isn't sign posted.
 

===GetTrackmarkDirection===
{{MethodHeader|public native int GetTrackmarkDirection(TrackMark mark)}}
;Parameters
*'''mark''' = A reference to the Trackmark to search for.
;Returned Value
* One of the [[#Found Results|Found Result]] values representing the location of the given track mark relative to this train.
;Syntax
int location = train.GetTrackmarkDirection(trackmark);
;Notes
 

===GetTrainBrakes===
{{MethodHeader|public native float GetTrainBrakes(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Train Brake Modes|Train Brake mode]] constants indicating the current state of this train's brakes.
;Syntax
float brakeState = train.GetTrainBrakes();
;Notes
 

===GetTrainDisplayName===
{{MethodHeader|public native string GetTrainDisplayName(void)}}
;Parameters
*None
;Returned Value
*A localised display name for this train.
;Syntax
string trainName = train.GetTrainDisplayName();
;Notes
*This will be a name Trainz has created for the consist such as "Consist 0" and will match the description shown in the Minimap view.
 

===GetTrainPriorityNumber===
{{MethodHeader|public native int GetTrainPriorityNumber(void)}}
;Parameters
*None
;Returned Value
*Train priority value in the range [1 .. 3]
;Syntax
int priority = train.GetTrainPriorityNumber();
;Notes
*See [[#SetTrainPriority|SetTrainPriority()]] for further details.
 

===GetTrainTimetable===
{{MethodHeader|public TrainTimetable GetTrainTimetable(void)}}
;Parameters
*None
;Returned Value
*The TrainTimetable that the train is currently using, null if there is none.
;Syntax
TrainTimetable timetable = train.GetTrainTimetable();
;Notes
 

===GetTrainVelocity===
{{MethodHeader|public native float GetTrainVelocity(void)}}
;Parameters
*None
;Returned Value
*The train's current velocity in metres per second.
;Syntax
float speed = train.GetTrainVelocity();
;Notes
* This function provides the instantaneous velocity for vehicles in this train, which is good for physics calculations but not good for human-readable display. If you want human-readable display, use [[#GetSmoothedVelocity|GetSmoothedVelocity()]] instead.
 

===GetVehicles===
{{MethodHeader|public native Vehicle[ ] GetVehicles(void)}}
;Parameters
*None
;Returned Value
*Returns an array consisting of all the vehicles making up this train.
;Syntax
Vehicle[] vehicles = train.GetVehicles();
;Notes
*GetVehicles[0] is always the front vehicle of the train relative to the train's current heading.
*The train's heading may not correspond to its physical appearance and can change during game play.
 

===GetVelocity===
{{MethodHeader|public native float GetVelocity(void)}}
;Parameters
*None
;Returned Value
*The train's current velocity.
;Syntax
float speed = train.GetVelocity();
;Notes
*Warning! The TS10 and TS12 Train.gs scripts advise this method is buggy and to use [[#GetSmoothedVelocity|GetSmoothedVelocity()]] or [[#GetTrainVelocity|GetTrainVelocity()]] instead.
*This function provides the instantaneous velocity for vehicles in this train, which is good for physics calculations but not good for human-readable display.
 

===HasReachedInnerJunctionRadius===
{{MethodHeader|public bool HasReachedJunctionInnerJunctionRadius(JunctionBase junction)}}
;Parameters
*'''junction''' = JunctionBase object to query.
;Returned Value
*True if this train is within the inner radius of the given junction, false otherwise.
;Syntax
bool arrived = train.HasReachedInnerJunctionRadius(junction10);
;Notes
 

===HasTrainTimetable===
{{MethodHeader|public bool HasTrainTimetable(void)}}
;Parameters
*None
;Returned Value
*True if this train has an attached TrainTimetable, false otherwise.
;Syntax
bool timed = train.HasTrainTimetable();
;Notes
 

===IsScheduleRunning===
{{MethodHeader|public bool IsScheduleRunning(void)}}
;Parameters
*None
;Returned Value
*True if this train is currently running to a Schedule, false otherwise.
;Syntax
bool scheduled = train.IsScheduleRunning();
;Notes
 

===IsScheduleWindowVisible===
{{MethodHeader|public bool IsScheduleWindowVisible(void)}}
;Parameters
*None
;Returned Value
*True if the schedule window for this train is currently open, false otherwise.
;Syntax
bool windowOpen = IsScheduleWindowVisible();
;Notes
 

===IsStillInJunction===
{{MethodHeader|public bool IsStillInJunction(JunctionBase junction)}}
;Parameters
*'''junction''' = JunctionBase object to query.
;Returned Value
*True if the train holds a Permit for the given junction, flse otherwise.
;Syntax
bool inJunction = train.IsStillInJunction(junction10);
;Notes
 

===IsStopped===
{{MethodHeader|public native bool IsStopped(void)}}
;Parameters
*None
;Returned Value
*True if the train is currently stationary, false if it is in motion.
;Syntax
bool moving=train.IsStopped();
;Notes
 

===IsTrainBusy===
{{MethodHeader|public bool IsTrainBusy(void)}}
;Parameters
*None
;Returned Value
*True if the train's 'busy' count is greater than zero, false otherwise.
;Syntax
bool busy = train.IsTrainBusy();
;Notes
*Using the [[#IncTrainBusy|IncTrainBusy()]] method, any piece of script code can tag a train being busy.
*The train can be untagged later by calling DecTrainBusy().
*This mechanism is mainly used by industries that are doing something with the train.
*A train can be tagged as being busy more than once by calling IncTrainBusy() multiple times so different industries can tag the train.
*Each time IncTrainBusy() is called, an internal busy count is incremented and if that busy count is greater than zero, the train is considered busy.
 

===IsViewDetailsVisible===
{{MethodHeader|public bool IsViewDetailsVisible(void)}}
;Parameters
*None
;Returned Value
*true if the ViewDetails window for this train is visible, false otherwise.
;Syntax
bool visible = train.IsViewDetailsVisible();
;Notes
 

===MapObjectIsInFront===
{{MethodHeader|public bool MapObjectIsInFront(MapObject obj, float range)}}
;Parameters
*'''obj''' = MapObject to search for.
*'''range''' = Maximum search distance.
;Returned Value
*True if the object is found within the specified distance and in front of the train, false otherwise.
;Syntax
bool isClose = train.MapObjectIsInFront(terminus,100.0);
;Notes
 

===ReleaseTrackPermits===
{{MethodHeader|public void ReleaseTrackPermits(Permit[ ] permitList)}}
;Parameters
*'''permitList''' = Permit array containing a list of permits to release.
;Returned Value
*None
;Syntax
train.ReleaseTrackPermits(permitList);
;Notes
*This method will release any permits from the ''permitList'' array that are currently held by this train.
*Any other permits in the array that are not held by this train will be ignored.
 

===RunSchedule===
{{MethodHeader|public thread void RunSchedule(Schedule schedule, bool loop, float delay)}}
;Parameters
*'''schedule''' = The Schedule that the train is to follow.
*'''loop''' = False to run the schedule once, True to repeat it continuously.
*'''delay''' = Time in seconds to wait before starting the schedule.
;Returned Value
*None
;Syntax
train.RunSchedule(schedule,false,10.0);
;Notes
*See [[Class Schedule|Schedule]] for information on how to build a schedule.
*Only one schedule may run on a train at a time and the user cannot control the train when it is running a schedule.
*This method is a thread, so the calling code does not need to wait for it to finish and return before executing other code.
 

===SetAdvisoryLimit===
{{MethodHeader|public native void SetAdvisoryLimit(float speed)}}
;Parameters
*'''speed''' = Speed limit to set in <del>KPH</del> metres/second.
;Returned Value
*None
;Syntax
train.SetAdvisoryLimit(60.0);
;Notes
*Sets an advisory speed limit for a script controlled train.
*Use zero in the speed parameter to clear any previously imposed limit.
*Does this really use KPH, most similar methods use MPS
*Experimental evidence confirms that it's in m/s not kph or mph
 

===SetAutopilotMode===
{{MethodHeader|public native void SetAutopilotMode(int mode)}}
;Parameters
*'''mode''' = One of the [[#Train Control Modes|Train Control Mode]] constants specifying the method by which this train is controlled.
;Returned Value
*None
;Syntax
train.SetAutopilotMode(Train.CONTROL_AUTOMANUAL);
;Notes
 

===SetAutopilotTarget===
{{MethodHeader|public native void SetAutopilotTarget(Buildable buildable, string trigger) public native void SetAutopilotTarget(Trackside trackside) public native void SetAutopilotTarget(Track track) public native void SetAutopilotTarget(JunctionBase junction)}}
;Parameters
*'''buildable''' = Buildable object to use as a destination.
*'''trigger''' = Attached trigger within the buildable, specified by name.
*'''trackside''' = Trackside object to use as a destination.
*'''track''' = Track segment to use as a destination.
*'''junction''' = JunctionBase object to use as a destination.
;Returned Value
*None
;Syntax
train.SetAutopilotTarget("Kings Cross Station","trigger1");
;Notes
*This method sets a destination for the autopilot to take this train to.
*Objects from respective child classes such as industries, signals and trackmarks may be specified.
 

===SetAutopilotTargetMinimumDistance===
{{MethodHeader|public native void SetAutopilotTargetMinimumDistance(float distance)}}
;Parameters
*'''distance''' = The minimum distance in metres, between the train and the autopilot target, to be reached before the train will start to slow down.
;Returned Value
*None
;Syntax
train SetAutopilotTargetMinimumDistance(100.0);
;Notes
 

===SetAutoPilotTargetMinimumSpeed===
{{MethodHeader|public native void SetAutopilotTargetMinimumSpeed(float speed)}}
;Parameters
*'''speed''' = Minimum speed, in metres per second, that the train should be travelling at when it reaches the Autopilot target.
;Returned Value
*None
;Syntax
train.SetAutoPilotTargetMinimumSpeed(20.0);
;Notes
*The documentation seems to mean that the train should be going at 20.0 OR MORE. Shouldn't it be MaximumSpeed???
 

===SetBail===
{{MethodHeader|public native void SetBail(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.SetBail();
;Notes
*Depresses the bail control for a short period.
 

===SetCouplingMask===
{{MethodHeader|public void SetCouplingMask(int mask)}}
;Parameters
*'''mask''' = A mask specifying which of the trains exposed couplers are allowed to couple.
;Returned Value
*None
;Syntax
train.SetCouplingMask(Vehicle.COUPLE_NONE); // prevents this train from coupling to another in Driver mode.
;Notes
*The mask can be built using the [[Class Vehicle#Coupler Flags|Coupler Flag]] constants defined in [[Class Vehicle]].
*This method will not prevent vehicles or trains from coupling in Surveyor, but takes effect in Driver mode.
 

===SetDCCThrottle===
{{MethodHeader|public native void SetDCCThrottle(float throttle)}}
;Parameters
*'''throttle''' = Float value in the range -1.0 .. 1.0 defining the throttle setting for the train when using DCC physics.
;Returned Value
*None
;Syntax
train.SetDCCThrottle(0.0); //sets the throttle to neutral.
;Notes
*Full speed ahead is 1.0
*Maximum in reverse is -1.0
*Neutral is 0.0
 

===SetDecouplingMask===
{{MethodHeader|public void SetDecouplingMask(int mask)}}
;Parameters
*'''mask''' = A mask specifying which of the couplers are allowed to couple, applies to all of the vehicles in the train.
;Returned Value
*None
;Syntax
train.SetDecouplingMask(Vehicle.COUPLE_FRONT|Vehicle.COUPLE_BACK); // prevents vehicles being uncoupled from the train in Driver mode.
;Notes
*The mask can be built using the [[Class Vehicle#Coupler Flags|Coupler Flag]] constants defined in [[Class Vehicle]].
*This method will not prevent vehicles or trains from being uncoupled in Surveyor, but takes effect in Driver mode.
 

===SetDynamicBrakeMode===
{{MethodHeader|public native void SetDynamicBrakeMode(int mode)}}
;Parameters
*One of the [[#Dynamic Brake States|Dynamic Brake State]] constants indicating the current state of this train's brakes.
;Returned Value
*None
;Syntax
train.SetDynamicBrakeMode(Train.DYNAMIC_BRAKE_TRACTION);
;Notes
 

===SetFloatingLimit===
{{MethodHeader|public native void SetFloatingLimit(float delta, bool enable)}}
;Parameters
*'''delta''' = Tolerance allowed from the posted limit in metres per second.
*'''enable''' = Use true to enable messages related to floating limits, false to disable.
;Returned Value
*None
;Syntax
train.SetFloatingLimit(5.0,true);
;Notes
*Sets the floating speed limit level above the sign posted limit.
*The floating limit is an amount of tolerance above the current speed limit.
*Messages for floating speed violations are not to be confused with regular speed limit messages.
*The floating limit is monitored by the Scenario.Monitor() thread, and may be used for point deduction when speeding. It should therefore be reserved for player trains.
 

===SetHandBrake===
{{MethodHeader|public void SetHandBrake(bool state)}}
;Parameters
*'''state''' = Use true to apply the handbrake to all vehicles in this train which are not Locomotives, false to release the handbrake.
;Returned Value
*None
;Syntax
train.SetHandBrake(true);
;Notes ''The use of this function did not reveal any effect on the physics of trains.''
 

===SetHeadlightState===
{{MethodHeader|public native void SetHeadlightState(bool lightsOn)}}
;Parameters
*'''lightsOn''' = True to turn the headlights on, false to turn them off.
;Returned Value
*None
;Syntax
train.SetHeadlightState(true);
;Notes
*This method affects only the headlights on the frontmost locomotive.
 

===SetHighBeams===
{{MethodHeader|public void SetHighBeams(bool value)}}
;Parameters
*'''value''' = True to turn on high beams, false to turn them off.
;Returned Value
*None
;Syntax
train.SetHighBeams(true);
;Notes
*See also [[Class Vehicle#SetHighBeams|Vehicle.SetHighColor()]]
 

===SetLastVisitedBuildable===
{{MethodHeader|public void SetLastVisitedBuildable(Buildable buildable)}}
;Parameters
*'''buildable''' = Sets the last visited buildable to the given object.
;Returned Value
*None
;Syntax
train.SetLastVisitedBuildable(KingsCrossStation);
;Notes
 

===SetManualThrottle===
{{MethodHeader|public native void SetManualThrottle(int notch)}}
;Parameters
*'''notch''' = Value in the range 0 .. 8 to set the throttle.
;Returned Value
*None
;Syntax
train.SetManualThrottle(5);
;Notes
 

===SetPantogaphState===
{{MethodHeader|public native void SetPantographState(int state)}}
;Parameters
*'''state''' = Value in the range 0 .. 3 to set the pantographs if this train has them.
;Returned Value
*None
;Syntax
train.SetPantographState(3);
;Notes
*Use one of these values for ''state'':
**0 = Both pantographs down.
**1 = Front pantograph up.
**2 = Rear pantograph up.
**3 = Both pantographs up.
 

===SetReverser===
{{MethodHeader|public native void SetReverser(int mode)}}
;Parameters
*'''mode''' = One of the [[#Reverser Traction Modes|Reverser Traction Mode]] constants defining the required state of the train's reverser lever.
;Returned Value
*None
;Syntax
train.SetReverser(Train.TRACTION_REVERSE);
;Notes
 

===SetTrainBrakes===
{{MethodHeader|public native void SetTrainBrakes(float mode)}}
;Parameters
*'''mode''' = One of the [[#Train Brake States|Train Brake State]] constants defining the required state of the train's brakes.
;Returned Value
*None
;Syntax
train.SetTrainBrakes(Train.TRAIN_BRAKE_EMERGENCY);
;Notes
 

===SetTrainPriorityNumber===
{{MethodHeader|public native void SetTrainPriority Number(int priority)}}
;Parameters
*'''priority''' = Priority value in the range 1 .. 3.
;Returned Value
*None
;Syntax
train.SetTrainPriorityNumber(2);
;Notes
*All trains and track sections can be assigned a priority value in the range of [1 - 3] with the default value being 2.
*The priority value is not a numerical scale of precedence, but a value for the AI driver to attempt to match.
*This means the driver will ''prefer'' track sections that have a priority equal to that of the train.
*Changing the priority of the train only takes affect when the driver restarts a new schedule.
 

===SetTrainTimetable===
{{MethodHeader|public void SetTrainTimetable(TrainTimetable timetable)}}
;Parameters
*'''timetable''' = Assigns the specified timetable to this train.
;Returned Value
*None
;Syntax
train.SetTrainTimetable(timetable);
;Notes
*This train must not already have a TrainTimetable assigned.
*To ensure that this proviso is met, use [[#ClearTrainTimetabel|ClearTrainTimetable()]] prior to calling this method.
*It is the responsibility of the caller to post a "TrainTimetable","Touch" message after calling this function.
 

===SetVelocity===
{{MethodHeader|public native void SetVelocity(float velocity)}}
;Parameters
*'''velocity''' = Velocity to apply to the train, in metres per second.
;Returned Value
*None
;Syntax
train.SetVelocity(0.0); // stops the train, subject to braking performance.
;Notes
 

===ShowInConsistMenu===
{{MethodHeader|public native void ShowInConsistMenu(bool show)}}
;Parameters
*'''show''' = True to make this train visible to the in-game consist menu, false to hide it.
;Returned Value
*None
;Syntax
train.ShowInConsistMenu(false);
;Notes
 

===SoundHorn===
{{MethodHeader|public native void SoundHorn(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.SoundHorn();
;Notes
*Sounds the horn or whictle for all locomotives in this train.
 

===StopSchedule===
{{MethodHeader|public void StopSchedule(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.StopSchedule();
;Notes
*This method stops the Schedule this train is currently running (if any).
 

===StopScheduleAndWait===
{{MethodHeader|public void StopSchedule(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.StopSchedule();
;Notes
*This method stops the Schedule this train is currently running (if any) and waits until the train's schedule actually stops before returning.
*If the train is not running a schedule, the method returns after broadcasting a "Schedule","Touch" message, in case someone is listening for schedule messages.
 

===StopTrainGently===
{{MethodHeader|public native void StopTrainGently(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.StopTrainGently();
;Notes
*Brings the train to a halt over a short time period.
 

===TakePermitOnTrack===
{{MethodHeader|public Permit[ ] TakePermitOnTrack(bool direction)}}
;Parameters
*'''direction''' = Direction relative to the train in which to take out permits.
;Returned Value
*An array including any permits taken which have not yet been granted to this train. Some of these permits may not yet have been granted.
;Syntax
Permit[] permits = train.TakePermitOnTrack(true);
;Notes
*Gets permits on the current track in the given direction.
 

===TestTrackPermit===
{{MethodHeader|public native bool TestTrackPermit(Permit permit, bool innerOnly)}}
;Parameters
*'''permit''' = An existing Permit object.
*'''innerOnly''' = If true the method will test only the inner radius, if false the default radius of 150 metres will be used.
;Returned Value
*True if this train is within the track controlled by ''permit'', false otherwise.
;Syntax
bool ownPermit = train.TestTrackPermit(permit1,false);
;Notes
*The method generates an exception if the ''permit'' parameter does not refer to a track.
 

===ToggleScheduleWindow===
{{MethodHeader|public void ToggleScheduleWindow(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.ToggleScheduleWindow();
;Notes
*If the schedule window is already open/visible, this method will destroy it.
*Otherwise if the view details window is not visible, UpdateScheduleWindow() is called to create it for display.
 

===ToggleViewDetailsWindow===
{{MethodHeader|public void ToggleViewDetailsWindow(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.ToggleViewDetailsWindow();
;Notes
*If the ViewDetails window is already open/visible, this method will destroy it.
*Otherwise if the view details window is not visible, ViewDetails() is called to create it for display.
 

===TrackSearch===
{{MethodHeader|public native MapObject[ ] TrackSearch(bool direction, float distance)}}
;Parameters
*'''direction''' = Direction to search relative to the train's heading, true for forwards, false for backwards.
*'''distance''' = Maximum search distance in metres.
;Returned Value
*An array of objects found along the track in the defined search direction, the array might be empty.
;Syntax
MapObject[] objects = train.TrackSearch(true,5000.0) // searches 5km forwards along the track.
;Notes
*Gets all of the Trackside and SceneryWithTrack objects on a length of track that is either in front of or behind this train.
*Descendants of these classes are also returned.
 

===TracksideIsInFront===
{{MethodHeader|public bool TracksideIsInFront(Trackside obj, float range)}}
;Parameters
*'''obj''' = Trackside object to search for.
*'''range''' = Mximum search distance.
;Returned Value
*True if the object is logically forward of this train, false otherwise.
;Syntax
bool found = train.TracksideIsInFront(signal1,500.0);
;Notes
 

===Turnaround===
{{MethodHeader|public native void Turnaround(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.Turnaround();
;Notes
*Reverses the logical direction of the train, ie changes its heading.
*The physical direction of the vehicles is not altered but the throttle direction is reversed.
*If the camera is focused on the train in tracking view when this method is called the camera's direction of view (relative to the map) will alter through 180 degrees.
 

===UpdateScheduleWindow===
{{MethodHeader|public void UpdateScheduleWindow(string vehicleName)}}
;Parameters
*'''vehicleName''' = Name of vehicle within the train.
;Returned Value
*None
;Syntax
train.UpdateScheduleWindow("brake2");
;Notes
*Updates the schedule window from the given vehicle.
 

===UpdateViewDetails===
{{MethodHeader|public void UpdateViewDetails(Vehicle vehicle)}}
;Parameters
*'''vehicle''' = Reference to a vehicle within the train.
;Returned Value
*None
;Syntax
train.UpdateViewDetails(vehicle);
;Notes
*Called by Vehicle.UpdateViewDetails() when a vehicle's load has changed so that the train's detail window can be amended.
 

===UpdateViewDetailsLocomotive===
{{MethodHeader|public void UpdateViewDetailsLocomotive(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.UpdateViewDetailsLocomotive(vehicle);
;Notes
*Called by Locomotive.UpdateViewDetails() when any of the Locomotive's operating parameters have changed so that the train's detail window can be amended.
 

===ViewDetails===
{{MethodHeader|public void ViewDetails(Vehicle vehicle)}}
;Parameters
*'''vehicle''' = Reference to a vehicle within the train.
;Returned Value
*None
;Syntax
train.ViewDetails(vehicle);
;Notes
*This method is called by Vehicle.ViewDetails() when the user has requested to view the details of the consist.
*It will create a Browser window listing information about the train including who the driver character is and the loads of all vehicles.
 

===WasRunScheduleSuccessful===
{{MethodHeader|public bool WasRunScheduleSuccessful(void)}}
;Parameters
*None
;Returned Value
*True if the most recently run schedule was successfully, false otherwise.
;Syntax
train.WasRunScheduleSuccessful();
;Notes
 

==Code Examples==
 

==Related Methods==
[[Class TrainUtil#AreInTrain|TrainUtil.AreInTrain()]] 
[[Class TrainUtil#CreateTrainFromSoup|TrainUtil.CreateTrainFromSoup()]] 
[[Class TrainUtil#IsInTrain|TrainUtil.IsInTrain()]] 
[[Class World#CreateTrain|World.CreateTrain()]] 
[[Class World#DeleteTrain|World.DeleteTrain()]] 
[[Class World#GetTrainList|World.GetTrainList()]] 
 

==Categories==
[[Category:Script Class]]

Class Cabin

2020-12-28T13:47:05Z

Danny252: Change link to library reference, not language reference