Class ScenarioBehavior - Revision history

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

2021-03-27T12:20:59Z

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

← Older revision		Revision as of 12:20, 27 March 2021
Line 86:		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>

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

2021-03-27T12:17:19Z

Constants: Added information about the default state.

← Older revision		Revision as of 12:17, 27 March 2021
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.		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=~~375~~\|public define int NONE = 0\|\|No flags set.		\|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==

Marekp9: Changed overwrite -> override

2021-03-26T22:23:08Z

Changed overwrite -> override

← Older revision		Revision as of 22:23, 26 March 2021
Line 36:		Line 36:

	;Note		;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.		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 146:		Line 146:

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

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

2021-03-26T21:14:14Z

GetSessionString: Corrected display of link to SetSessionString()

← Older revision		Revision as of 21:14, 26 March 2021
Line 183:		Line 183:

	;Return value		;Return value
	* Session string-table entry created by this asset using the [[#SetSessionString]]() function.		* 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.

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

2021-03-26T21:12:56Z

SetSessionString: Corrected display of link to GetSessionString()

← Older revision		Revision as of 21:12, 26 March 2021
Line 174:		Line 174:

	;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]]() function to retrieve the string for display		*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>

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

2021-03-26T21:11:51Z

SetChildrenLimits: Corrected display of link to IsCorrectlyConfigured()

← Older revision		Revision as of 21:11, 26 March 2021
Line 205:		Line 205:

	;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>

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

2021-03-26T21:10:28Z

SetProperties: Corrected display of link to GetProperties()

← Older revision		Revision as of 21:10, 26 March 2021
Line 100:		Line 100:

	;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>

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

2021-03-26T21:09:19Z

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

← Older revision		Revision as of 21:09, 26 March 2021
Line 12:		Line 12:

	==Constants==		==Constants==
	*These constants represent flags defining the rule's state. They can be used in combination with [[#GetStateFlags]]() and [[#SetStateFlags]]() methods.		*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}}		{{TableHeader\|width=95%\|margin=15px}}

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

2021-03-26T21:07:38Z

Constants: Fixed links to GetStateFlags and SetStateFlags

← Older revision		Revision as of 21:07, 26 March 2021
Line 12:		Line 12:

	==Constants==		==Constants==
	*These constants represent flags defining the rule's state. They can be used in combination with [[GetStateFlags]]() and [[SetStateFlags]]() methods.		*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}}		{{TableHeader\|width=95%\|margin=15px}}

Marekp9: Page created

2021-03-26T21:06:17Z

Page created

New page

*[[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]]