Class ScenarioBehavior
From TrainzOnline
(Difference between revisions)
m (→Constants: Fixed links to GetStateFlags and SetStateFlags) |
m (→SetStateFlags: Flags not specified by the parameter keep their old value.) |
||
| (7 intermediate revisions by one user not shown) | |||
| Line 12: | Line 12: | ||
==Constants== | ==Constants== | ||
| − | + | These constants represent flags defining the rule's state. They can be used in combination with [[#GetStateFlags|GetStateFlags()]] and [[#SetStateFlags|SetStateFlags()]] methods.<br> | |
| + | 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}} | {{TableHeader|width=95%|margin=15px}} | ||
| − | |width= | + | |width=300|public define int '''NONE''' = 0||No flags set. |
|- | |- | ||
| − | |public define int PAUSED = 1||This behavior is currently paused. | + | |public define int '''PAUSED''' = 1||This behavior is currently paused. |
|- | |- | ||
| − | |public define int COMPLETE = 2||This behavior is complete. | + | |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 '''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. | + | |public define int '''DOES_COMPLETE''' = 8||This behavior is capable of reaching a <COMPLETE> state.<br>(Distinguishes rules that can complete their execution from infinitely continuous rules.) |
|} | |} | ||
<br> | <br> | ||
| + | |||
| + | The initial state of the ScenarioBehavior is PAUSED.<br> | ||
| + | The inheriting class needs to set the DOES_COMPLETE flag by itself if it wants to mark itself as not continuous rule. | ||
==Pause== | ==Pause== | ||
| Line 36: | Line 40: | ||
;Note | ;Note | ||
| − | This method in ScenarioBehavior does nothing by itself. The rule inheriting from the ScenarioBehavior must | + | 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. |
<br> | <br> | ||
| Line 82: | Line 86: | ||
;Description | ;Description | ||
| − | Sets the state of the specified flags for this behavior. | + | Sets the state of the specified flags for this behavior.<br> |
| + | The method changes value only of the flags specified in the 'flags' parameter. All other flags will keep their old value. | ||
<br> | <br> | ||
| Line 100: | Line 105: | ||
;Description | ;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. | + | * 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. |
<br> | <br> | ||
| Line 146: | Line 151: | ||
;Note | ;Note | ||
| − | * If not | + | * If not overridden, then the method returns string with key "description" from the [[Class StringTable|string table]]. |
<br> | <br> | ||
| Line 174: | Line 179: | ||
;Description | ;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 | + | *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 |
<br> | <br> | ||
| Line 183: | Line 188: | ||
;Return value | ;Return value | ||
| − | * Session string-table entry created by this asset using the [[#SetSessionString | + | * 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. | ** If present the string for the currently active local will be returned. | ||
** English value will be returned if localised is not present. | ** English value will be returned if localised is not present. | ||
| Line 205: | Line 210: | ||
;Description | ;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 | + | * 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()]]). |
<br> | <br> | ||
Latest revision as of 22:20, 27 March 2021
- 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.
[edit] 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.
[edit] Pause
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 PAUSED flag by itself. When called with 'false' parameter, the rule should start executing its own logic.
[edit] SetComplete
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 COMPLETE flag. If called with 'true' parameter it sets also the WAS_COMPLETE flag.
[edit] IsComplete
public bool IsComplete(void)
- Return value
- Returns whether this behavior is currently complete
[edit] WasComplete
public bool WasComplete(void)
- Return value
- Returns whether this behavior was ever complete
[edit] IsPaused
public bool IsPaused(void)
- Return value
- Returns whether this behavior is paused.
[edit] GetStateFlags
public int GetStateFlags(void)
- Return value
- Current state flags for this behavior object.
[edit] SetStateFlags
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.
[edit] GetProperties
public mandatory 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.
[edit] SetProperties
public mandatory void SetProperties(Soup soup)
- 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.
[edit] GetRequirements
public 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.
[edit] GetChildBehaviors
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
[edit] AreAllChildrenComplete
public bool AreAllChildrenComplete()
- Return value
- Whether all child rules are complete
[edit] GetParentBehavior
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.
[edit] Reset
public void Reset(void)
- Description
- Resets the COMPLETE and WAS_COMPLETE flags for this rule.
[edit] GetDescription
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 string table.
[edit] AppendDependencies
public void AppendDependencies(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.
[edit] GetDebugString
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.
[edit] SetSessionString
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
[edit] GetSessionString
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.
[edit] IsCorrectlyConfigured
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.
[edit] SetChildrenLimits
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()).
[edit] GetChildRelationshipIcon
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.
[edit] GetSessionProperties
public Soup GetSessionProperties(void)
- 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.
