Class ScenarioBehavior
- API Hierarchy
- GSObject
- GameObject
- TrainzGameObject
- ScenarioBehavior (scenariobehavior.gs)
- TrainzGameObject
- GameObject
- PropertyObject
- ScenarioBehavior (scenariobehavior.gs)
- GSObject
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.
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).
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
- 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 PAUSED flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
SetComplete
- 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 COMPLETE flag. If called with 'true' parameter it sets also the WAS_COMPLETE flag.
IsComplete
- Return value
- Returns whether this behavior is currently complete
WasComplete
- Return value
- Returns whether this behavior was ever complete
IsPaused
- Return value
- Returns whether this behavior is paused.
GetStateFlags
- Return value
- Current state flags for this behavior object.
SetStateFlags
- 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
- 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
- Parameters
- 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
- 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
- Return value
- Child behaviors under this one, i.e. the ones immediately below this one in the Surveyor Rules Editor
AreAllChildrenComplete
- Return value
- Whether all child rules are complete
GetParentBehavior
- 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
- Description
- Resets the COMPLETE and WAS_COMPLETE flags for this rule.
GetDescription
- 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 string table.
AppendDependencies
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- Return value
- 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.