TrainzOnline - User contributions [en]

Class PropertyObject

2021-04-05T09:22:03Z

Marekp9: /* GetDescriptionHTML */ Added link to MiniBrowser with the list of supported HTML elements

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

This class provides an interface that allows an object to implement properties that can be saved or loaded to a session and edited by the user through a browser window in Surveyor. To enable this for an asset, it must inherit from PropertyObject (or from a derived child class such as [[Class ScenarioBehavior|ScenarioBehavior]] or [[Class MeshObject|MeshObject]]).

PropertyObject operates by way of a series of predefined callback methods which are designed to be overridden by the script writer to allow Trainz to access an object's properties. Properties are referred to in the class methods by their propertyID. Trainz determines this by reference to links in the object browser in the form ''live://property/propertyID''.

When Trainz is saving a session, it asks each object to save its respective state into a [[Class Soup|Soup]] database. Trainz doesn't know what your object needs to save, but it does know that it can request an object's state via callbacks. Trainz relies on the script programmer to give careful thought to what data is needed to save and restore an objects state.

Depending on circumstances, not all callback methods have to be implemented. For example, you don't need to override [[#GetPropertyElementList|GetPropertyElementList()]] if there are no list-selection properties.

==Callback Sequences==
The precise sequence of callback method calls will vary with the content of the browser and the user's input but the following gives a general idea:
*When the Property Browser is opened Trainz calls:
** [[#GetProperties|GetProperties()]] to read the current session data.
** [[#GetDescriptionHTML|GetDescriptionHTML()]] to read the HTML code for the browser configuration window.
*When the user clicks on a URL, the propertyID is extracted from the link and these calls are made:
** [[#GetPropertyType|GetPropertyType()]] to establish the 'type' of the property is to be edited.
**For "link" properties Trainz will call:
*** [[#LinkPropertyValue|LinkPropertyValue()]], which should respond and set the desired value
**For "string", "int" and "float" properties:
*** [[#GetPropertyValue|GetPropertyValue()]] to establish the property's current value.
*** [[#GetPropertyName|GetPropertyName()]] and/or [[#GetPropertyDescription|GetPropertyDescription()]] to obtain display info for the UI.
*** Trainz then provides a pop-up edit box with a caption and current value filled in and waits for the user to edit the property, if desired.
**For "list" properties:
*** [[#GetPropertyName|GetPropertyName()]] and/or [[#GetPropertyDescription|GetPropertyDescription()]] to obtain display info for the UI.
*** [[#GetPropertyElementList|GetPropertyElementList()]] to obtain the list options to display to the player.
*** Trainz then provides a pop-up edit box with a caption and the list of options and waits for the user to edit the property, if desired.
**For "map-object" and "asset-list" properties:
*** [[#GetPropertyName|GetPropertyName()]] and/or [[#GetPropertyDescription|GetPropertyDescription()]] to obtain display info for the UI.
*** Trainz displays a filterable list dialog to the player, showing a spinner while the search runs.
*** When a search completes, Trainz calls [[#FilterPropertyElementList|FilterPropertyElementList()]], to allow the script to add/remove any custom entries.
*Once the user has carried out any edits:
** The appropriate variant of [[#SetPropertyValue|SetPropertyValue()]] is called to update the value of the property.
** [[#GetDescriptionHTML|GetDescriptionHTML()]] is called again to refresh the contents of the Browser window for any new configuration.
*When all edits are complete:
**If the user confirms their changes and closes the dialog:
*** [[#SetProperties|SetProperties()]] is called with the modified Soup to update the session database.
**If the user cancels the changes:
*** [[#SetProperties|SetProperties()]] is called with the original unaltered Soup to restore the script to it's original pre-edit state.
 

Throughout the above sequences Trainz is only concerned with the loading and saving of properties. Wherever a change in a property requires an update to the appearance of the object or to the contents of its variables it is the responsibility of the script writer to implement these changes at the appropriate time. In general changes should be implemented in [[#SetProperties|SetProperties()]] since this will help to ensure that changes can be reversed if they are cancelled or when the game's ''UNDO'' command is invoked.

==Save/Load==
Scripted objects do not have their state automatically saved and restored. It is the responsibility of the individual scripts to save and restored any necessary state across a Surveyor save session/load session, or across a Driver save game/load game. This is implemented using the PropertyObject [[#GetProperties|GetProperties()]] and [[#SetProperties|SetProperties()]] functions. When saving, Trainz will ensure that GetProperties() has been called for every PropertyObject that is being saved. The [[Soup]] returned by this function is stored along with any native state for the object in question. When reloading, Trainz will first create the object and load the native state, then will call the SetProperties() function with the saved Soup which instructs the script to restore its state.

==GetDescriptionHTML==
{{MethodHeader|public string GetDescriptionHTML(void)}}
;Parameters
''None''

;Return Value;
HTML formatted string to be loaded into the Property Browser.

;Example Implementation
public string GetDescriptionHTML(void)
{
StringTable strTable = GetAsset().GetStringTable();

HTMLBuffer buffer = HTMLBufferStatic.Construct();
buffer.Print("<html><body>");

buffer.Escape(strTable.GetString("property_name_forename"));
buffer.Print(": <a href=live://property/forename>");
buffer.Escape(m_foreName);
<nowiki>buffer.Print("</a> ");</nowiki>
buffer.Escape(strTable.GetString("property_name_surname"));
buffer.Print(": <a href=live://property/forename>");
buffer.Escape(m_surName);
<nowiki>buffer.Print("</a> ");</nowiki>
buffer.Print("</body></html>");

return buffer.AsString();
}

;Description
This method is called by Trainz to retrieve HTML which a player can use to configure the objects properties. Any embedded properties should use the ''live://property/propertyID'' format, all player readable strings should be sourced from the asset string-table, and all player configurable values should be appropriately escaped to avoid HTML corruption.
 
The Trainz uses its Mini Browser to display the HTML. See the [[MiniBrowser]] page to find supported HTML elements.

==GetProperties==
{{MethodHeader|public Soup GetProperties(void)}}
;Parameters
''None''

;Return Value
Soup object containing data appropriate to represent the configured state of the object.

;Example Implementation
public Soup GetProperties(void)
{
Soup soup = inherited();
soup.SetNamedTag("forename", m_foreName);
soup.SetNamedTag("surname", m_surName);
return soup;
}

;Description
This method is used to save current properties into the session database. Care must be taken to ensure it writes data in the same tag format that [[#SetProperties|SetProperties()]] is expecting. When overriding this method to handle your own properties, always call through to the overridden parent by using inherited().
 

==SetProperties==
{{MethodHeader|public void SetProperties(Soup soup)}}
;Parameters
*'''soup''' = reference to ''soup'' to be saved to session.

;Returned Value
None

;Example Implementation
public void SetProperties(Soup soup)
{
inherited(soup);
m_foreName = soup.GetNamedTag("forename");
m_surName = soup.GetNamedTag("surname");
}

;Description
Restores object state with a Soup object returned from a previous call to GetProperties(). When overriding this method to handle your own properties, always call through to the overridden parent by using inherited(soup). This ensures that any data required by the parent class is appropriately set.
 

==GetPropertyType==
{{MethodHeader|string GetPropertyType(string propertyID)}}
;Parameters
*'''propertyID''' = Name of property.

;Return Value
The type of the current property.

;Example Implementation
string GetPropertyType(string propertyID)
{
if (propertyID == "forename" or propertyID == "surname")
return "string";

return inherited(propertyID);
}

;Description
This method is used by Trainz to determine the type of the named property. The supported types and their parameters are listed in the table below.
{{TableHeader|width=50%|margin=15px}}
|Value type||Parameters||Description
|-
|string||minimum-length,maximum-length||A string value, with optional minimum and maximum lengths. e.g. "string,0,200".
|-
|int||minimum-value,maximum-value,step-value||An integer value with optional minimum, maximum and 'step' value. e.g. "int,0,100,5".
|-
|float||minimum-value,maximum-value,step-value||An floating point value with optional minimum, maximum and 'step' value. e.g. "float,0,10,0.5".
|-
|list||sorted-bool||An list, with an optional sorting flag (default off). e.g. "list,1" to sort, "list,0" for unsorted.
|-
|map-object||category-list||A list of map objects in the route which match a specific non-optional category list. e.g. "map-object,IND" for an industry list.
|-
|asset-list||category-list||A list of locally installed, compatible and available assets which match a specific non-optional category list. e.g. "asset-list,DR" for a list of installed Driver Character assets.
|-
|link||||A link type. This would usually respond and set some specific value, or perhaps toggle a bool.
|}

==GetPropertyName==
{{MethodHeader|string GetPropertyName(string propertyID)}}
;Parameters
*'''propertyID''' = Name of property.

;Return Value
The name of the current property.

;Example Implementation
string GetPropertyName(string propertyID)
{
if (propertyID == "forename")
return GetAsset().GetStringTable().GetString("property_name_forename");
if (propertyID == "surname")
return GetAsset().GetStringTable().GetString("property_name_surname");

return inherited(propertyID);
}

==GetPropertyDescription==
{{MethodHeader|string GetPropertyDescription(string propertyID)}}
;Parameters
*'''propertyID''' = Name of property.

;Return Value
Description to be used as a caption for the edit box presented to the user for a specific property.

;Example Implementation
string GetPropertyDescription(string propertyID)
{
if (propertyID == "forename")
return GetAsset().GetStringTable().GetString("property_description_forename");
if (propertyID == "surname")
return GetAsset().GetStringTable().GetString("property_description_surname");

return inherited(propertyID);
}

==GetPropertyValue==
{{MethodHeader|public string GetPropertyValue(string propertyID)}}
;Parameters
*'''propertyID''' = Name of property.

;Returned Value
A string representation of the value of the current property.

;Example Implementation
public string GetPropertyValue(string propertyID)
{
if (propertyID == "forename")
return m_foreName;
if (propertyID == "surname")
return m_foreName;

return inherited(propertyID);
}

;Description
Returns a string representation of the current value of the selected property, if possible. Where it is not possible to format a value into a string (such as with map-object and asset-list types) then any cached localised name may be returned, and native will attempt to find that object in any displayed list, etc.
 

==LinkPropertyValue==
{{MethodHeader|void LinkPropertyValue(string propertyID)}}
;Parameters
*'''propertyID''' = Name of property.

;Returned Value
''None''

;Example Implementation
void LinkPropertyValue(string propertyID)
{
if (propertyID == "doors")
{
m_doorsOpen = !m_doorsOpen;
SetMeshAnimationState("doors", m_doorsOpen);
return;
}

inherited(propertyID);
}

;Description
Called when the player clicks on a "link" property type. Link properties are most frequently used to toggle boolean values and selecting "radio" buttons.
 

==GetPropertyElementList==
{{MethodHeader|public string[ ] GetPropertyElementList(string propertyID)}}
;Parameters
*'''propertyID''' = Name of property.

;Returned Value
A string array to for the player to select a value from.

;Example Implementation
public string[] GetPropertyElementList(string propertyID)
{
if (propertyID == "mode")
{
StringTable strTable = GetAsset().GetStringTable();

string[] result = new string[10];
int i;
for (i = 1; i < 10; ++i)
result[i] = strTable.GetString("property_list_mode_" + i);

return result;
}

return inherited(propertyID);
}

;Description
Retrieves a list possible values for a named property. Used for the "list" type. The returned list should support localisation by using string-table entries where appropriate.
 

==FilterPropertyElementList==
{{MethodHeader|public bool FilterPropertyElementList(string propertyID, GSObject[] listObjects, string[] listNames)}}
;Parameters
*'''propertyID''' = Name of property.
*'''listObjects''' = The list of objects about to be displayed.
*'''listNames''' = The names of the objects about to be displayed.

;Returned Value
Whether the filter function has altered the list at all.

;Example Implementation
public bool FilterPropertyElementList(string propertyID, GSObject[] listObjects, string[] listNames)
{
if (propertyID == "object-list")
{
bool bDidChangeAnything = false;
// Remove any already added objects from the list
int i;
for (i = 0; i < listObjects.size(); )
{
if (IsAlreadyInList(cast<GameObject>(listObjects[i])))
{
listObjects[i,i+1] = null;
listNames[i,i+1] = null;
bDidChangeAnything = true;
}
else
{
++i;
}
}

return bDidChangeAnything;
}

return inherited(propertyID, listObjects, listNames);
}

;Description
Used for "map-object" and "asset-list" types to allow the list to be filtered before display. This gives the script an opportunity to cull any inappropriate values (such as those already added) and/or add any custom entries (such as a "none" selection).

==SetPropertyValue==
{{MethodHeader|
void SetPropertyValue(string propertyID, string value) 
void SetPropertyValue(string propertyID, int value) 
void SetPropertyValue(string propertyID, float value) 
void SetPropertyValue(string propertyID, string value, int index) 
void SetPropertyValue(string propertyID, GSObject value, string readableName)
}}
;Parameters
*'''propertyID''' = Name of property.
*'''value''' = string, int, float or object value to assign to the property.
*'''index''' = list types only, specifies the index of the selected item in the list.
*'''readableName''' = map-object and asset-list types only, specifies the localised name of the object/asset selected.

;Return Value
''None''

;Example Implementations
void SetPropertyValue(string propertyID, string value)
{
if (propertyID == "forename")
{
m_foreName = value;
return;
}
if (propertyID == "surname")
{
m_surName = value;
return;
}

inherited(propertyID, value);
}

void SetPropertyValue(string propertyID, GSObject value, string readableName)
{
if (propertyID == "junction")
{
m_junctionID = cast<GameObjectID>(value);
m_junctionName = readableName;
return;
}
if (propertyID == "sound-asset")
{
m_sound = cast<Asset>(value);
m_soundName = readableName;
return;
}

inherited(propertyID, value, readableName);
}

;Description
Sets a new value for the named property. The variant called depends on the property type, as returned by GetPropertyType().
 

==PropertyBrowserRefresh==
{{MethodHeader|public void PropertyBrowserRefresh(Browser browser)}}
;Parameters
*'''browser''' = Reference to ''browser'' object displaying properties.

;Returned Value
''None''

;Description
A callback method which the script writer can override to specify tasks to be carried out whenever the Browser is refreshed.
 

==SetPropertyHandler==
{{MethodHeader|public void SetPropertyHandler(HTMLPropertyHandler handler)}}
;Parameters
*'''handler''' = Handler to assign to this property object.

;Returned Value
''None''

;Description
Called to add a sub-handler property object to this object. The added HTMLPropertyHandler can then implement property lists, etc. This is useful for organising property values into groups. Several pre-defined HTMLPropertyHandler classes also already exist in the core Trainz scripts, which script programmers can use to save time and avoid code duplication.
 

==GetPropertyHandler==
{{MethodHeader|public HTMLPropertyHandler GetPropertyHandler(void)}}
;Parameters
''None''

;Returned Value
A reference to the current property handler for this object, or null if none has been set.
 

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

Class GameObject

2021-03-27T12:33:37Z

Marekp9: Added link to list of known messages

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

*GameObject is the base class for any object that requires messaging and threading support.
*GameObjects are placed in the game's object table, known as the Router.
*You cannot create a GameObject using ''new()'' from a script, all game objects are created by the game.
*Each game object has a unique ID (see [[#GetId|GetId()]]) and many also have a name.
*GameObject instances are often referred to as a ''node'' because they represent a message node in the Router.

==AddHandler==
{{MethodHeader|public native void AddHandler(GameObject target, string major, string minor, string Handler)}}
;Parameters
*'''target''' = Object to add the message handler to. This is usually ''me'' but can be any ''GameObject''.
*'''major''' = [[List of Standard Messages|Message ''major'']] to listen for.
*'''minor''' = [[List of Standard Messages|Message ''minor'']] to listen for. If this paremeter is null or an empty string then all messages that match the ''major'' parameter will be sent to the handler.
*'''Handler''' Name of the message handler method to call. This must have a prototype in of the form ''void MessageHandler(Message msg)''
;Returned Value
*None
;Syntax
AddHandler(me,"Object","Enter","ObjectHandler");
AddHandler(me,"Object","","ObjectHandler");
;Notes
*Adds a message handler to the current class such that it will be called whenever the target GameObject receives a matching message.
*Message handlers called by this means are not threaded and will be executed immediately.
 

==ClearMessages==
{{MethodHeader|public native void ClearMessages(string major, string minor)}}
;Parameters
*'''major''' = [[List of Standard Messages|Message ''major'']] to listen for.
*'''minor''' = [[List of Standard Messages|Message ''minor'']] to listen for.
;Returned Value
*None
;Syntax
ClearMessages("Object","Enter");
;Notes
*Clears any outstanding messages of the specified major and minor types that have been sent via calls to [[#PostMessage|PostMessage()]] and have not yet been processed.
 

==Exception==
{{MethodHeader|public native void Exception(string reason)}}
;Parameters
*'''reason''' = Explanatory text to add to the message box.
;Returned Value
*None
;Syntax
Exception("Fatal Error");
;Notes
*Raises an Exception on the current thread and prints out the contents of the ''reason'' parameter followed by a stack dump.
 

==GetId==
{{MethodHeader|public native int GetId(void)}}
;Parameters
*None
;Returned Value
*The GameObject ID, an integer value which the Router uses to identify the current object.
;Syntax
int ID = GetId();
;Notes
*The ID is unique to the current session.
 

==GetName==
{{MethodHeader|public native string GetName(void)'''}}
;Parameters
*None
;Returned Value
*The name of the current object if it has one, an empty string otherwise.
;Syntax
string MyName = GetName();
;Notes
*The name returned is the text string that is shown at the top of the property object browser for the object concerned.
*If the name has been assigned by the game this will be the asset's username followed by a serial number.
*The string returned by this method is not guaranteed to be unique although TRS will issue prompts requesting confirmation in situations where duplication of names is about to occur.
*The name persists from session to session.
 

==PostMessage==
{{MethodHeader|public native void PostMessage(GameObject dest, string major, string minor, float seconds)}}
;Parameters
*'''dest''' = Destination object for the message. If this is null the message will be broadcast.
*'''major''' = [[List of Standard Messages|Message ''major'']] to be sent.
*'''minor''' = [[List of Standard Messages|Message ''minor'']] to be sent.
*'''seconds''' = Delay in seconds before the message is posted. If this is zero the message will be posted immediately.
;Returned Value
*None
;Syntax
PostMessage(me,"Timer","Tick",10.0);
PostMessage(null,"Browser-URL","live://next",0.0);
;Notes
*Messages sent via this method are processed by the Router in the next game update after they become due.
 

==SendMessage==
{{MethodHeader|public native void SendMessage(GameObject dest, string major, string minor)}}
;Parameters
*'''dest''' = Destination object for the message. If this is null the message will be broadcast.
*'''major''' = [[List of Standard Messages|Message ''major'']] to be sent.
*'''minor''' = [[List of Standard Messages|Message ''minor'']] to be sent.
;Returned Value
*None
;Syntax
SendMessage(train,"Object","Enter");
;Notes
*Sends a message to the destination object for immediate processing.
 

==Sleep==
{{MethodHeader|public native void Sleep(float seconds)}}
;Parameters
*'''seconds''' = Time to wait in seconds.
;Returned Value
*None
;Syntax
Sleep(10.0);
;Notes
*Causes the current thread to pause for the specified period of time.
*Warning! Sleep(World.PlaySound(...)) should no longer be used, as PlaySound does not return the file duration anymore!
 

==Sniff==
{{MethodHeader|public native void Sniff(GameObject target, string major, string minor, bool state)}}
;Parameters
*'''target''' = Game Object to which the handler will be attached.
*'''major''' = [[List of Standard Messages|Message ''major'']] to listen for.
*'''minor''' = [[List of Standard Messages|Message ''minor'']] to listen for. If this parameter is null or an empty string then all messages matching the ''major'' parameter will be processed.
*'''state''' = Boolean flag to set whether or not the handler is currently active.
;Returned Value
*None
;Syntax
Sniff(train,"Object","Enter",true);
;Notes
*Attaches a message handler to another object allowing the current script to listen in on the specified messages.
*Messages of the specified type received by the target object will be copied to the current script.
*The current script will usually need a separate handler to process these messages and will normally need to check the identity of the message source.
 

==Code Examples==
Script calls made during the Init() method of an object can never be certain that other objects within the map have already been initialised. In cases where initialisation depends on the existence of other objects [[#PostMessage|PostMessage()]] can be used to delay part or all of the startup. Messages sent in this way are never processed until the next game update and this does not occur until all objects have been initialised.
public void Init(void)
{
inherited();
SetupTasks();
AddHandler(me,"Setup","","SetupHandler");
PostMessage(me,"Setup","",0.0);
}

void SetupHandler(Message msg)
{
if (msg.src == me)
{
MoreSetupTasks();
}
}
 

==Related Methods==
[[Class Router#GetGameObject|Router.GetGameObject()]] 
[[Class Router#PostMessage|Router.PostMessage()]] 
[[TrainzScript Message Reference]] 

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

Class GameObject

2021-03-27T12:30:53Z

Marekp9: /* AddHandler */ Added link to list of known messages

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

*GameObject is the base class for any object that requires messaging and threading support.
*GameObjects are placed in the game's object table, known as the Router.
*You cannot create a GameObject using ''new()'' from a script, all game objects are created by the game.
*Each game object has a unique ID (see [[#GetId|GetId()]]) and many also have a name.
*GameObject instances are often referred to as a ''node'' because they represent a message node in the Router.

==AddHandler==
{{MethodHeader|public native void AddHandler(GameObject target, string major, string minor, string Handler)}}
;Parameters
*'''target''' = Object to add the message handler to. This is usually ''me'' but can be any ''GameObject''.
*'''major''' = [[List of Standard Messages|Message ''major'']] to listen for.
*'''minor''' = [[List of Standard Messages|Message ''minor'']] to listen for. If this paremeter is null or an empty string then all messages that match the ''major'' parameter will be sent to the handler.
*'''Handler''' Name of the message handler method to call. This must have a prototype in of the form ''void MessageHandler(Message msg)''
;Returned Value
*None
;Syntax
AddHandler(me,"Object","Enter","ObjectHandler");
AddHandler(me,"Object","","ObjectHandler");
;Notes
*Adds a message handler to the current class such that it will be called whenever the target GameObject receives a matching message.
*Message handlers called by this means are not threaded and will be executed immediately.
 

==ClearMessages==
{{MethodHeader|public native void ClearMessages(string major, string minor)}}
;Parameters
*'''major''' = Message ''major'' to listen for.
*'''minor''' = Message ''minor'' to listen for.
;Returned Value
*None
;Syntax
ClearMessages("Object","Enter");
;Notes
*Clears any outstanding messages of the specified major and minor types that have been sent via calls to [[#PostMessage|PostMessage()]] and have not yet been processed.
 

==Exception==
{{MethodHeader|public native void Exception(string reason)}}
;Parameters
*'''reason''' = Explanatory text to add to the message box.
;Returned Value
*None
;Syntax
Exception("Fatal Error");
;Notes
*Raises an Exception on the current thread and prints out the contents of the ''reason'' parameter followed by a stack dump.
 

==GetId==
{{MethodHeader|public native int GetId(void)}}
;Parameters
*None
;Returned Value
*The GameObject ID, an integer value which the Router uses to identify the current object.
;Syntax
int ID = GetId();
;Notes
*The ID is unique to the current session.
 

==GetName==
{{MethodHeader|public native string GetName(void)'''}}
;Parameters
*None
;Returned Value
*The name of the current object if it has one, an empty string otherwise.
;Syntax
string MyName = GetName();
;Notes
*The name returned is the text string that is shown at the top of the property object browser for the object concerned.
*If the name has been assigned by the game this will be the asset's username followed by a serial number.
*The string returned by this method is not guaranteed to be unique although TRS will issue prompts requesting confirmation in situations where duplication of names is about to occur.
*The name persists from session to session.
 

==PostMessage==
{{MethodHeader|public native void PostMessage(GameObject dest, string major, string minor, float seconds)}}
;Parameters
*'''dest''' = Destination object for the message. If this is null the message will be broadcast.
*'''major''' = Message ''major'' to be sent.
*'''minor''' = Message ''minor'' to be sent.
*'''seconds''' = Delay in seconds before the message is posted. If this is zero the message will be posted immediately.
;Returned Value
*None
;Syntax
PostMessage(me,"Timer","Tick",10.0);
PostMessage(null,"Browser-URL","live://next",0.0);
;Notes
*Messages sent via this method are processed by the Router in the next game update after they become due.
 

==SendMessage==
{{MethodHeader|public native void SendMessage(GameObject dest, string major, string minor)}}
;Parameters
*'''dest''' = Destination object for the message. If this is null the message will be broadcast.
*'''major''' = Message ''major'' to be sent.
*'''minor''' = Message ''minor'' to be sent.
;Returned Value
*None
;Syntax
SendMessage(train,"Object","Enter");
;Notes
*Sends a message to the destination object for immediate processing.
 

==Sleep==
{{MethodHeader|public native void Sleep(float seconds)}}
;Parameters
*'''seconds''' = Time to wait in seconds.
;Returned Value
*None
;Syntax
Sleep(10.0);
;Notes
*Causes the current thread to pause for the specified period of time.
*Warning! Sleep(World.PlaySound(...)) should no longer be used, as PlaySound does not return the file duration anymore!
 

==Sniff==
{{MethodHeader|public native void Sniff(GameObject target, string major, string minor, bool state)}}
;Parameters
*'''target''' = Game Object to which the handler will be attached.
*'''major''' = Message ''major'' to listen for.
*'''minor''' = Message ''minor'' to listen for. If this parameter is null or an empty string then all messages matching the ''major'' parameter will be processed.
*'''state''' = Boolean flag to set whether or not the handler is currently active.
;Returned Value
*None
;Syntax
Sniff(train,"Object","Enter",true);
;Notes
*Attaches a message handler to another object allowing the current script to listen in on the specified messages.
*Messages of the specified type received by the target object will be copied to the current script.
*The current script will usually need a separate handler to process these messages and will normally need to check the identity of the message source.
 

==Code Examples==
Script calls made during the Init() method of an object can never be certain that other objects within the map have already been initialised. In cases where initialisation depends on the existence of other objects [[#PostMessage|PostMessage()]] can be used to delay part or all of the startup. Messages sent in this way are never processed until the next game update and this does not occur until all objects have been initialised.
public void Init(void)
{
inherited();
SetupTasks();
AddHandler(me,"Setup","","SetupHandler");
PostMessage(me,"Setup","",0.0);
}

void SetupHandler(Message msg)
{
if (msg.src == me)
{
MoreSetupTasks();
}
}
 

==Related Methods==
[[Class Router#GetGameObject|Router.GetGameObject()]] 
[[Class Router#PostMessage|Router.PostMessage()]] 
[[TrainzScript Message Reference]] 

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

Class ScenarioBehavior

2021-03-27T12:20:59Z

Marekp9: /* SetStateFlags */ Flags not specified by the parameter keep their old value.

*[[TrainzScript Library Reference|API Hierarchy]]
** [[Class GSObject|GSObject]]
*** [[Class GameObject|GameObject]]
**** [[Class TrainzGameObject|TrainzGameObject]]
***** ScenarioBehavior (scenariobehavior.gs)
** [[Class PropertyObject|PropertyObject]]
*** ScenarioBehavior (scenariobehavior.gs)
 

The ScenarioBehavior class is the base class for session rules.
 

==Constants==
These constants represent flags defining the rule's state. They can be used in combination with [[#GetStateFlags|GetStateFlags()]] and [[#SetStateFlags|SetStateFlags()]] methods. 
The state of the ScenarioBehavior instance can be any combination of these flags, e.g. PAUSED | WAS_COMPLETE | DOES_COMPLETE means the rule is currently not running (is paused), was completed in the past at least once, and can reach a COMPLETE state (i.e. is not a continuous rule running infinitely).

{{TableHeader|width=95%|margin=15px}}
|width=300|public define int '''NONE''' = 0||No flags set.
|-
|public define int '''PAUSED''' = 1||This behavior is currently paused.
|-
|public define int '''COMPLETE''' = 2||This behavior is complete.
|-
|public define int '''WAS_COMPLETE''' = 4||This behavior was complete some time previously.
|-
|public define int '''DOES_COMPLETE''' = 8||This behavior is capable of reaching a <COMPLETE> state. (Distinguishes rules that can complete their execution from infinitely continuous rules.)
|}
 

The initial state of the ScenarioBehavior is PAUSED. 
The inheriting class needs to set the DOES_COMPLETE flag by itself if it wants to mark itself as not continuous rule.

==Pause==
{{MethodHeader|public void Pause(bool pause)}}
;Parameters
*'''pause''' = Whether the rule is being paused (true) or unpaused (false).

;Description
*Pauses or un-pauses this behavior. This is called either by Trainz native code or the behavior's parent. When called this rule should begin or stop whatever it is configured to do.

;Note
This method in ScenarioBehavior does nothing by itself. The rule inheriting from the ScenarioBehavior must override this method and set/clear the [[#Constants|PAUSED]] flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
 

==SetComplete==
{{MethodHeader|public void SetComplete(bool isComplete)}}
;Parameters
*'''isComplete''' = Whether the rule is complete (true) or not (false).

;Description
*Sets this rule as complete. This should be called on any rule that can reach a state where it is no longer doing anything, once it reaches that state. If this rule executes children, then this should not be called until all children have completed.

;Note
This method sets/clears the [[#Constants|COMPLETE]] flag. If called with 'true' parameter it sets also the [[#Constants|WAS_COMPLETE]] flag.
 

==IsComplete==
{{MethodHeader|public bool IsComplete(void)}}
;Return value
*Returns whether this behavior is currently complete
 

==WasComplete==
{{MethodHeader|public bool WasComplete(void)}}
;Return value
*Returns whether this behavior was ever complete
 

==IsPaused==
{{MethodHeader|public bool IsPaused(void)}}
;Return value
*Returns whether this behavior is paused.
 

==GetStateFlags==
{{MethodHeader|public int GetStateFlags(void)}}
;Return value
*Current state flags for this behavior object.
 

==SetStateFlags==
{{MethodHeader|public void SetStateFlags(int flags, bool set)}}
;Parameters
*'''flags''' = state flags that should be set/cleared
*'''set''' = whether the flags should be set (true) or cleared (false)

;Description
Sets the state of the specified flags for this behavior. 
The method changes value only of the flags specified in the 'flags' parameter. All other flags will keep their old value.
 

==GetProperties==
{{MethodHeader|public mandatory [[Class Soup|Soup]] GetProperties(void)}}
;Return value
*Soup database describing the current state of this rule.

;Description
* Inheriting classes should override this to save all rule state. This includes the Surveyor configuration, and Driver runtime state, as this function is used for saving sessions/profiles, and for savegames.
 

==SetProperties==
{{MethodHeader|public mandatory void SetProperties([[Class Soup|Soup]] soup)}}
;Parameters
*'''soup''' - [[Class Soup|Soup]] database describing the current state of this rule.

;Description
* Configures this rule state using a Soup database created by a previous call to [[#GetProperties|GetProperties()]]. This call should restore all data, start any necessary threads, add handlers, etc. such that the rule can continue execution in whatever state it was previously.
 

==GetRequirements==
{{MethodHeader|public [[Class Requirement|Requirement]][] GetRequirements(void)}}
;Return value
*Resource requirements of this rule.

;Description
* This is called by Trainz native code to determine the product requirements of a behavior (if any) so a waybill listing drop-off/pickup requirements can be displayed to the user.
 

==GetChildBehaviors==
{{MethodHeader|public native ScenarioBehavior[] GetChildBehaviors(void)}}
;Return value
*Child behaviors under this one, i.e. the ones immediately below this one in the Surveyor Rules Editor
 

==AreAllChildrenComplete==
{{MethodHeader|public bool AreAllChildrenComplete()}}
;Return value
* Whether all child rules are complete
 

==GetParentBehavior==
{{MethodHeader|public native ScenarioBehavior GetParentBehavior(void)}}
;Return value
* The parent of this rule in the rules list (i.e., the rule that will/should execute it).
* null for "top level" rules.
 

==Reset==
{{MethodHeader|public void Reset(void)}}
;Description
*Resets the [[#Constants|COMPLETE]] and [[#Constants|WAS_COMPLETE]] flags for this rule.
 

==GetDescription==
{{MethodHeader|public string GetDescription(void)}}
;Return value
* The text describing this rule.

;Description
*Gets a short text description of this session rule, for display in the rules list. This should at least contain a basic overview of what the rule does, but may also reference specific configured objects etc. Basic html markup is supported but do not include images, embedded objects, etc.

;Note
* If not overridden, then the method returns string with key "description" from the [[Class StringTable|string table]].
 

==AppendDependencies==
{{MethodHeader|public void AppendDependencies([[Class KUIDList|KUIDList]] io_dependencies)}}
;Parameters
*'''io_dependencies''' - ???

;Description
*Gets any asset dependencies that are specific to this rule instance. This method is called by Trainz to determine the asset dependencies of this rule instance, as configured by the player in Surveyor. Inheriting scripts should override this to add assets that the player may configure/select, e.g. html assets, sounds, textures.
 

==GetDebugString==
{{MethodHeader|public string GetDebugString(void)}}
;Return value
* The human-readable string identifying this ScenarioBehavior.

;Description
*Returns a human-readable string identifying this ScenarioBehavior. Used for debugging purposes. The exact contents of this string may vary based on the class of this object and the Trainz version. Do not attempt to machine-parse this value.
 

==SetSessionString==
{{MethodHeader|native void SetSessionString(string tag, string value)}}
;Parameters
*'''tag''' - A unique identifier by which to refer to this string.
*'''value''' - The English value for this string.

;Description
*SURVEYOR ONLY - Creates a localisable string-table entry in the current session asset with the tag and English value passed. This should be used in any situation where a session creator is required to enter player visible text. The KUID for this ScenarioBehaviour will be prepended to the tag when the config.txt is updated. Use the [[#GetSessionString|GetSessionString()]] function to retrieve the string for display
 

==GetSessionString==
{{MethodHeader|native string GetSessionString(string tag)}}
;Parameters
*'''tag''' - The unique identifier by which to refer to this string

;Return value
* Session string-table entry created by this asset using the [[#SetSessionString|SetSessionString()]] function.
** If present the string for the currently active local will be returned.
** English value will be returned if localised is not present.
** Empty string will be returned if no string with the specified tag exists for this asset.
 

==IsCorrectlyConfigured==
{{MethodHeader|public bool IsCorrectlyConfigured()}}
;Return value
* true if this rule is correctly configured

;Description
* Called by native code in Surveyor to test whether this rule has been correctly configured by the player. If it returns false Surveyor will show a visual indication to the player that the setup needs action.
 

==SetChildrenLimits==
{{MethodHeader|public void SetChildrenLimits(int minChildren, int maxChildren)}}
;Parameters
*'''minChildren''' - The minimum number of children required
*'''maxChildren''' - The maximum number of children allowed, or -1 for no max

;Description
* Sets the limits on the number of children this rule can have. Rules configured in Surveyor with more than the max or less that the minimum will display as incorrectly configured (via [[#IsCorrectlyConfigured|IsCorrectlyConfigured()]]).
 

==GetChildRelationshipIcon==
{{MethodHeader|public string GetChildRelationshipIcon(ScenarioBehavior child)}}
;Parameters
*'''child''' - The child of this rule to get the relationship for

;Return value
*Either:
** "none" - The child is not used by this rule in any way
** "simultaneous" - Rule is a child, and all children are executed simultaneously on completion
** A positive integer, representing the order in which a child rule will be executed by the parent on completion (e.g., "1" is first, "2" is second, etc.)
** A path to a custom icon file within this rule assets dir
** A KUID for a custom texture asset

;Description
* Called by native code in Surveyor to get an icon to indicate the relationship of a child rule to its parent (this rule). This is for Surveyor display purposes only and provides no rule functionality.
 

==GetSessionProperties==
{{MethodHeader|public [[Class Soup|Soup]] GetSessionProperties(void)}}
;Return value
* [[Class Soup|Soup]] form of rule-data container to be written.

;Description
* Retrieve any data this rule wishes to store in the config.txt of the session, to be made available to script outside of the session (i.e. when it is not running), such as in a menu etc.
 

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

Class ScenarioBehavior

2021-03-27T12:17:19Z

Marekp9: /* Constants */ Added information about the default state.

*[[TrainzScript Library Reference|API Hierarchy]]
** [[Class GSObject|GSObject]]
*** [[Class GameObject|GameObject]]
**** [[Class TrainzGameObject|TrainzGameObject]]
***** ScenarioBehavior (scenariobehavior.gs)
** [[Class PropertyObject|PropertyObject]]
*** ScenarioBehavior (scenariobehavior.gs)
 

The ScenarioBehavior class is the base class for session rules.
 

==Constants==
These constants represent flags defining the rule's state. They can be used in combination with [[#GetStateFlags|GetStateFlags()]] and [[#SetStateFlags|SetStateFlags()]] methods. 
The state of the ScenarioBehavior instance can be any combination of these flags, e.g. PAUSED | WAS_COMPLETE | DOES_COMPLETE means the rule is currently not running (is paused), was completed in the past at least once, and can reach a COMPLETE state (i.e. is not a continuous rule running infinitely).

{{TableHeader|width=95%|margin=15px}}
|width=300|public define int '''NONE''' = 0||No flags set.
|-
|public define int '''PAUSED''' = 1||This behavior is currently paused.
|-
|public define int '''COMPLETE''' = 2||This behavior is complete.
|-
|public define int '''WAS_COMPLETE''' = 4||This behavior was complete some time previously.
|-
|public define int '''DOES_COMPLETE''' = 8||This behavior is capable of reaching a <COMPLETE> state. (Distinguishes rules that can complete their execution from infinitely continuous rules.)
|}
 

The initial state of the ScenarioBehavior is PAUSED. 
The inheriting class needs to set the DOES_COMPLETE flag by itself if it wants to mark itself as not continuous rule.

==Pause==
{{MethodHeader|public void Pause(bool pause)}}
;Parameters
*'''pause''' = Whether the rule is being paused (true) or unpaused (false).

;Description
*Pauses or un-pauses this behavior. This is called either by Trainz native code or the behavior's parent. When called this rule should begin or stop whatever it is configured to do.

;Note
This method in ScenarioBehavior does nothing by itself. The rule inheriting from the ScenarioBehavior must override this method and set/clear the [[#Constants|PAUSED]] flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
 

==SetComplete==
{{MethodHeader|public void SetComplete(bool isComplete)}}
;Parameters
*'''isComplete''' = Whether the rule is complete (true) or not (false).

;Description
*Sets this rule as complete. This should be called on any rule that can reach a state where it is no longer doing anything, once it reaches that state. If this rule executes children, then this should not be called until all children have completed.

;Note
This method sets/clears the [[#Constants|COMPLETE]] flag. If called with 'true' parameter it sets also the [[#Constants|WAS_COMPLETE]] flag.
 

==IsComplete==
{{MethodHeader|public bool IsComplete(void)}}
;Return value
*Returns whether this behavior is currently complete
 

==WasComplete==
{{MethodHeader|public bool WasComplete(void)}}
;Return value
*Returns whether this behavior was ever complete
 

==IsPaused==
{{MethodHeader|public bool IsPaused(void)}}
;Return value
*Returns whether this behavior is paused.
 

==GetStateFlags==
{{MethodHeader|public int GetStateFlags(void)}}
;Return value
*Current state flags for this behavior object.
 

==SetStateFlags==
{{MethodHeader|public void SetStateFlags(int flags, bool set)}}
;Parameters
*'''flags''' = state flags that should be set/cleared
*'''set''' = whether the flags should be set (true) or cleared (false)

;Description
Sets the state of the specified flags for this behavior.
 

==GetProperties==
{{MethodHeader|public mandatory [[Class Soup|Soup]] GetProperties(void)}}
;Return value
*Soup database describing the current state of this rule.

;Description
* Inheriting classes should override this to save all rule state. This includes the Surveyor configuration, and Driver runtime state, as this function is used for saving sessions/profiles, and for savegames.
 

==SetProperties==
{{MethodHeader|public mandatory void SetProperties([[Class Soup|Soup]] soup)}}
;Parameters
*'''soup''' - [[Class Soup|Soup]] database describing the current state of this rule.

;Description
* Configures this rule state using a Soup database created by a previous call to [[#GetProperties|GetProperties()]]. This call should restore all data, start any necessary threads, add handlers, etc. such that the rule can continue execution in whatever state it was previously.
 

==GetRequirements==
{{MethodHeader|public [[Class Requirement|Requirement]][] GetRequirements(void)}}
;Return value
*Resource requirements of this rule.

;Description
* This is called by Trainz native code to determine the product requirements of a behavior (if any) so a waybill listing drop-off/pickup requirements can be displayed to the user.
 

==GetChildBehaviors==
{{MethodHeader|public native ScenarioBehavior[] GetChildBehaviors(void)}}
;Return value
*Child behaviors under this one, i.e. the ones immediately below this one in the Surveyor Rules Editor
 

==AreAllChildrenComplete==
{{MethodHeader|public bool AreAllChildrenComplete()}}
;Return value
* Whether all child rules are complete
 

==GetParentBehavior==
{{MethodHeader|public native ScenarioBehavior GetParentBehavior(void)}}
;Return value
* The parent of this rule in the rules list (i.e., the rule that will/should execute it).
* null for "top level" rules.
 

==Reset==
{{MethodHeader|public void Reset(void)}}
;Description
*Resets the [[#Constants|COMPLETE]] and [[#Constants|WAS_COMPLETE]] flags for this rule.
 

==GetDescription==
{{MethodHeader|public string GetDescription(void)}}
;Return value
* The text describing this rule.

;Description
*Gets a short text description of this session rule, for display in the rules list. This should at least contain a basic overview of what the rule does, but may also reference specific configured objects etc. Basic html markup is supported but do not include images, embedded objects, etc.

;Note
* If not overridden, then the method returns string with key "description" from the [[Class StringTable|string table]].
 

==AppendDependencies==
{{MethodHeader|public void AppendDependencies([[Class KUIDList|KUIDList]] io_dependencies)}}
;Parameters
*'''io_dependencies''' - ???

;Description
*Gets any asset dependencies that are specific to this rule instance. This method is called by Trainz to determine the asset dependencies of this rule instance, as configured by the player in Surveyor. Inheriting scripts should override this to add assets that the player may configure/select, e.g. html assets, sounds, textures.
 

==GetDebugString==
{{MethodHeader|public string GetDebugString(void)}}
;Return value
* The human-readable string identifying this ScenarioBehavior.

;Description
*Returns a human-readable string identifying this ScenarioBehavior. Used for debugging purposes. The exact contents of this string may vary based on the class of this object and the Trainz version. Do not attempt to machine-parse this value.
 

==SetSessionString==
{{MethodHeader|native void SetSessionString(string tag, string value)}}
;Parameters
*'''tag''' - A unique identifier by which to refer to this string.
*'''value''' - The English value for this string.

;Description
*SURVEYOR ONLY - Creates a localisable string-table entry in the current session asset with the tag and English value passed. This should be used in any situation where a session creator is required to enter player visible text. The KUID for this ScenarioBehaviour will be prepended to the tag when the config.txt is updated. Use the [[#GetSessionString|GetSessionString()]] function to retrieve the string for display
 

==GetSessionString==
{{MethodHeader|native string GetSessionString(string tag)}}
;Parameters
*'''tag''' - The unique identifier by which to refer to this string

;Return value
* Session string-table entry created by this asset using the [[#SetSessionString|SetSessionString()]] function.
** If present the string for the currently active local will be returned.
** English value will be returned if localised is not present.
** Empty string will be returned if no string with the specified tag exists for this asset.
 

==IsCorrectlyConfigured==
{{MethodHeader|public bool IsCorrectlyConfigured()}}
;Return value
* true if this rule is correctly configured

;Description
* Called by native code in Surveyor to test whether this rule has been correctly configured by the player. If it returns false Surveyor will show a visual indication to the player that the setup needs action.
 

==SetChildrenLimits==
{{MethodHeader|public void SetChildrenLimits(int minChildren, int maxChildren)}}
;Parameters
*'''minChildren''' - The minimum number of children required
*'''maxChildren''' - The maximum number of children allowed, or -1 for no max

;Description
* Sets the limits on the number of children this rule can have. Rules configured in Surveyor with more than the max or less that the minimum will display as incorrectly configured (via [[#IsCorrectlyConfigured|IsCorrectlyConfigured()]]).
 

==GetChildRelationshipIcon==
{{MethodHeader|public string GetChildRelationshipIcon(ScenarioBehavior child)}}
;Parameters
*'''child''' - The child of this rule to get the relationship for

;Return value
*Either:
** "none" - The child is not used by this rule in any way
** "simultaneous" - Rule is a child, and all children are executed simultaneously on completion
** A positive integer, representing the order in which a child rule will be executed by the parent on completion (e.g., "1" is first, "2" is second, etc.)
** A path to a custom icon file within this rule assets dir
** A KUID for a custom texture asset

;Description
* Called by native code in Surveyor to get an icon to indicate the relationship of a child rule to its parent (this rule). This is for Surveyor display purposes only and provides no rule functionality.
 

==GetSessionProperties==
{{MethodHeader|public [[Class Soup|Soup]] GetSessionProperties(void)}}
;Return value
* [[Class Soup|Soup]] form of rule-data container to be written.

;Description
* Retrieve any data this rule wishes to store in the config.txt of the session, to be made available to script outside of the session (i.e. when it is not running), such as in a menu etc.
 

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

Class ScenarioBehavior

2021-03-26T22:23:08Z

Marekp9: Changed overwrite -> override

*[[TrainzScript Library Reference|API Hierarchy]]
** [[Class GSObject|GSObject]]
*** [[Class GameObject|GameObject]]
**** [[Class TrainzGameObject|TrainzGameObject]]
***** ScenarioBehavior (scenariobehavior.gs)
** [[Class PropertyObject|PropertyObject]]
*** ScenarioBehavior (scenariobehavior.gs)
 

The ScenarioBehavior class is the base class for session rules.
 

==Constants==
*These constants represent flags defining the rule's state. They can be used in combination with [[#GetStateFlags|GetStateFlags()]] and [[#SetStateFlags|SetStateFlags()]] methods.

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NONE = 0||No flags set.
|-
|public define int PAUSED = 1||This behavior is currently paused.
|-
|public define int COMPLETE = 2||This behavior is complete.
|-
|public define int WAS_COMPLETE = 4||This behavior was complete some time previously.
|-
|public define int DOES_COMPLETE = 8||This behavior is capable of reaching a <COMPLETE> state.
|}
 

==Pause==
{{MethodHeader|public void Pause(bool pause)}}
;Parameters
*'''pause''' = Whether the rule is being paused (true) or unpaused (false).

;Description
*Pauses or un-pauses this behavior. This is called either by Trainz native code or the behavior's parent. When called this rule should begin or stop whatever it is configured to do.

;Note
This method in ScenarioBehavior does nothing by itself. The rule inheriting from the ScenarioBehavior must override this method and set/clear the [[#Constants|PAUSED]] flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
 

==SetComplete==
{{MethodHeader|public void SetComplete(bool isComplete)}}
;Parameters
*'''isComplete''' = Whether the rule is complete (true) or not (false).

;Description
*Sets this rule as complete. This should be called on any rule that can reach a state where it is no longer doing anything, once it reaches that state. If this rule executes children, then this should not be called until all children have completed.

;Note
This method sets/clears the [[#Constants|COMPLETE]] flag. If called with 'true' parameter it sets also the [[#Constants|WAS_COMPLETE]] flag.
 

==IsComplete==
{{MethodHeader|public bool IsComplete(void)}}
;Return value
*Returns whether this behavior is currently complete
 

==WasComplete==
{{MethodHeader|public bool WasComplete(void)}}
;Return value
*Returns whether this behavior was ever complete
 

==IsPaused==
{{MethodHeader|public bool IsPaused(void)}}
;Return value
*Returns whether this behavior is paused.
 

==GetStateFlags==
{{MethodHeader|public int GetStateFlags(void)}}
;Return value
*Current state flags for this behavior object.
 

==SetStateFlags==
{{MethodHeader|public void SetStateFlags(int flags, bool set)}}
;Parameters
*'''flags''' = state flags that should be set/cleared
*'''set''' = whether the flags should be set (true) or cleared (false)

;Description
Sets the state of the specified flags for this behavior.
 

==GetProperties==
{{MethodHeader|public mandatory [[Class Soup|Soup]] GetProperties(void)}}
;Return value
*Soup database describing the current state of this rule.

;Description
* Inheriting classes should override this to save all rule state. This includes the Surveyor configuration, and Driver runtime state, as this function is used for saving sessions/profiles, and for savegames.
 

==SetProperties==
{{MethodHeader|public mandatory void SetProperties([[Class Soup|Soup]] soup)}}
;Parameters
*'''soup''' - [[Class Soup|Soup]] database describing the current state of this rule.

;Description
* Configures this rule state using a Soup database created by a previous call to [[#GetProperties|GetProperties()]]. This call should restore all data, start any necessary threads, add handlers, etc. such that the rule can continue execution in whatever state it was previously.
 

==GetRequirements==
{{MethodHeader|public [[Class Requirement|Requirement]][] GetRequirements(void)}}
;Return value
*Resource requirements of this rule.

;Description
* This is called by Trainz native code to determine the product requirements of a behavior (if any) so a waybill listing drop-off/pickup requirements can be displayed to the user.
 

==GetChildBehaviors==
{{MethodHeader|public native ScenarioBehavior[] GetChildBehaviors(void)}}
;Return value
*Child behaviors under this one, i.e. the ones immediately below this one in the Surveyor Rules Editor
 

==AreAllChildrenComplete==
{{MethodHeader|public bool AreAllChildrenComplete()}}
;Return value
* Whether all child rules are complete
 

==GetParentBehavior==
{{MethodHeader|public native ScenarioBehavior GetParentBehavior(void)}}
;Return value
* The parent of this rule in the rules list (i.e., the rule that will/should execute it).
* null for "top level" rules.
 

==Reset==
{{MethodHeader|public void Reset(void)}}
;Description
*Resets the [[#Constants|COMPLETE]] and [[#Constants|WAS_COMPLETE]] flags for this rule.
 

==GetDescription==
{{MethodHeader|public string GetDescription(void)}}
;Return value
* The text describing this rule.

;Description
*Gets a short text description of this session rule, for display in the rules list. This should at least contain a basic overview of what the rule does, but may also reference specific configured objects etc. Basic html markup is supported but do not include images, embedded objects, etc.

;Note
* If not overridden, then the method returns string with key "description" from the [[Class StringTable|string table]].
 

==AppendDependencies==
{{MethodHeader|public void AppendDependencies([[Class KUIDList|KUIDList]] io_dependencies)}}
;Parameters
*'''io_dependencies''' - ???

;Description
*Gets any asset dependencies that are specific to this rule instance. This method is called by Trainz to determine the asset dependencies of this rule instance, as configured by the player in Surveyor. Inheriting scripts should override this to add assets that the player may configure/select, e.g. html assets, sounds, textures.
 

==GetDebugString==
{{MethodHeader|public string GetDebugString(void)}}
;Return value
* The human-readable string identifying this ScenarioBehavior.

;Description
*Returns a human-readable string identifying this ScenarioBehavior. Used for debugging purposes. The exact contents of this string may vary based on the class of this object and the Trainz version. Do not attempt to machine-parse this value.
 

==SetSessionString==
{{MethodHeader|native void SetSessionString(string tag, string value)}}
;Parameters
*'''tag''' - A unique identifier by which to refer to this string.
*'''value''' - The English value for this string.

;Description
*SURVEYOR ONLY - Creates a localisable string-table entry in the current session asset with the tag and English value passed. This should be used in any situation where a session creator is required to enter player visible text. The KUID for this ScenarioBehaviour will be prepended to the tag when the config.txt is updated. Use the [[#GetSessionString|GetSessionString()]] function to retrieve the string for display
 

==GetSessionString==
{{MethodHeader|native string GetSessionString(string tag)}}
;Parameters
*'''tag''' - The unique identifier by which to refer to this string

;Return value
* Session string-table entry created by this asset using the [[#SetSessionString|SetSessionString()]] function.
** If present the string for the currently active local will be returned.
** English value will be returned if localised is not present.
** Empty string will be returned if no string with the specified tag exists for this asset.
 

==IsCorrectlyConfigured==
{{MethodHeader|public bool IsCorrectlyConfigured()}}
;Return value
* true if this rule is correctly configured

;Description
* Called by native code in Surveyor to test whether this rule has been correctly configured by the player. If it returns false Surveyor will show a visual indication to the player that the setup needs action.
 

==SetChildrenLimits==
{{MethodHeader|public void SetChildrenLimits(int minChildren, int maxChildren)}}
;Parameters
*'''minChildren''' - The minimum number of children required
*'''maxChildren''' - The maximum number of children allowed, or -1 for no max

;Description
* Sets the limits on the number of children this rule can have. Rules configured in Surveyor with more than the max or less that the minimum will display as incorrectly configured (via [[#IsCorrectlyConfigured|IsCorrectlyConfigured()]]).
 

==GetChildRelationshipIcon==
{{MethodHeader|public string GetChildRelationshipIcon(ScenarioBehavior child)}}
;Parameters
*'''child''' - The child of this rule to get the relationship for

;Return value
*Either:
** "none" - The child is not used by this rule in any way
** "simultaneous" - Rule is a child, and all children are executed simultaneously on completion
** A positive integer, representing the order in which a child rule will be executed by the parent on completion (e.g., "1" is first, "2" is second, etc.)
** A path to a custom icon file within this rule assets dir
** A KUID for a custom texture asset

;Description
* Called by native code in Surveyor to get an icon to indicate the relationship of a child rule to its parent (this rule). This is for Surveyor display purposes only and provides no rule functionality.
 

==GetSessionProperties==
{{MethodHeader|public [[Class Soup|Soup]] GetSessionProperties(void)}}
;Return value
* [[Class Soup|Soup]] form of rule-data container to be written.

;Description
* Retrieve any data this rule wishes to store in the config.txt of the session, to be made available to script outside of the session (i.e. when it is not running), such as in a menu etc.
 

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

Class ScenarioBehavior

2021-03-26T21:14:14Z

Marekp9: /* GetSessionString */ Corrected display of link to SetSessionString()

*[[TrainzScript Library Reference|API Hierarchy]]
** [[Class GSObject|GSObject]]
*** [[Class GameObject|GameObject]]
**** [[Class TrainzGameObject|TrainzGameObject]]
***** ScenarioBehavior (scenariobehavior.gs)
** [[Class PropertyObject|PropertyObject]]
*** ScenarioBehavior (scenariobehavior.gs)
 

The ScenarioBehavior class is the base class for session rules.
 

==Constants==
*These constants represent flags defining the rule's state. They can be used in combination with [[#GetStateFlags|GetStateFlags()]] and [[#SetStateFlags|SetStateFlags()]] methods.

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NONE = 0||No flags set.
|-
|public define int PAUSED = 1||This behavior is currently paused.
|-
|public define int COMPLETE = 2||This behavior is complete.
|-
|public define int WAS_COMPLETE = 4||This behavior was complete some time previously.
|-
|public define int DOES_COMPLETE = 8||This behavior is capable of reaching a <COMPLETE> state.
|}
 

==Pause==
{{MethodHeader|public void Pause(bool pause)}}
;Parameters
*'''pause''' = Whether the rule is being paused (true) or unpaused (false).

;Description
*Pauses or un-pauses this behavior. This is called either by Trainz native code or the behavior's parent. When called this rule should begin or stop whatever it is configured to do.

;Note
This method in ScenarioBehavior does nothing by itself. The rule inheriting from the ScenarioBehavior must overwrite this method and set/clear the [[#Constants|PAUSED]] flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
 

==SetComplete==
{{MethodHeader|public void SetComplete(bool isComplete)}}
;Parameters
*'''isComplete''' = Whether the rule is complete (true) or not (false).

;Description
*Sets this rule as complete. This should be called on any rule that can reach a state where it is no longer doing anything, once it reaches that state. If this rule executes children, then this should not be called until all children have completed.

;Note
This method sets/clears the [[#Constants|COMPLETE]] flag. If called with 'true' parameter it sets also the [[#Constants|WAS_COMPLETE]] flag.
 

==IsComplete==
{{MethodHeader|public bool IsComplete(void)}}
;Return value
*Returns whether this behavior is currently complete
 

==WasComplete==
{{MethodHeader|public bool WasComplete(void)}}
;Return value
*Returns whether this behavior was ever complete
 

==IsPaused==
{{MethodHeader|public bool IsPaused(void)}}
;Return value
*Returns whether this behavior is paused.
 

==GetStateFlags==
{{MethodHeader|public int GetStateFlags(void)}}
;Return value
*Current state flags for this behavior object.
 

==SetStateFlags==
{{MethodHeader|public void SetStateFlags(int flags, bool set)}}
;Parameters
*'''flags''' = state flags that should be set/cleared
*'''set''' = whether the flags should be set (true) or cleared (false)

;Description
Sets the state of the specified flags for this behavior.
 

==GetProperties==
{{MethodHeader|public mandatory [[Class Soup|Soup]] GetProperties(void)}}
;Return value
*Soup database describing the current state of this rule.

;Description
* Inheriting classes should override this to save all rule state. This includes the Surveyor configuration, and Driver runtime state, as this function is used for saving sessions/profiles, and for savegames.
 

==SetProperties==
{{MethodHeader|public mandatory void SetProperties([[Class Soup|Soup]] soup)}}
;Parameters
*'''soup''' - [[Class Soup|Soup]] database describing the current state of this rule.

;Description
* Configures this rule state using a Soup database created by a previous call to [[#GetProperties|GetProperties()]]. This call should restore all data, start any necessary threads, add handlers, etc. such that the rule can continue execution in whatever state it was previously.
 

==GetRequirements==
{{MethodHeader|public [[Class Requirement|Requirement]][] GetRequirements(void)}}
;Return value
*Resource requirements of this rule.

;Description
* This is called by Trainz native code to determine the product requirements of a behavior (if any) so a waybill listing drop-off/pickup requirements can be displayed to the user.
 

==GetChildBehaviors==
{{MethodHeader|public native ScenarioBehavior[] GetChildBehaviors(void)}}
;Return value
*Child behaviors under this one, i.e. the ones immediately below this one in the Surveyor Rules Editor
 

==AreAllChildrenComplete==
{{MethodHeader|public bool AreAllChildrenComplete()}}
;Return value
* Whether all child rules are complete
 

==GetParentBehavior==
{{MethodHeader|public native ScenarioBehavior GetParentBehavior(void)}}
;Return value
* The parent of this rule in the rules list (i.e., the rule that will/should execute it).
* null for "top level" rules.
 

==Reset==
{{MethodHeader|public void Reset(void)}}
;Description
*Resets the [[#Constants|COMPLETE]] and [[#Constants|WAS_COMPLETE]] flags for this rule.
 

==GetDescription==
{{MethodHeader|public string GetDescription(void)}}
;Return value
* The text describing this rule.

;Description
*Gets a short text description of this session rule, for display in the rules list. This should at least contain a basic overview of what the rule does, but may also reference specific configured objects etc. Basic html markup is supported but do not include images, embedded objects, etc.

;Note
* If not overwritten, then the method returns string with key "description" from the [[Class StringTable|string table]].
 

==AppendDependencies==
{{MethodHeader|public void AppendDependencies([[Class KUIDList|KUIDList]] io_dependencies)}}
;Parameters
*'''io_dependencies''' - ???

;Description
*Gets any asset dependencies that are specific to this rule instance. This method is called by Trainz to determine the asset dependencies of this rule instance, as configured by the player in Surveyor. Inheriting scripts should override this to add assets that the player may configure/select, e.g. html assets, sounds, textures.
 

==GetDebugString==
{{MethodHeader|public string GetDebugString(void)}}
;Return value
* The human-readable string identifying this ScenarioBehavior.

;Description
*Returns a human-readable string identifying this ScenarioBehavior. Used for debugging purposes. The exact contents of this string may vary based on the class of this object and the Trainz version. Do not attempt to machine-parse this value.
 

==SetSessionString==
{{MethodHeader|native void SetSessionString(string tag, string value)}}
;Parameters
*'''tag''' - A unique identifier by which to refer to this string.
*'''value''' - The English value for this string.

;Description
*SURVEYOR ONLY - Creates a localisable string-table entry in the current session asset with the tag and English value passed. This should be used in any situation where a session creator is required to enter player visible text. The KUID for this ScenarioBehaviour will be prepended to the tag when the config.txt is updated. Use the [[#GetSessionString|GetSessionString()]] function to retrieve the string for display
 

==GetSessionString==
{{MethodHeader|native string GetSessionString(string tag)}}
;Parameters
*'''tag''' - The unique identifier by which to refer to this string

;Return value
* Session string-table entry created by this asset using the [[#SetSessionString|SetSessionString()]] function.
** If present the string for the currently active local will be returned.
** English value will be returned if localised is not present.
** Empty string will be returned if no string with the specified tag exists for this asset.
 

==IsCorrectlyConfigured==
{{MethodHeader|public bool IsCorrectlyConfigured()}}
;Return value
* true if this rule is correctly configured

;Description
* Called by native code in Surveyor to test whether this rule has been correctly configured by the player. If it returns false Surveyor will show a visual indication to the player that the setup needs action.
 

==SetChildrenLimits==
{{MethodHeader|public void SetChildrenLimits(int minChildren, int maxChildren)}}
;Parameters
*'''minChildren''' - The minimum number of children required
*'''maxChildren''' - The maximum number of children allowed, or -1 for no max

;Description
* Sets the limits on the number of children this rule can have. Rules configured in Surveyor with more than the max or less that the minimum will display as incorrectly configured (via [[#IsCorrectlyConfigured|IsCorrectlyConfigured()]]).
 

==GetChildRelationshipIcon==
{{MethodHeader|public string GetChildRelationshipIcon(ScenarioBehavior child)}}
;Parameters
*'''child''' - The child of this rule to get the relationship for

;Return value
*Either:
** "none" - The child is not used by this rule in any way
** "simultaneous" - Rule is a child, and all children are executed simultaneously on completion
** A positive integer, representing the order in which a child rule will be executed by the parent on completion (e.g., "1" is first, "2" is second, etc.)
** A path to a custom icon file within this rule assets dir
** A KUID for a custom texture asset

;Description
* Called by native code in Surveyor to get an icon to indicate the relationship of a child rule to its parent (this rule). This is for Surveyor display purposes only and provides no rule functionality.
 

==GetSessionProperties==
{{MethodHeader|public [[Class Soup|Soup]] GetSessionProperties(void)}}
;Return value
* [[Class Soup|Soup]] form of rule-data container to be written.

;Description
* Retrieve any data this rule wishes to store in the config.txt of the session, to be made available to script outside of the session (i.e. when it is not running), such as in a menu etc.
 

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

Class ScenarioBehavior

2021-03-26T21:12:56Z

Marekp9: /* SetSessionString */ Corrected display of link to GetSessionString()

*[[TrainzScript Library Reference|API Hierarchy]]
** [[Class GSObject|GSObject]]
*** [[Class GameObject|GameObject]]
**** [[Class TrainzGameObject|TrainzGameObject]]
***** ScenarioBehavior (scenariobehavior.gs)
** [[Class PropertyObject|PropertyObject]]
*** ScenarioBehavior (scenariobehavior.gs)
 

The ScenarioBehavior class is the base class for session rules.
 

==Constants==
*These constants represent flags defining the rule's state. They can be used in combination with [[#GetStateFlags|GetStateFlags()]] and [[#SetStateFlags|SetStateFlags()]] methods.

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NONE = 0||No flags set.
|-
|public define int PAUSED = 1||This behavior is currently paused.
|-
|public define int COMPLETE = 2||This behavior is complete.
|-
|public define int WAS_COMPLETE = 4||This behavior was complete some time previously.
|-
|public define int DOES_COMPLETE = 8||This behavior is capable of reaching a <COMPLETE> state.
|}
 

==Pause==
{{MethodHeader|public void Pause(bool pause)}}
;Parameters
*'''pause''' = Whether the rule is being paused (true) or unpaused (false).

;Description
*Pauses or un-pauses this behavior. This is called either by Trainz native code or the behavior's parent. When called this rule should begin or stop whatever it is configured to do.

;Note
This method in ScenarioBehavior does nothing by itself. The rule inheriting from the ScenarioBehavior must overwrite this method and set/clear the [[#Constants|PAUSED]] flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
 

==SetComplete==
{{MethodHeader|public void SetComplete(bool isComplete)}}
;Parameters
*'''isComplete''' = Whether the rule is complete (true) or not (false).

;Description
*Sets this rule as complete. This should be called on any rule that can reach a state where it is no longer doing anything, once it reaches that state. If this rule executes children, then this should not be called until all children have completed.

;Note
This method sets/clears the [[#Constants|COMPLETE]] flag. If called with 'true' parameter it sets also the [[#Constants|WAS_COMPLETE]] flag.
 

==IsComplete==
{{MethodHeader|public bool IsComplete(void)}}
;Return value
*Returns whether this behavior is currently complete
 

==WasComplete==
{{MethodHeader|public bool WasComplete(void)}}
;Return value
*Returns whether this behavior was ever complete
 

==IsPaused==
{{MethodHeader|public bool IsPaused(void)}}
;Return value
*Returns whether this behavior is paused.
 

==GetStateFlags==
{{MethodHeader|public int GetStateFlags(void)}}
;Return value
*Current state flags for this behavior object.
 

==SetStateFlags==
{{MethodHeader|public void SetStateFlags(int flags, bool set)}}
;Parameters
*'''flags''' = state flags that should be set/cleared
*'''set''' = whether the flags should be set (true) or cleared (false)

;Description
Sets the state of the specified flags for this behavior.
 

==GetProperties==
{{MethodHeader|public mandatory [[Class Soup|Soup]] GetProperties(void)}}
;Return value
*Soup database describing the current state of this rule.

;Description
* Inheriting classes should override this to save all rule state. This includes the Surveyor configuration, and Driver runtime state, as this function is used for saving sessions/profiles, and for savegames.
 

==SetProperties==
{{MethodHeader|public mandatory void SetProperties([[Class Soup|Soup]] soup)}}
;Parameters
*'''soup''' - [[Class Soup|Soup]] database describing the current state of this rule.

;Description
* Configures this rule state using a Soup database created by a previous call to [[#GetProperties|GetProperties()]]. This call should restore all data, start any necessary threads, add handlers, etc. such that the rule can continue execution in whatever state it was previously.
 

==GetRequirements==
{{MethodHeader|public [[Class Requirement|Requirement]][] GetRequirements(void)}}
;Return value
*Resource requirements of this rule.

;Description
* This is called by Trainz native code to determine the product requirements of a behavior (if any) so a waybill listing drop-off/pickup requirements can be displayed to the user.
 

==GetChildBehaviors==
{{MethodHeader|public native ScenarioBehavior[] GetChildBehaviors(void)}}
;Return value
*Child behaviors under this one, i.e. the ones immediately below this one in the Surveyor Rules Editor
 

==AreAllChildrenComplete==
{{MethodHeader|public bool AreAllChildrenComplete()}}
;Return value
* Whether all child rules are complete
 

==GetParentBehavior==
{{MethodHeader|public native ScenarioBehavior GetParentBehavior(void)}}
;Return value
* The parent of this rule in the rules list (i.e., the rule that will/should execute it).
* null for "top level" rules.
 

==Reset==
{{MethodHeader|public void Reset(void)}}
;Description
*Resets the [[#Constants|COMPLETE]] and [[#Constants|WAS_COMPLETE]] flags for this rule.
 

==GetDescription==
{{MethodHeader|public string GetDescription(void)}}
;Return value
* The text describing this rule.

;Description
*Gets a short text description of this session rule, for display in the rules list. This should at least contain a basic overview of what the rule does, but may also reference specific configured objects etc. Basic html markup is supported but do not include images, embedded objects, etc.

;Note
* If not overwritten, then the method returns string with key "description" from the [[Class StringTable|string table]].
 

==AppendDependencies==
{{MethodHeader|public void AppendDependencies([[Class KUIDList|KUIDList]] io_dependencies)}}
;Parameters
*'''io_dependencies''' - ???

;Description
*Gets any asset dependencies that are specific to this rule instance. This method is called by Trainz to determine the asset dependencies of this rule instance, as configured by the player in Surveyor. Inheriting scripts should override this to add assets that the player may configure/select, e.g. html assets, sounds, textures.
 

==GetDebugString==
{{MethodHeader|public string GetDebugString(void)}}
;Return value
* The human-readable string identifying this ScenarioBehavior.

;Description
*Returns a human-readable string identifying this ScenarioBehavior. Used for debugging purposes. The exact contents of this string may vary based on the class of this object and the Trainz version. Do not attempt to machine-parse this value.
 

==SetSessionString==
{{MethodHeader|native void SetSessionString(string tag, string value)}}
;Parameters
*'''tag''' - A unique identifier by which to refer to this string.
*'''value''' - The English value for this string.

;Description
*SURVEYOR ONLY - Creates a localisable string-table entry in the current session asset with the tag and English value passed. This should be used in any situation where a session creator is required to enter player visible text. The KUID for this ScenarioBehaviour will be prepended to the tag when the config.txt is updated. Use the [[#GetSessionString|GetSessionString()]] function to retrieve the string for display
 

==GetSessionString==
{{MethodHeader|native string GetSessionString(string tag)}}
;Parameters
*'''tag''' - The unique identifier by which to refer to this string

;Return value
* Session string-table entry created by this asset using the [[#SetSessionString]]() function.
** If present the string for the currently active local will be returned.
** English value will be returned if localised is not present.
** Empty string will be returned if no string with the specified tag exists for this asset.
 

==IsCorrectlyConfigured==
{{MethodHeader|public bool IsCorrectlyConfigured()}}
;Return value
* true if this rule is correctly configured

;Description
* Called by native code in Surveyor to test whether this rule has been correctly configured by the player. If it returns false Surveyor will show a visual indication to the player that the setup needs action.
 

==SetChildrenLimits==
{{MethodHeader|public void SetChildrenLimits(int minChildren, int maxChildren)}}
;Parameters
*'''minChildren''' - The minimum number of children required
*'''maxChildren''' - The maximum number of children allowed, or -1 for no max

;Description
* Sets the limits on the number of children this rule can have. Rules configured in Surveyor with more than the max or less that the minimum will display as incorrectly configured (via [[#IsCorrectlyConfigured|IsCorrectlyConfigured()]]).
 

==GetChildRelationshipIcon==
{{MethodHeader|public string GetChildRelationshipIcon(ScenarioBehavior child)}}
;Parameters
*'''child''' - The child of this rule to get the relationship for

;Return value
*Either:
** "none" - The child is not used by this rule in any way
** "simultaneous" - Rule is a child, and all children are executed simultaneously on completion
** A positive integer, representing the order in which a child rule will be executed by the parent on completion (e.g., "1" is first, "2" is second, etc.)
** A path to a custom icon file within this rule assets dir
** A KUID for a custom texture asset

;Description
* Called by native code in Surveyor to get an icon to indicate the relationship of a child rule to its parent (this rule). This is for Surveyor display purposes only and provides no rule functionality.
 

==GetSessionProperties==
{{MethodHeader|public [[Class Soup|Soup]] GetSessionProperties(void)}}
;Return value
* [[Class Soup|Soup]] form of rule-data container to be written.

;Description
* Retrieve any data this rule wishes to store in the config.txt of the session, to be made available to script outside of the session (i.e. when it is not running), such as in a menu etc.
 

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

Class ScenarioBehavior

2021-03-26T21:11:51Z

Marekp9: /* SetChildrenLimits */ Corrected display of link to IsCorrectlyConfigured()

*[[TrainzScript Library Reference|API Hierarchy]]
** [[Class GSObject|GSObject]]
*** [[Class GameObject|GameObject]]
**** [[Class TrainzGameObject|TrainzGameObject]]
***** ScenarioBehavior (scenariobehavior.gs)
** [[Class PropertyObject|PropertyObject]]
*** ScenarioBehavior (scenariobehavior.gs)
 

The ScenarioBehavior class is the base class for session rules.
 

==Constants==
*These constants represent flags defining the rule's state. They can be used in combination with [[#GetStateFlags|GetStateFlags()]] and [[#SetStateFlags|SetStateFlags()]] methods.

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NONE = 0||No flags set.
|-
|public define int PAUSED = 1||This behavior is currently paused.
|-
|public define int COMPLETE = 2||This behavior is complete.
|-
|public define int WAS_COMPLETE = 4||This behavior was complete some time previously.
|-
|public define int DOES_COMPLETE = 8||This behavior is capable of reaching a <COMPLETE> state.
|}
 

==Pause==
{{MethodHeader|public void Pause(bool pause)}}
;Parameters
*'''pause''' = Whether the rule is being paused (true) or unpaused (false).

;Description
*Pauses or un-pauses this behavior. This is called either by Trainz native code or the behavior's parent. When called this rule should begin or stop whatever it is configured to do.

;Note
This method in ScenarioBehavior does nothing by itself. The rule inheriting from the ScenarioBehavior must overwrite this method and set/clear the [[#Constants|PAUSED]] flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
 

==SetComplete==
{{MethodHeader|public void SetComplete(bool isComplete)}}
;Parameters
*'''isComplete''' = Whether the rule is complete (true) or not (false).

;Description
*Sets this rule as complete. This should be called on any rule that can reach a state where it is no longer doing anything, once it reaches that state. If this rule executes children, then this should not be called until all children have completed.

;Note
This method sets/clears the [[#Constants|COMPLETE]] flag. If called with 'true' parameter it sets also the [[#Constants|WAS_COMPLETE]] flag.
 

==IsComplete==
{{MethodHeader|public bool IsComplete(void)}}
;Return value
*Returns whether this behavior is currently complete
 

==WasComplete==
{{MethodHeader|public bool WasComplete(void)}}
;Return value
*Returns whether this behavior was ever complete
 

==IsPaused==
{{MethodHeader|public bool IsPaused(void)}}
;Return value
*Returns whether this behavior is paused.
 

==GetStateFlags==
{{MethodHeader|public int GetStateFlags(void)}}
;Return value
*Current state flags for this behavior object.
 

==SetStateFlags==
{{MethodHeader|public void SetStateFlags(int flags, bool set)}}
;Parameters
*'''flags''' = state flags that should be set/cleared
*'''set''' = whether the flags should be set (true) or cleared (false)

;Description
Sets the state of the specified flags for this behavior.
 

==GetProperties==
{{MethodHeader|public mandatory [[Class Soup|Soup]] GetProperties(void)}}
;Return value
*Soup database describing the current state of this rule.

;Description
* Inheriting classes should override this to save all rule state. This includes the Surveyor configuration, and Driver runtime state, as this function is used for saving sessions/profiles, and for savegames.
 

==SetProperties==
{{MethodHeader|public mandatory void SetProperties([[Class Soup|Soup]] soup)}}
;Parameters
*'''soup''' - [[Class Soup|Soup]] database describing the current state of this rule.

;Description
* Configures this rule state using a Soup database created by a previous call to [[#GetProperties|GetProperties()]]. This call should restore all data, start any necessary threads, add handlers, etc. such that the rule can continue execution in whatever state it was previously.
 

==GetRequirements==
{{MethodHeader|public [[Class Requirement|Requirement]][] GetRequirements(void)}}
;Return value
*Resource requirements of this rule.

;Description
* This is called by Trainz native code to determine the product requirements of a behavior (if any) so a waybill listing drop-off/pickup requirements can be displayed to the user.
 

==GetChildBehaviors==
{{MethodHeader|public native ScenarioBehavior[] GetChildBehaviors(void)}}
;Return value
*Child behaviors under this one, i.e. the ones immediately below this one in the Surveyor Rules Editor
 

==AreAllChildrenComplete==
{{MethodHeader|public bool AreAllChildrenComplete()}}
;Return value
* Whether all child rules are complete
 

==GetParentBehavior==
{{MethodHeader|public native ScenarioBehavior GetParentBehavior(void)}}
;Return value
* The parent of this rule in the rules list (i.e., the rule that will/should execute it).
* null for "top level" rules.
 

==Reset==
{{MethodHeader|public void Reset(void)}}
;Description
*Resets the [[#Constants|COMPLETE]] and [[#Constants|WAS_COMPLETE]] flags for this rule.
 

==GetDescription==
{{MethodHeader|public string GetDescription(void)}}
;Return value
* The text describing this rule.

;Description
*Gets a short text description of this session rule, for display in the rules list. This should at least contain a basic overview of what the rule does, but may also reference specific configured objects etc. Basic html markup is supported but do not include images, embedded objects, etc.

;Note
* If not overwritten, then the method returns string with key "description" from the [[Class StringTable|string table]].
 

==AppendDependencies==
{{MethodHeader|public void AppendDependencies([[Class KUIDList|KUIDList]] io_dependencies)}}
;Parameters
*'''io_dependencies''' - ???

;Description
*Gets any asset dependencies that are specific to this rule instance. This method is called by Trainz to determine the asset dependencies of this rule instance, as configured by the player in Surveyor. Inheriting scripts should override this to add assets that the player may configure/select, e.g. html assets, sounds, textures.
 

==GetDebugString==
{{MethodHeader|public string GetDebugString(void)}}
;Return value
* The human-readable string identifying this ScenarioBehavior.

;Description
*Returns a human-readable string identifying this ScenarioBehavior. Used for debugging purposes. The exact contents of this string may vary based on the class of this object and the Trainz version. Do not attempt to machine-parse this value.
 

==SetSessionString==
{{MethodHeader|native void SetSessionString(string tag, string value)}}
;Parameters
*'''tag''' - A unique identifier by which to refer to this string.
*'''value''' - The English value for this string.

;Description
*SURVEYOR ONLY - Creates a localisable string-table entry in the current session asset with the tag and English value passed. This should be used in any situation where a session creator is required to enter player visible text. The KUID for this ScenarioBehaviour will be prepended to the tag when the config.txt is updated. Use the [[#GetSessionString]]() function to retrieve the string for display
 

==GetSessionString==
{{MethodHeader|native string GetSessionString(string tag)}}
;Parameters
*'''tag''' - The unique identifier by which to refer to this string

;Return value
* Session string-table entry created by this asset using the [[#SetSessionString]]() function.
** If present the string for the currently active local will be returned.
** English value will be returned if localised is not present.
** Empty string will be returned if no string with the specified tag exists for this asset.
 

==IsCorrectlyConfigured==
{{MethodHeader|public bool IsCorrectlyConfigured()}}
;Return value
* true if this rule is correctly configured

;Description
* Called by native code in Surveyor to test whether this rule has been correctly configured by the player. If it returns false Surveyor will show a visual indication to the player that the setup needs action.
 

==SetChildrenLimits==
{{MethodHeader|public void SetChildrenLimits(int minChildren, int maxChildren)}}
;Parameters
*'''minChildren''' - The minimum number of children required
*'''maxChildren''' - The maximum number of children allowed, or -1 for no max

;Description
* Sets the limits on the number of children this rule can have. Rules configured in Surveyor with more than the max or less that the minimum will display as incorrectly configured (via [[#IsCorrectlyConfigured|IsCorrectlyConfigured()]]).
 

==GetChildRelationshipIcon==
{{MethodHeader|public string GetChildRelationshipIcon(ScenarioBehavior child)}}
;Parameters
*'''child''' - The child of this rule to get the relationship for

;Return value
*Either:
** "none" - The child is not used by this rule in any way
** "simultaneous" - Rule is a child, and all children are executed simultaneously on completion
** A positive integer, representing the order in which a child rule will be executed by the parent on completion (e.g., "1" is first, "2" is second, etc.)
** A path to a custom icon file within this rule assets dir
** A KUID for a custom texture asset

;Description
* Called by native code in Surveyor to get an icon to indicate the relationship of a child rule to its parent (this rule). This is for Surveyor display purposes only and provides no rule functionality.
 

==GetSessionProperties==
{{MethodHeader|public [[Class Soup|Soup]] GetSessionProperties(void)}}
;Return value
* [[Class Soup|Soup]] form of rule-data container to be written.

;Description
* Retrieve any data this rule wishes to store in the config.txt of the session, to be made available to script outside of the session (i.e. when it is not running), such as in a menu etc.
 

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

Class ScenarioBehavior

2021-03-26T21:10:28Z

Marekp9: /* SetProperties */ Corrected display of link to GetProperties()

*[[TrainzScript Library Reference|API Hierarchy]]
** [[Class GSObject|GSObject]]
*** [[Class GameObject|GameObject]]
**** [[Class TrainzGameObject|TrainzGameObject]]
***** ScenarioBehavior (scenariobehavior.gs)
** [[Class PropertyObject|PropertyObject]]
*** ScenarioBehavior (scenariobehavior.gs)
 

The ScenarioBehavior class is the base class for session rules.
 

==Constants==
*These constants represent flags defining the rule's state. They can be used in combination with [[#GetStateFlags|GetStateFlags()]] and [[#SetStateFlags|SetStateFlags()]] methods.

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NONE = 0||No flags set.
|-
|public define int PAUSED = 1||This behavior is currently paused.
|-
|public define int COMPLETE = 2||This behavior is complete.
|-
|public define int WAS_COMPLETE = 4||This behavior was complete some time previously.
|-
|public define int DOES_COMPLETE = 8||This behavior is capable of reaching a <COMPLETE> state.
|}
 

==Pause==
{{MethodHeader|public void Pause(bool pause)}}
;Parameters
*'''pause''' = Whether the rule is being paused (true) or unpaused (false).

;Description
*Pauses or un-pauses this behavior. This is called either by Trainz native code or the behavior's parent. When called this rule should begin or stop whatever it is configured to do.

;Note
This method in ScenarioBehavior does nothing by itself. The rule inheriting from the ScenarioBehavior must overwrite this method and set/clear the [[#Constants|PAUSED]] flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
 

==SetComplete==
{{MethodHeader|public void SetComplete(bool isComplete)}}
;Parameters
*'''isComplete''' = Whether the rule is complete (true) or not (false).

;Description
*Sets this rule as complete. This should be called on any rule that can reach a state where it is no longer doing anything, once it reaches that state. If this rule executes children, then this should not be called until all children have completed.

;Note
This method sets/clears the [[#Constants|COMPLETE]] flag. If called with 'true' parameter it sets also the [[#Constants|WAS_COMPLETE]] flag.
 

==IsComplete==
{{MethodHeader|public bool IsComplete(void)}}
;Return value
*Returns whether this behavior is currently complete
 

==WasComplete==
{{MethodHeader|public bool WasComplete(void)}}
;Return value
*Returns whether this behavior was ever complete
 

==IsPaused==
{{MethodHeader|public bool IsPaused(void)}}
;Return value
*Returns whether this behavior is paused.
 

==GetStateFlags==
{{MethodHeader|public int GetStateFlags(void)}}
;Return value
*Current state flags for this behavior object.
 

==SetStateFlags==
{{MethodHeader|public void SetStateFlags(int flags, bool set)}}
;Parameters
*'''flags''' = state flags that should be set/cleared
*'''set''' = whether the flags should be set (true) or cleared (false)

;Description
Sets the state of the specified flags for this behavior.
 

==GetProperties==
{{MethodHeader|public mandatory [[Class Soup|Soup]] GetProperties(void)}}
;Return value
*Soup database describing the current state of this rule.

;Description
* Inheriting classes should override this to save all rule state. This includes the Surveyor configuration, and Driver runtime state, as this function is used for saving sessions/profiles, and for savegames.
 

==SetProperties==
{{MethodHeader|public mandatory void SetProperties([[Class Soup|Soup]] soup)}}
;Parameters
*'''soup''' - [[Class Soup|Soup]] database describing the current state of this rule.

;Description
* Configures this rule state using a Soup database created by a previous call to [[#GetProperties|GetProperties()]]. This call should restore all data, start any necessary threads, add handlers, etc. such that the rule can continue execution in whatever state it was previously.
 

==GetRequirements==
{{MethodHeader|public [[Class Requirement|Requirement]][] GetRequirements(void)}}
;Return value
*Resource requirements of this rule.

;Description
* This is called by Trainz native code to determine the product requirements of a behavior (if any) so a waybill listing drop-off/pickup requirements can be displayed to the user.
 

==GetChildBehaviors==
{{MethodHeader|public native ScenarioBehavior[] GetChildBehaviors(void)}}
;Return value
*Child behaviors under this one, i.e. the ones immediately below this one in the Surveyor Rules Editor
 

==AreAllChildrenComplete==
{{MethodHeader|public bool AreAllChildrenComplete()}}
;Return value
* Whether all child rules are complete
 

==GetParentBehavior==
{{MethodHeader|public native ScenarioBehavior GetParentBehavior(void)}}
;Return value
* The parent of this rule in the rules list (i.e., the rule that will/should execute it).
* null for "top level" rules.
 

==Reset==
{{MethodHeader|public void Reset(void)}}
;Description
*Resets the [[#Constants|COMPLETE]] and [[#Constants|WAS_COMPLETE]] flags for this rule.
 

==GetDescription==
{{MethodHeader|public string GetDescription(void)}}
;Return value
* The text describing this rule.

;Description
*Gets a short text description of this session rule, for display in the rules list. This should at least contain a basic overview of what the rule does, but may also reference specific configured objects etc. Basic html markup is supported but do not include images, embedded objects, etc.

;Note
* If not overwritten, then the method returns string with key "description" from the [[Class StringTable|string table]].
 

==AppendDependencies==
{{MethodHeader|public void AppendDependencies([[Class KUIDList|KUIDList]] io_dependencies)}}
;Parameters
*'''io_dependencies''' - ???

;Description
*Gets any asset dependencies that are specific to this rule instance. This method is called by Trainz to determine the asset dependencies of this rule instance, as configured by the player in Surveyor. Inheriting scripts should override this to add assets that the player may configure/select, e.g. html assets, sounds, textures.
 

==GetDebugString==
{{MethodHeader|public string GetDebugString(void)}}
;Return value
* The human-readable string identifying this ScenarioBehavior.

;Description
*Returns a human-readable string identifying this ScenarioBehavior. Used for debugging purposes. The exact contents of this string may vary based on the class of this object and the Trainz version. Do not attempt to machine-parse this value.
 

==SetSessionString==
{{MethodHeader|native void SetSessionString(string tag, string value)}}
;Parameters
*'''tag''' - A unique identifier by which to refer to this string.
*'''value''' - The English value for this string.

;Description
*SURVEYOR ONLY - Creates a localisable string-table entry in the current session asset with the tag and English value passed. This should be used in any situation where a session creator is required to enter player visible text. The KUID for this ScenarioBehaviour will be prepended to the tag when the config.txt is updated. Use the [[#GetSessionString]]() function to retrieve the string for display
 

==GetSessionString==
{{MethodHeader|native string GetSessionString(string tag)}}
;Parameters
*'''tag''' - The unique identifier by which to refer to this string

;Return value
* Session string-table entry created by this asset using the [[#SetSessionString]]() function.
** If present the string for the currently active local will be returned.
** English value will be returned if localised is not present.
** Empty string will be returned if no string with the specified tag exists for this asset.
 

==IsCorrectlyConfigured==
{{MethodHeader|public bool IsCorrectlyConfigured()}}
;Return value
* true if this rule is correctly configured

;Description
* Called by native code in Surveyor to test whether this rule has been correctly configured by the player. If it returns false Surveyor will show a visual indication to the player that the setup needs action.
 

==SetChildrenLimits==
{{MethodHeader|public void SetChildrenLimits(int minChildren, int maxChildren)}}
;Parameters
*'''minChildren''' - The minimum number of children required
*'''maxChildren''' - The maximum number of children allowed, or -1 for no max

;Description
* Sets the limits on the number of children this rule can have. Rules configured in Surveyor with more than the max or less that the minimum will display as incorrectly configured (via [[#IsCorrectlyConfigured]]()).
 

==GetChildRelationshipIcon==
{{MethodHeader|public string GetChildRelationshipIcon(ScenarioBehavior child)}}
;Parameters
*'''child''' - The child of this rule to get the relationship for

;Return value
*Either:
** "none" - The child is not used by this rule in any way
** "simultaneous" - Rule is a child, and all children are executed simultaneously on completion
** A positive integer, representing the order in which a child rule will be executed by the parent on completion (e.g., "1" is first, "2" is second, etc.)
** A path to a custom icon file within this rule assets dir
** A KUID for a custom texture asset

;Description
* Called by native code in Surveyor to get an icon to indicate the relationship of a child rule to its parent (this rule). This is for Surveyor display purposes only and provides no rule functionality.
 

==GetSessionProperties==
{{MethodHeader|public [[Class Soup|Soup]] GetSessionProperties(void)}}
;Return value
* [[Class Soup|Soup]] form of rule-data container to be written.

;Description
* Retrieve any data this rule wishes to store in the config.txt of the session, to be made available to script outside of the session (i.e. when it is not running), such as in a menu etc.
 

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

Class ScenarioBehavior

2021-03-26T21:09:19Z

Marekp9: /* Constants */ Adjustments to the display of GetStateFlags() and SetStateFlags()

*[[TrainzScript Library Reference|API Hierarchy]]
** [[Class GSObject|GSObject]]
*** [[Class GameObject|GameObject]]
**** [[Class TrainzGameObject|TrainzGameObject]]
***** ScenarioBehavior (scenariobehavior.gs)
** [[Class PropertyObject|PropertyObject]]
*** ScenarioBehavior (scenariobehavior.gs)
 

The ScenarioBehavior class is the base class for session rules.
 

==Constants==
*These constants represent flags defining the rule's state. They can be used in combination with [[#GetStateFlags|GetStateFlags()]] and [[#SetStateFlags|SetStateFlags()]] methods.

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NONE = 0||No flags set.
|-
|public define int PAUSED = 1||This behavior is currently paused.
|-
|public define int COMPLETE = 2||This behavior is complete.
|-
|public define int WAS_COMPLETE = 4||This behavior was complete some time previously.
|-
|public define int DOES_COMPLETE = 8||This behavior is capable of reaching a <COMPLETE> state.
|}
 

==Pause==
{{MethodHeader|public void Pause(bool pause)}}
;Parameters
*'''pause''' = Whether the rule is being paused (true) or unpaused (false).

;Description
*Pauses or un-pauses this behavior. This is called either by Trainz native code or the behavior's parent. When called this rule should begin or stop whatever it is configured to do.

;Note
This method in ScenarioBehavior does nothing by itself. The rule inheriting from the ScenarioBehavior must overwrite this method and set/clear the [[#Constants|PAUSED]] flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
 

==SetComplete==
{{MethodHeader|public void SetComplete(bool isComplete)}}
;Parameters
*'''isComplete''' = Whether the rule is complete (true) or not (false).

;Description
*Sets this rule as complete. This should be called on any rule that can reach a state where it is no longer doing anything, once it reaches that state. If this rule executes children, then this should not be called until all children have completed.

;Note
This method sets/clears the [[#Constants|COMPLETE]] flag. If called with 'true' parameter it sets also the [[#Constants|WAS_COMPLETE]] flag.
 

==IsComplete==
{{MethodHeader|public bool IsComplete(void)}}
;Return value
*Returns whether this behavior is currently complete
 

==WasComplete==
{{MethodHeader|public bool WasComplete(void)}}
;Return value
*Returns whether this behavior was ever complete
 

==IsPaused==
{{MethodHeader|public bool IsPaused(void)}}
;Return value
*Returns whether this behavior is paused.
 

==GetStateFlags==
{{MethodHeader|public int GetStateFlags(void)}}
;Return value
*Current state flags for this behavior object.
 

==SetStateFlags==
{{MethodHeader|public void SetStateFlags(int flags, bool set)}}
;Parameters
*'''flags''' = state flags that should be set/cleared
*'''set''' = whether the flags should be set (true) or cleared (false)

;Description
Sets the state of the specified flags for this behavior.
 

==GetProperties==
{{MethodHeader|public mandatory [[Class Soup|Soup]] GetProperties(void)}}
;Return value
*Soup database describing the current state of this rule.

;Description
* Inheriting classes should override this to save all rule state. This includes the Surveyor configuration, and Driver runtime state, as this function is used for saving sessions/profiles, and for savegames.
 

==SetProperties==
{{MethodHeader|public mandatory void SetProperties([[Class Soup|Soup]] soup)}}
;Parameters
*'''soup''' - [[Class Soup|Soup]] database describing the current state of this rule.

;Description
* Configures this rule state using a Soup database created by a previous call to [[#GetProperties]]. This call should restore all data, start any necessary threads, add handlers, etc. such that the rule can continue execution in whatever state it was previously.
 

==GetRequirements==
{{MethodHeader|public [[Class Requirement|Requirement]][] GetRequirements(void)}}
;Return value
*Resource requirements of this rule.

;Description
* This is called by Trainz native code to determine the product requirements of a behavior (if any) so a waybill listing drop-off/pickup requirements can be displayed to the user.
 

==GetChildBehaviors==
{{MethodHeader|public native ScenarioBehavior[] GetChildBehaviors(void)}}
;Return value
*Child behaviors under this one, i.e. the ones immediately below this one in the Surveyor Rules Editor
 

==AreAllChildrenComplete==
{{MethodHeader|public bool AreAllChildrenComplete()}}
;Return value
* Whether all child rules are complete
 

==GetParentBehavior==
{{MethodHeader|public native ScenarioBehavior GetParentBehavior(void)}}
;Return value
* The parent of this rule in the rules list (i.e., the rule that will/should execute it).
* null for "top level" rules.
 

==Reset==
{{MethodHeader|public void Reset(void)}}
;Description
*Resets the [[#Constants|COMPLETE]] and [[#Constants|WAS_COMPLETE]] flags for this rule.
 

==GetDescription==
{{MethodHeader|public string GetDescription(void)}}
;Return value
* The text describing this rule.

;Description
*Gets a short text description of this session rule, for display in the rules list. This should at least contain a basic overview of what the rule does, but may also reference specific configured objects etc. Basic html markup is supported but do not include images, embedded objects, etc.

;Note
* If not overwritten, then the method returns string with key "description" from the [[Class StringTable|string table]].
 

==AppendDependencies==
{{MethodHeader|public void AppendDependencies([[Class KUIDList|KUIDList]] io_dependencies)}}
;Parameters
*'''io_dependencies''' - ???

;Description
*Gets any asset dependencies that are specific to this rule instance. This method is called by Trainz to determine the asset dependencies of this rule instance, as configured by the player in Surveyor. Inheriting scripts should override this to add assets that the player may configure/select, e.g. html assets, sounds, textures.
 

==GetDebugString==
{{MethodHeader|public string GetDebugString(void)}}
;Return value
* The human-readable string identifying this ScenarioBehavior.

;Description
*Returns a human-readable string identifying this ScenarioBehavior. Used for debugging purposes. The exact contents of this string may vary based on the class of this object and the Trainz version. Do not attempt to machine-parse this value.
 

==SetSessionString==
{{MethodHeader|native void SetSessionString(string tag, string value)}}
;Parameters
*'''tag''' - A unique identifier by which to refer to this string.
*'''value''' - The English value for this string.

;Description
*SURVEYOR ONLY - Creates a localisable string-table entry in the current session asset with the tag and English value passed. This should be used in any situation where a session creator is required to enter player visible text. The KUID for this ScenarioBehaviour will be prepended to the tag when the config.txt is updated. Use the [[#GetSessionString]]() function to retrieve the string for display
 

==GetSessionString==
{{MethodHeader|native string GetSessionString(string tag)}}
;Parameters
*'''tag''' - The unique identifier by which to refer to this string

;Return value
* Session string-table entry created by this asset using the [[#SetSessionString]]() function.
** If present the string for the currently active local will be returned.
** English value will be returned if localised is not present.
** Empty string will be returned if no string with the specified tag exists for this asset.
 

==IsCorrectlyConfigured==
{{MethodHeader|public bool IsCorrectlyConfigured()}}
;Return value
* true if this rule is correctly configured

;Description
* Called by native code in Surveyor to test whether this rule has been correctly configured by the player. If it returns false Surveyor will show a visual indication to the player that the setup needs action.
 

==SetChildrenLimits==
{{MethodHeader|public void SetChildrenLimits(int minChildren, int maxChildren)}}
;Parameters
*'''minChildren''' - The minimum number of children required
*'''maxChildren''' - The maximum number of children allowed, or -1 for no max

;Description
* Sets the limits on the number of children this rule can have. Rules configured in Surveyor with more than the max or less that the minimum will display as incorrectly configured (via [[#IsCorrectlyConfigured]]()).
 

==GetChildRelationshipIcon==
{{MethodHeader|public string GetChildRelationshipIcon(ScenarioBehavior child)}}
;Parameters
*'''child''' - The child of this rule to get the relationship for

;Return value
*Either:
** "none" - The child is not used by this rule in any way
** "simultaneous" - Rule is a child, and all children are executed simultaneously on completion
** A positive integer, representing the order in which a child rule will be executed by the parent on completion (e.g., "1" is first, "2" is second, etc.)
** A path to a custom icon file within this rule assets dir
** A KUID for a custom texture asset

;Description
* Called by native code in Surveyor to get an icon to indicate the relationship of a child rule to its parent (this rule). This is for Surveyor display purposes only and provides no rule functionality.
 

==GetSessionProperties==
{{MethodHeader|public [[Class Soup|Soup]] GetSessionProperties(void)}}
;Return value
* [[Class Soup|Soup]] form of rule-data container to be written.

;Description
* Retrieve any data this rule wishes to store in the config.txt of the session, to be made available to script outside of the session (i.e. when it is not running), such as in a menu etc.
 

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

Class ScenarioBehavior

2021-03-26T21:07:38Z

Marekp9: /* Constants */ Fixed links to GetStateFlags and SetStateFlags

*[[TrainzScript Library Reference|API Hierarchy]]
** [[Class GSObject|GSObject]]
*** [[Class GameObject|GameObject]]
**** [[Class TrainzGameObject|TrainzGameObject]]
***** ScenarioBehavior (scenariobehavior.gs)
** [[Class PropertyObject|PropertyObject]]
*** ScenarioBehavior (scenariobehavior.gs)
 

The ScenarioBehavior class is the base class for session rules.
 

==Constants==
*These constants represent flags defining the rule's state. They can be used in combination with [[#GetStateFlags]]() and [[#SetStateFlags]]() methods.

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NONE = 0||No flags set.
|-
|public define int PAUSED = 1||This behavior is currently paused.
|-
|public define int COMPLETE = 2||This behavior is complete.
|-
|public define int WAS_COMPLETE = 4||This behavior was complete some time previously.
|-
|public define int DOES_COMPLETE = 8||This behavior is capable of reaching a <COMPLETE> state.
|}
 

==Pause==
{{MethodHeader|public void Pause(bool pause)}}
;Parameters
*'''pause''' = Whether the rule is being paused (true) or unpaused (false).

;Description
*Pauses or un-pauses this behavior. This is called either by Trainz native code or the behavior's parent. When called this rule should begin or stop whatever it is configured to do.

;Note
This method in ScenarioBehavior does nothing by itself. The rule inheriting from the ScenarioBehavior must overwrite this method and set/clear the [[#Constants|PAUSED]] flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
 

==SetComplete==
{{MethodHeader|public void SetComplete(bool isComplete)}}
;Parameters
*'''isComplete''' = Whether the rule is complete (true) or not (false).

;Description
*Sets this rule as complete. This should be called on any rule that can reach a state where it is no longer doing anything, once it reaches that state. If this rule executes children, then this should not be called until all children have completed.

;Note
This method sets/clears the [[#Constants|COMPLETE]] flag. If called with 'true' parameter it sets also the [[#Constants|WAS_COMPLETE]] flag.
 

==IsComplete==
{{MethodHeader|public bool IsComplete(void)}}
;Return value
*Returns whether this behavior is currently complete
 

==WasComplete==
{{MethodHeader|public bool WasComplete(void)}}
;Return value
*Returns whether this behavior was ever complete
 

==IsPaused==
{{MethodHeader|public bool IsPaused(void)}}
;Return value
*Returns whether this behavior is paused.
 

==GetStateFlags==
{{MethodHeader|public int GetStateFlags(void)}}
;Return value
*Current state flags for this behavior object.
 

==SetStateFlags==
{{MethodHeader|public void SetStateFlags(int flags, bool set)}}
;Parameters
*'''flags''' = state flags that should be set/cleared
*'''set''' = whether the flags should be set (true) or cleared (false)

;Description
Sets the state of the specified flags for this behavior.
 

==GetProperties==
{{MethodHeader|public mandatory [[Class Soup|Soup]] GetProperties(void)}}
;Return value
*Soup database describing the current state of this rule.

;Description
* Inheriting classes should override this to save all rule state. This includes the Surveyor configuration, and Driver runtime state, as this function is used for saving sessions/profiles, and for savegames.
 

==SetProperties==
{{MethodHeader|public mandatory void SetProperties([[Class Soup|Soup]] soup)}}
;Parameters
*'''soup''' - [[Class Soup|Soup]] database describing the current state of this rule.

;Description
* Configures this rule state using a Soup database created by a previous call to [[#GetProperties]]. This call should restore all data, start any necessary threads, add handlers, etc. such that the rule can continue execution in whatever state it was previously.
 

==GetRequirements==
{{MethodHeader|public [[Class Requirement|Requirement]][] GetRequirements(void)}}
;Return value
*Resource requirements of this rule.

;Description
* This is called by Trainz native code to determine the product requirements of a behavior (if any) so a waybill listing drop-off/pickup requirements can be displayed to the user.
 

==GetChildBehaviors==
{{MethodHeader|public native ScenarioBehavior[] GetChildBehaviors(void)}}
;Return value
*Child behaviors under this one, i.e. the ones immediately below this one in the Surveyor Rules Editor
 

==AreAllChildrenComplete==
{{MethodHeader|public bool AreAllChildrenComplete()}}
;Return value
* Whether all child rules are complete
 

==GetParentBehavior==
{{MethodHeader|public native ScenarioBehavior GetParentBehavior(void)}}
;Return value
* The parent of this rule in the rules list (i.e., the rule that will/should execute it).
* null for "top level" rules.
 

==Reset==
{{MethodHeader|public void Reset(void)}}
;Description
*Resets the [[#Constants|COMPLETE]] and [[#Constants|WAS_COMPLETE]] flags for this rule.
 

==GetDescription==
{{MethodHeader|public string GetDescription(void)}}
;Return value
* The text describing this rule.

;Description
*Gets a short text description of this session rule, for display in the rules list. This should at least contain a basic overview of what the rule does, but may also reference specific configured objects etc. Basic html markup is supported but do not include images, embedded objects, etc.

;Note
* If not overwritten, then the method returns string with key "description" from the [[Class StringTable|string table]].
 

==AppendDependencies==
{{MethodHeader|public void AppendDependencies([[Class KUIDList|KUIDList]] io_dependencies)}}
;Parameters
*'''io_dependencies''' - ???

;Description
*Gets any asset dependencies that are specific to this rule instance. This method is called by Trainz to determine the asset dependencies of this rule instance, as configured by the player in Surveyor. Inheriting scripts should override this to add assets that the player may configure/select, e.g. html assets, sounds, textures.
 

==GetDebugString==
{{MethodHeader|public string GetDebugString(void)}}
;Return value
* The human-readable string identifying this ScenarioBehavior.

;Description
*Returns a human-readable string identifying this ScenarioBehavior. Used for debugging purposes. The exact contents of this string may vary based on the class of this object and the Trainz version. Do not attempt to machine-parse this value.
 

==SetSessionString==
{{MethodHeader|native void SetSessionString(string tag, string value)}}
;Parameters
*'''tag''' - A unique identifier by which to refer to this string.
*'''value''' - The English value for this string.

;Description
*SURVEYOR ONLY - Creates a localisable string-table entry in the current session asset with the tag and English value passed. This should be used in any situation where a session creator is required to enter player visible text. The KUID for this ScenarioBehaviour will be prepended to the tag when the config.txt is updated. Use the [[#GetSessionString]]() function to retrieve the string for display
 

==GetSessionString==
{{MethodHeader|native string GetSessionString(string tag)}}
;Parameters
*'''tag''' - The unique identifier by which to refer to this string

;Return value
* Session string-table entry created by this asset using the [[#SetSessionString]]() function.
** If present the string for the currently active local will be returned.
** English value will be returned if localised is not present.
** Empty string will be returned if no string with the specified tag exists for this asset.
 

==IsCorrectlyConfigured==
{{MethodHeader|public bool IsCorrectlyConfigured()}}
;Return value
* true if this rule is correctly configured

;Description
* Called by native code in Surveyor to test whether this rule has been correctly configured by the player. If it returns false Surveyor will show a visual indication to the player that the setup needs action.
 

==SetChildrenLimits==
{{MethodHeader|public void SetChildrenLimits(int minChildren, int maxChildren)}}
;Parameters
*'''minChildren''' - The minimum number of children required
*'''maxChildren''' - The maximum number of children allowed, or -1 for no max

;Description
* Sets the limits on the number of children this rule can have. Rules configured in Surveyor with more than the max or less that the minimum will display as incorrectly configured (via [[#IsCorrectlyConfigured]]()).
 

==GetChildRelationshipIcon==
{{MethodHeader|public string GetChildRelationshipIcon(ScenarioBehavior child)}}
;Parameters
*'''child''' - The child of this rule to get the relationship for

;Return value
*Either:
** "none" - The child is not used by this rule in any way
** "simultaneous" - Rule is a child, and all children are executed simultaneously on completion
** A positive integer, representing the order in which a child rule will be executed by the parent on completion (e.g., "1" is first, "2" is second, etc.)
** A path to a custom icon file within this rule assets dir
** A KUID for a custom texture asset

;Description
* Called by native code in Surveyor to get an icon to indicate the relationship of a child rule to its parent (this rule). This is for Surveyor display purposes only and provides no rule functionality.
 

==GetSessionProperties==
{{MethodHeader|public [[Class Soup|Soup]] GetSessionProperties(void)}}
;Return value
* [[Class Soup|Soup]] form of rule-data container to be written.

;Description
* Retrieve any data this rule wishes to store in the config.txt of the session, to be made available to script outside of the session (i.e. when it is not running), such as in a menu etc.
 

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

Class ScenarioBehavior

2021-03-26T21:06:17Z

Marekp9: Page created

*[[TrainzScript Library Reference|API Hierarchy]]
** [[Class GSObject|GSObject]]
*** [[Class GameObject|GameObject]]
**** [[Class TrainzGameObject|TrainzGameObject]]
***** ScenarioBehavior (scenariobehavior.gs)
** [[Class PropertyObject|PropertyObject]]
*** ScenarioBehavior (scenariobehavior.gs)
 

The ScenarioBehavior class is the base class for session rules.
 

==Constants==
*These constants represent flags defining the rule's state. They can be used in combination with [[GetStateFlags]]() and [[SetStateFlags]]() methods.

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NONE = 0||No flags set.
|-
|public define int PAUSED = 1||This behavior is currently paused.
|-
|public define int COMPLETE = 2||This behavior is complete.
|-
|public define int WAS_COMPLETE = 4||This behavior was complete some time previously.
|-
|public define int DOES_COMPLETE = 8||This behavior is capable of reaching a <COMPLETE> state.
|}
 

==Pause==
{{MethodHeader|public void Pause(bool pause)}}
;Parameters
*'''pause''' = Whether the rule is being paused (true) or unpaused (false).

;Description
*Pauses or un-pauses this behavior. This is called either by Trainz native code or the behavior's parent. When called this rule should begin or stop whatever it is configured to do.

;Note
This method in ScenarioBehavior does nothing by itself. The rule inheriting from the ScenarioBehavior must overwrite this method and set/clear the [[#Constants|PAUSED]] flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
 

==SetComplete==
{{MethodHeader|public void SetComplete(bool isComplete)}}
;Parameters
*'''isComplete''' = Whether the rule is complete (true) or not (false).

;Description
*Sets this rule as complete. This should be called on any rule that can reach a state where it is no longer doing anything, once it reaches that state. If this rule executes children, then this should not be called until all children have completed.

;Note
This method sets/clears the [[#Constants|COMPLETE]] flag. If called with 'true' parameter it sets also the [[#Constants|WAS_COMPLETE]] flag.
 

==IsComplete==
{{MethodHeader|public bool IsComplete(void)}}
;Return value
*Returns whether this behavior is currently complete
 

==WasComplete==
{{MethodHeader|public bool WasComplete(void)}}
;Return value
*Returns whether this behavior was ever complete
 

==IsPaused==
{{MethodHeader|public bool IsPaused(void)}}
;Return value
*Returns whether this behavior is paused.
 

==GetStateFlags==
{{MethodHeader|public int GetStateFlags(void)}}
;Return value
*Current state flags for this behavior object.
 

==SetStateFlags==
{{MethodHeader|public void SetStateFlags(int flags, bool set)}}
;Parameters
*'''flags''' = state flags that should be set/cleared
*'''set''' = whether the flags should be set (true) or cleared (false)

;Description
Sets the state of the specified flags for this behavior.
 

==GetProperties==
{{MethodHeader|public mandatory [[Class Soup|Soup]] GetProperties(void)}}
;Return value
*Soup database describing the current state of this rule.

;Description
* Inheriting classes should override this to save all rule state. This includes the Surveyor configuration, and Driver runtime state, as this function is used for saving sessions/profiles, and for savegames.
 

==SetProperties==
{{MethodHeader|public mandatory void SetProperties([[Class Soup|Soup]] soup)}}
;Parameters
*'''soup''' - [[Class Soup|Soup]] database describing the current state of this rule.

;Description
* Configures this rule state using a Soup database created by a previous call to [[#GetProperties]]. This call should restore all data, start any necessary threads, add handlers, etc. such that the rule can continue execution in whatever state it was previously.
 

==GetRequirements==
{{MethodHeader|public [[Class Requirement|Requirement]][] GetRequirements(void)}}
;Return value
*Resource requirements of this rule.

;Description
* This is called by Trainz native code to determine the product requirements of a behavior (if any) so a waybill listing drop-off/pickup requirements can be displayed to the user.
 

==GetChildBehaviors==
{{MethodHeader|public native ScenarioBehavior[] GetChildBehaviors(void)}}
;Return value
*Child behaviors under this one, i.e. the ones immediately below this one in the Surveyor Rules Editor
 

==AreAllChildrenComplete==
{{MethodHeader|public bool AreAllChildrenComplete()}}
;Return value
* Whether all child rules are complete
 

==GetParentBehavior==
{{MethodHeader|public native ScenarioBehavior GetParentBehavior(void)}}
;Return value
* The parent of this rule in the rules list (i.e., the rule that will/should execute it).
* null for "top level" rules.
 

==Reset==
{{MethodHeader|public void Reset(void)}}
;Description
*Resets the [[#Constants|COMPLETE]] and [[#Constants|WAS_COMPLETE]] flags for this rule.
 

==GetDescription==
{{MethodHeader|public string GetDescription(void)}}
;Return value
* The text describing this rule.

;Description
*Gets a short text description of this session rule, for display in the rules list. This should at least contain a basic overview of what the rule does, but may also reference specific configured objects etc. Basic html markup is supported but do not include images, embedded objects, etc.

;Note
* If not overwritten, then the method returns string with key "description" from the [[Class StringTable|string table]].
 

==AppendDependencies==
{{MethodHeader|public void AppendDependencies([[Class KUIDList|KUIDList]] io_dependencies)}}
;Parameters
*'''io_dependencies''' - ???

;Description
*Gets any asset dependencies that are specific to this rule instance. This method is called by Trainz to determine the asset dependencies of this rule instance, as configured by the player in Surveyor. Inheriting scripts should override this to add assets that the player may configure/select, e.g. html assets, sounds, textures.
 

==GetDebugString==
{{MethodHeader|public string GetDebugString(void)}}
;Return value
* The human-readable string identifying this ScenarioBehavior.

;Description
*Returns a human-readable string identifying this ScenarioBehavior. Used for debugging purposes. The exact contents of this string may vary based on the class of this object and the Trainz version. Do not attempt to machine-parse this value.
 

==SetSessionString==
{{MethodHeader|native void SetSessionString(string tag, string value)}}
;Parameters
*'''tag''' - A unique identifier by which to refer to this string.
*'''value''' - The English value for this string.

;Description
*SURVEYOR ONLY - Creates a localisable string-table entry in the current session asset with the tag and English value passed. This should be used in any situation where a session creator is required to enter player visible text. The KUID for this ScenarioBehaviour will be prepended to the tag when the config.txt is updated. Use the [[#GetSessionString]]() function to retrieve the string for display
 

==GetSessionString==
{{MethodHeader|native string GetSessionString(string tag)}}
;Parameters
*'''tag''' - The unique identifier by which to refer to this string

;Return value
* Session string-table entry created by this asset using the [[#SetSessionString]]() function.
** If present the string for the currently active local will be returned.
** English value will be returned if localised is not present.
** Empty string will be returned if no string with the specified tag exists for this asset.
 

==IsCorrectlyConfigured==
{{MethodHeader|public bool IsCorrectlyConfigured()}}
;Return value
* true if this rule is correctly configured

;Description
* Called by native code in Surveyor to test whether this rule has been correctly configured by the player. If it returns false Surveyor will show a visual indication to the player that the setup needs action.
 

==SetChildrenLimits==
{{MethodHeader|public void SetChildrenLimits(int minChildren, int maxChildren)}}
;Parameters
*'''minChildren''' - The minimum number of children required
*'''maxChildren''' - The maximum number of children allowed, or -1 for no max

;Description
* Sets the limits on the number of children this rule can have. Rules configured in Surveyor with more than the max or less that the minimum will display as incorrectly configured (via [[#IsCorrectlyConfigured]]()).
 

==GetChildRelationshipIcon==
{{MethodHeader|public string GetChildRelationshipIcon(ScenarioBehavior child)}}
;Parameters
*'''child''' - The child of this rule to get the relationship for

;Return value
*Either:
** "none" - The child is not used by this rule in any way
** "simultaneous" - Rule is a child, and all children are executed simultaneously on completion
** A positive integer, representing the order in which a child rule will be executed by the parent on completion (e.g., "1" is first, "2" is second, etc.)
** A path to a custom icon file within this rule assets dir
** A KUID for a custom texture asset

;Description
* Called by native code in Surveyor to get an icon to indicate the relationship of a child rule to its parent (this rule). This is for Surveyor display purposes only and provides no rule functionality.
 

==GetSessionProperties==
{{MethodHeader|public [[Class Soup|Soup]] GetSessionProperties(void)}}
;Return value
* [[Class Soup|Soup]] form of rule-data container to be written.

;Description
* Retrieve any data this rule wishes to store in the config.txt of the session, to be made available to script outside of the session (i.e. when it is not running), such as in a menu etc.
 

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

Class World

2021-03-26T18:46:05Z

Marekp9: /* SetGameDate */ Corrected Time to Date

*[[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 SetGameDate(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.SetGameDate(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]]