Class ScenarioBehavior

From TrainzOnline
Jump to: navigation, search


The ScenarioBehavior class is the base class for session rules.

Contents

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

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.

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.

IsComplete

public bool IsComplete(void)
Return value
  • Returns whether this behavior is currently complete


WasComplete

public bool WasComplete(void)
Return value
  • Returns whether this behavior was ever complete


IsPaused

public bool IsPaused(void)
Return value
  • Returns whether this behavior is paused.


GetStateFlags

public int GetStateFlags(void)
Return value
  • Current state flags for this behavior object.


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.

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.


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.


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.


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


AreAllChildrenComplete

public bool AreAllChildrenComplete()
Return value
  • Whether all child rules are complete


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.


Reset

public void Reset(void)
Description


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.


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.


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.


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


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.


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.


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()).


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.


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.


Categories

Retrieved from "https://online.ts2009.com/mediaWiki/index.php?title=Class_ScenarioBehavior&oldid=29036"
Personal tools