Session Rule Implementation - Revision history

Pw3r at 05:32, 11 October 2019

2019-10-11T05:32:57Z

← Older revision		Revision as of 05:32, 11 October 2019
Line 449:		Line 449:

	[[Category:Help]]		[[Category:Help]]
			[[Category:Session Rules]]

Tonyhilliam at 12:22, 12 September 2019

2019-09-12T12:22:46Z

← Older revision		Revision as of 12:22, 12 September 2019
Line 442:		Line 442:

	5. Inheriting from ConditionalScenarioBehavior typically means that there's a lot less semi-custom boilerplate in your rule, making your rule much simpler to read and maintain. This helps you while you're debugging your own rule, helps you when you're coming back in a year's time and wondering how it all worked, and perhaps helps others in the community if they need to update your rule in 10 years time after you've moved on from developing Trainz script code.		5. Inheriting from ConditionalScenarioBehavior typically means that there's a lot less semi-custom boilerplate in your rule, making your rule much simpler to read and maintain. This helps you while you're debugging your own rule, helps you when you're coming back in a year's time and wondering how it all worked, and perhaps helps others in the community if they need to update your rule in 10 years time after you've moved on from developing Trainz script code.

			SEE ALSO:

			*[[Session_Rules_Overview\|Session Rules Overview]]
			*[[Session_Rules_By_Categories_With_Properties\|Session Rules By Categories With Properties]]

			[[Category:Help]]

Pw3r at 02:56, 28 June 2019

2019-06-28T02:56:17Z

← Older revision		Revision as of 02:56, 28 June 2019
Line 36:		Line 36:
	== Initial State ==		== Initial State ==
	All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes steps to begin program flow.		All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes steps to begin program flow.

			== State Determination ==
			Rules should always base their functionality on the state flags such as the PAUSED state, rather than attempting to detect and vary their functionality based on the state of the game.

			For example, [[Unified Driver Surveyor]] makes it possible to switch between Driver and Surveyor at will, without any loading screen, and without any affect on world gameplay state. This includes Session Rule state. It is incorrect behavior for a rule to pause itself, or otherwise prevent or stop execution, based on the active interface module. APIs exist to detect such state changes where necessary, but in most cases it's simply not necessary to care whether your rule is in Surveyor or Driver - you should act based on the PAUSED state instead.

			Rules should also not assume that it is impossible to be reconfigured during gameplay. This will of course introduce some side effects, such as when an unpaused rule is modified during execution. It is the rule's responsibility to ensure that these side effects do not lead to script exceptions or to leaked state. For example, if a single thread is supposed to be running, reconfiguring the rule should not cause a second thread to run simultaneously. If a rule sniffs a target vehicle, and the target vehicle is redefined, then the rule should unsniff the original vehicle rather than now sniffing two vehicles.

	== Top Level Rules ==		== Top Level Rules ==
Line 128:		Line 135:
	It is important to note that these behaviors describe how the rule reacts to internal condition checks. The rule's reaction to being paused by its parent is discussed above under "Early Termination via Pause" and is not affected by the description here.		It is important to note that these behaviors describe how the rule reacts to internal condition checks. The rule's reaction to being paused by its parent is discussed above under "Early Termination via Pause" and is not affected by the description here.

	In short, there are many ways of handling this, and the important thing is for ~~your~~ (parent) rule to clearly explain which approach it is going to use.		In short, there are many ways of handling this, and the important thing is for the (parent) rule to clearly explain which approach it is going to use.


	= Rule Reset =		= Rule Reset =
	A rule may be ''reset'' by its parent. This causes both the COMPLETE and WAS COMPLETE states to be deflagged. Individual rules may also react to the reset by modifying their internal state to forget past or present actions. Parent rules must also cause their children to be reset in turn.		A rule may be ''reset'' by its parent. This causes both the COMPLETE and WAS COMPLETE states to be deflagged. Individual rules may also react to the reset by modifying their internal state to forget past or present actions. Parent rules which support child execution must also cause their children to be reset in turn.

	This mechanism is used to permit rules to be used in a repeating scenario, such as responding to a condition which can occur multiple times, or in a repeating loop. At some point after a rule has become flagged as WAS COMPLETE, it will typically become paused and will not be unpaused again. If the rule is to be included in some repeating behavior, this would normally prevent the behavior from operating successfully after the first run through. To avoid this, the parent rule responsible for implementing the repeating behavior will ''reset'' all children when a repeat occurs. This effectively cleans the rules back to their initial state ready to perform their roles again.		This mechanism is used to permit rules to be used in a repeating scenario, such as responding to a condition which can occur multiple times, or in a repeating loop. At some point after a rule has become flagged as WAS COMPLETE, it will typically become paused and will not be unpaused again. If the rule is to be included in some repeating behavior, this would normally prevent the behavior from operating successfully after the first run through. To avoid this, the parent rule responsible for implementing the repeating behavior will ''reset'' all children when a repeat occurs. This effectively cleans the rules back to their initial state ready to perform their roles again.
Line 138:		Line 145:
	It is important to note that a reset should cause the rule to return to its configured settings. For example, if a timer value is configured and is decremented during rule operation, the timer must be reset back to its initial value during rule reset.		It is important to note that a reset should cause the rule to return to its configured settings. For example, if a timer value is configured and is decremented during rule operation, the timer must be reset back to its initial value during rule reset.

	It is important to note that there is no requirement to pause a rule prior to resetting it.		It is also important to note that there is no requirement to pause a rule prior to resetting it.

			= Spurious Events =
			There are various events (typically script messages) that a rule may listen for in order to detect state changes. It is important to note that spurious events are often possible, and that an event handler should often be coupled with a condition check. As a specific example, the "ScenarioBehavior", "Touch" message typically indicates that a child state has changed, but the message may in fact be sent at any time. This message should prompt the rule to evaluate whether any state changes are necessary, but the rule should not assume that a state change is necessary without performing an evaluation.

			Similarly, calls to a function such as Pause() may in some cases have no effect. For example, if a rule is already executing and its parent calls Pause(false), the rule should not pause, reset, or change state in any way at all. Similarly, if a rule is already paused and its parent calls Pause(true), the rule should not unpause, reset, fire any events, or otherwise change state in any way at all.

			The short version is: do not assume that every event and every method call is supposed to achieve something meaningful. Check first, and if the event is meaningless to you then do nothing at all.

	= Saving and Loading Driver Sessions =		= Saving and Loading Driver Sessions =
Line 158:		Line 171:
	Finally, the COMPLETE, WAS COMPLETE, and PAUSED flags on child rules should be honored. This is typically sufficient information to determine the running state of child rules, so no further state will generally need to be maintained. More accurately, the child rules take care of their own state at all times, and the parent only needs to react to changes in the child state. Since no child state change occurs across a Save/Load operation, the parent does not need to become involved.		Finally, the COMPLETE, WAS COMPLETE, and PAUSED flags on child rules should be honored. This is typically sufficient information to determine the running state of child rules, so no further state will generally need to be maintained. More accurately, the child rules take care of their own state at all times, and the parent only needs to react to changes in the child state. Since no child state change occurs across a Save/Load operation, the parent does not need to become involved.

	For rules which derive ConditionalScenarioBehavior, the ~~majority of~~ load/save logic is handled automatically. The only state information that such a rule should typically preserve is the ~~instance~~-specific configuration data. The condition-monitor thread will be automatically restarted as required, and there is generally no need to distinguish between a first-startup and any subsequent startup.		For rules which derive ConditionalScenarioBehavior, the load/save of the majority of execution logic is handled automatically. The only state information that such a rule should typically preserve is the implementation-specific configuration data. The condition-monitor thread will be automatically restarted as required, and there is generally no need to distinguish between a first-startup and any subsequent startup.


	~~= Spurious Events =~~
	There are various events (typically script messages) that a rule may listen for in order to detect state changes. It is important to note that spurious events are often possible, and that an event handler should often be coupled with a condition check. As a specific example, the "ScenarioBehavior", "Touch" message typically indicates that a child state has changed, but the message may in fact be sent at any time. This message should prompt the rule to evaluate whether any state changes are necessary, but the rule should not simply assume that a state change is necessary without performing an evaluation.

	Similarly, calls to a function such as Pause() may in some cases have no effect. For example, if a rule is already executing and its parent calls Pause(false), the rule should not pause, reset, or change state in any way at all. Similarly, if a rule is already paused and its parent calls Pause(true), the rule should not unpause, reset, fire any events, or otherwise change state in any way at all.

	~~The short version is: do not assume that every event and every method call is supposed to achieve something meaningful. Check first, and if the event is meaningless to you then do nothing at all.~~


	~~= Future Considerations =~~
	~~Rules should base their functionality on the state flags such as the PAUSED state, rather than attempting to detect and vary their functionality based on the state of the game.~~

	For example, we currently (in development builds) expose the rules editor in Driver for debugging purposes. This, or some mechanism like it, is likely to be included in public builds in the future. Rules should not assume that it is impossible to be reconfigured during gameplay. This will of course introduce some side effects, such as when an unpaused rule is modified during execution. It is the rule's responsibility to ensure that these side effects do not lead to script exceptions or to leaked state. For example, if a single thread is supposed to be running, reconfiguring the rule should not cause a second thread to run simultaneously. If a rule sniffs a target vehicle, and the target vehicle is redefined, then the rule should unsniff the original vehicle rather than now sniffing two vehicles.

	Likewise, we may in future allow some form of partial state swap between Driver and Surveyor. Rules should not assume that it is impossible to change from any one game state or module to any other game state or module, just because it is not possible at the current time. APIs already exist to detect such state changes where necessary, and in most cases it's simply not necessary to care whether your rule is in Surveyor or Driver - you should act based on the PAUSED state instead. Rules should deal with the game state as they find it rather than assuming that certain states will not ever occur.


	= Gotchas =		= Gotchas =

Pw3r: /* Early Termination via Pause */

2019-06-28T01:41:22Z

Early Termination via Pause

← Older revision		Revision as of 01:41, 28 June 2019
Line 110:		Line 110:
	A rule must accept being paused by its parent at any time. This should cause the rule to cease any game state monitoring or other direct effects. The rule must pause all child rules immediately.		A rule must accept being paused by its parent at any time. This should cause the rule to cease any game state monitoring or other direct effects. The rule must pause all child rules immediately.

	In cases where the rule is maintaining some reversible effect on the game world, pausing the rule should end this effect. For example, a rule which displays a message to the user should typically hide the message upon becoming paused, and a rule which causes a rain storm in a specific area should return the weather to normal upon becoming paused. Rules which make a single permanent change to the game world and then immediately flag as COMPLETE should not attempt to reverse the change upon becoming paused. Examples of these rules include configuration of the global weather conditions, or a rule which increments the player's score or penalty counter.		In cases where the rule is maintaining some reversible effect on the game world, pausing the rule should end this effect. For example, a rule which displays a message to the user should typically hide the message upon becoming paused, and a rule which causes a rain storm in a specific area should return the weather to normal upon becoming paused. Rules which make a single permanent change to the game world and then immediately flag as COMPLETE should not attempt to reverse the change upon becoming paused. Examples of these rules include configuration of the global weather conditions, or a rule which increments the player's score or penalty counter. It is acceptable for a single rule to support both of these cases by way of a checkbox option within the rule edit interface.

	It is important to note that any pause is resumable, although the parent may not choose to take advantage of this. Pausing a rule followed by unpausing it should result in the rule continuing operation where it left off. The notes on Saving and Loading Driver Sessions (below) are worth considering when evaluating techniques for implementing pause.		It is important to note that any pause is resumable, although the parent may not choose to take advantage of this. Pausing a rule followed by unpausing it should result in the rule continuing operation where it left off. The notes on Saving and Loading Driver Sessions (below) are worth considering when evaluating techniques for implementing pause.


	= Early Termination via Internal Logic =		= Early Termination via Internal Logic =

Pw3r at 01:19, 28 June 2019

2019-06-28T01:19:25Z

← Older revision		Revision as of 01:19, 28 June 2019
Line 3:		Line 3:

	= Legacy Behavior Note =		= Legacy Behavior Note =
	Please note that many existing rules do not behave ~~correctly~~ as defined here. This is considered a bug in the individual session rules. [[N3V Games]] has a policy of updating session rules to behave correctly even where that may lead to changes of function in existing [[session]] assets. Where reasonable to achieve, emulation of the existing (buggy) behavior may occur for existing rule instances in existing sessions, however any newly created rule instances will use the corrected behavior.		Please note that many existing rules do not behave as defined here. This is considered a bug in the individual session rules. [[N3V Games]] has a policy of updating session rules to behave correctly even where that may lead to changes of function in existing [[session]] assets. Where reasonable to achieve, emulation of the existing (buggy) behavior may occur for existing rule instances in existing sessions, however any newly created rule instances will use the corrected behavior.

	These expectations were codified at the end of [[TS12]] development due to an increasing inability of session rules to work together resulting from the unpredictable nature of their responses to various common use-cases. The systems as a whole, including most of the core rules discussed in this document, have existed for far longer than this document. The document does not redefine any existing systems, but simply presents the only reasonable implementation approach possible if rules are to be expected to work ~~properly~~ in all use-cases. In some cases we also choose to mandate specific points of behavior relating to user expectations rather than technical necessities.		These expectations were codified at the end of [[TS12]] development due to an increasing inability of session rules to work together resulting from the unpredictable nature of their responses to various common use-cases. The systems as a whole, including most of the core rules discussed in this document, have existed for far longer than this document. The document does not redefine any existing systems, but simply presents the only reasonable implementation approach possible if rules are to be expected to work reliably in all use-cases. In some cases we also choose to mandate specific points of behavior relating to user expectations rather than technical necessities.

	Certain additional API mechanisms were introduced alongside the development of this document, to allow better communication with session authors regarding the differences in behavior between certain types of rule. The correct usage for these mechanisms is also included in this document.		Certain additional API mechanisms were introduced alongside the development of this document, to allow better communication with session authors regarding the differences in behavior between certain types of rule. The correct usage for these mechanisms is also included in this document.
Line 17:		Line 17:

	=== PAUSED ===		=== PAUSED ===
	The rule is currently paused, meaning that it does not affect the game world in any way and does not respond to any changes in the game world. The parent rule must cause the rule to become unpaused for the rule to have any effect. It is not correct behavior for a rule to unpause itself.		The rule is currently paused, meaning that it does not affect the game world in any way and does not respond to any changes in the game world. The parent rule (or native code) must cause the rule to become unpaused for the rule to have any effect. It is not correct behavior for a rule to unpause itself. It is not correct behavior for a rule to unpause any children while it itself is paused.

	=== COMPLETE ===		=== COMPLETE ===
	This flag indicates that rule has fully completed its operation (including any child rule operations) and ~~does not affect~~ the game world in any way. This flag is set by the rule itself, not by an outside entity such as the parent. This state should not be changed while the rule is PAUSED.		This flag indicates that rule has fully completed its operation (including any child rule operations) and no longer affects the game world in any way. This flag is set by the rule itself, not by an outside entity such as the parent. This state should not be changed while the rule is PAUSED.

	Being COMPLETE does not imply being PAUSED. In many scenarios, the parent rule may respond to a child becoming COMPLETE by causing it to also become PAUSED, however this is certainly not guaranteed in all cases, and is not guaranteed to be immediate in the cases where it does happen.		Being COMPLETE does not imply being PAUSED. In many scenarios, the parent rule may respond to a child becoming COMPLETE by causing it to also become PAUSED, however this is certainly not guaranteed in all cases, and is not guaranteed to be immediate in the cases where it does happen.
Line 35:		Line 35:

	== Initial State ==		== Initial State ==
	All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes ~~step~~ to begin program flow.		All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes steps to begin program flow.

	== Top Level Rules ==		== Top Level Rules ==
Line 69:		Line 69:

	==Parent Rule Styles==		==Parent Rule Styles==
	There are a few common techniques with which parent rules interact with their children. Rules should always fit one of these descriptions. The vast majority of rules should follow either the "Does Not Support Children" style, or the "Ordered Execution of Children" style.		There are a few common techniques with which parent rules interact with their children. Rules should always fit one of these descriptions. The vast majority of rules should follow either the "Does Not Support Children" style, or the "Ordered Execution of Children" style. The style of child execution should also be indicated in the Rules list GUI, by implementing the ScenarioBehavior.GetChildRelationshipIcon() function.

	=== Does Not Support Children ===		=== Does Not Support Children ===
	The rule is incapable of supporting children and will ~~always~~ ignore them.		The rule is incapable of supporting children and will ignore them entirely.

	This is used for trivial rules which perform a set function and then become permanently COMPLETE. Such rules are not conditional and do not wait for any world state changes except those which they initiate internally.		This is used for trivial rules which perform a set function and then become permanently COMPLETE. Such rules are not conditional and do not wait for any world state changes except those which they initiate internally. For rules which do not support children ScenarioBehavior.GetChildRelationshipIcon() should be implemented to unconditionally return "none".
	~~The rule~~ should be ~~configured~~ to ~~validate and/or enforce that no child rules can be added~~.

	=== Simultaneous Execution of Children ===		=== Simultaneous Execution of Children ===
	When the rule is ready to begin executing children, it unpauses all children simultaneously. The rule then waits for all children to flag as WAS COMPLETE. Once this is detected, the rule pauses all children and flags itself as COMPLETE.		When the rule is ready to begin executing children, it unpauses all children simultaneously. The rule then waits for all children to flag as WAS COMPLETE. Once this is detected, the rule pauses all children and flags itself as COMPLETE.

	This is used for rules which have a specific need to simultaneously execute children, such as the "Simultaneous List" rule.		This is used for rules which have a specific need to simultaneously execute children, such as the "Simultaneous List" rule.

	The ~~rule editor~~ interface should ~~be explicit~~ that child rules will be executed simultaneously. ~~Child rules should be tagged appropriately in the~~ rule ~~editor list to denote unordered execution~~.		The rules list interface should explicitly denote that child rules will be executed simultaneously. This is done by implementing ScenarioBehavior.GetChildRelationshipIcon() to return "simultaneous" for any passed child rule.

	=== Ordered Execution of Children ===		=== Ordered Execution of Children ===
	When the rule is ready to begin executing children, it iterates through the children in top-to-bottom order. If the child is flagged as WAS COMPLETE, the child is paused and iteration continues. If the child is not flagged as WAS COMPLETE, the child is unpaused and iteration ends. Whenever a child state change is detected, this process is repeated from the start. Once iteration passes over all children without leaving any child unpaused, the rule flags itself as COMPLETE.		When the rule is ready to begin executing children, it iterates through the children in top-to-bottom order. If the child is flagged as WAS COMPLETE, the child is paused and iteration continues. If the child is not flagged as WAS COMPLETE, the child is unpaused and iteration ends. Whenever a child state change is detected, this process is repeated from the start. Once iteration passes over all children without leaving any child unpaused, the rule flags itself as COMPLETE.

	This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules ~~will~~ follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.		This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules should follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.

	Rules which follow this style should derive from [[ConditionalScenarioBehavior]] in order to avoid re-implementing the control flow logic, as it is ~~exceedingly~~ complex to implement correctly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.		Rules which follow this style should derive from [[ConditionalScenarioBehavior]] in order to avoid re-implementing the control flow logic, as it is surprisingly complex to implement correctly, and commonly done incorrectly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.

	~~Child rules should be tagged appropriately~~ in the ~~rule editor~~ list ~~to denote execution order~~.		Ordered child execution is denoted in the rules list interface by rendering a number beside the child. This behavior is implemented by having ScenarioBehavior.GetChildRelationshipIcon() return an appropriate number string.

	=== Controlled Selection of a Single Child ===		=== Controlled Selection of a Single Child ===
	When the rule is ready to begin executing children, it selects a single child and unpauses it. All other children remain paused. Once the selected child becomes flagged as WAS COMPLETE, the child is paused and the rule flags itself as COMPLETE.		When the rule is ready to begin executing children, it selects a single child and unpauses it. All other children remain paused. Once the selected child becomes flagged as WAS COMPLETE, the child is paused and the rule flags itself as COMPLETE.

	This style is used where complex conditional selection of child rules is required. This can be used to implement an "if-else" logic flow, a "switch-case" logic flow, or the "Random List" ~~rule~~. This style should not be used to implement a simple "if" logic flow, because that would unnecessarily restrict the rule to a single child where the "Ordered Execution of Children" style would provide the same functionality while allowing multiple children.		This style is used where complex conditional selection of child rules is required. This can be used to implement an "if-else" logic flow, a "switch-case" logic flow, or Rules such as the "Random List". This style should not be used to implement a simple "if" logic flow, because that would unnecessarily restrict the rule to a single child where the "Ordered Execution of Children" style would provide the same functionality while allowing multiple children.
	~~The rule editor~~ interface should ~~be very explicit about~~ how ~~the~~ child rules will be ~~selected~~. ~~Child rules should~~ be ~~tagged appropriately in the rule editor list~~ to ~~avoid the user attempting to fit~~ a ~~child~~ rule ~~into~~ the ~~wrong role~~.
			As always, the rules list interface should explicitly indicate how/if/which child rules will be executed. In this case ScenarioBehavior.GetChildRelationshipIcon() may be required to return a KUID or filepath for a custom texture. The rule edit interface and description should also clearly indicate the behaviour using localisable text.

	=== Custom Execution with Multiple Children ===		=== Custom Execution with Multiple Children ===

Pw3r at 22:42, 27 June 2019

2019-06-27T22:42:56Z

← Older revision		Revision as of 22:42, 27 June 2019
Line 1:		Line 1:
	This page seeks to clearly define expected script behavior for [[~~KIND Scenariobehavior~~\|Session Rule assets]]. This focuses specifically on correct behavior from the code perspective, rather than addressing how rules should be designed for best gameplay outcomes.		This page seeks to clearly define expected script behavior for [[KIND_Behavior\|Session Rule assets]]. This focuses specifically on correct behavior from the code perspective, rather than addressing how rules should be designed for best gameplay outcomes.

Windwalkr at 04:31, 28 November 2018

2018-11-28T04:31:59Z

← Older revision		Revision as of 04:31, 28 November 2018
Line 430:		Line 430:
	}		}
	</pre></code>		</pre></code>

			== Handler Called while Paused ==
			This one is pretty obvious, but can still catch you out. Handler functions created with AddHandler() will always be called, regardless of whether your rule is paused. You should generally only add your required handlers when your rule is unpaused, and remove them again when paused. If that's not feasible for some reason, then the alternative is to have you handler function confirm the paused state of the rule before doing any actual work (but keep in mind that this approach wastes CPU time).

	== Failing to Inherit from ConditionalScenarioBehavior ==		== Failing to Inherit from ConditionalScenarioBehavior ==

Windwalkr: /* Gotchas */

2018-11-27T17:26:22Z

Gotchas

← Older revision		Revision as of 17:26, 27 November 2018
Line 430:		Line 430:
	}		}
	</pre></code>		</pre></code>

			== Failing to Inherit from ConditionalScenarioBehavior ==
			This isn't really a separate gotcha, but it can't be stressed enough that your rule should inherit from ConditionalScenarioBehavior and should minimise the number of overrides to its default behavior. Apart from the "users expect things to work like this, so that's what you should do" argument, there are some much more compelling arguments for would-be rule developers:

			1. Developing a rule with correct threading behavior is hard. Just have a look at some of the above gotchas. Were you already consciously aware of them all? If not, you're probably not ready to write your own rule which involves threading. ConditionalScenarioBehavior provides a polling thread mechanism that's already built, so you can reap the benefits of that approach without having to worry about whether you made any mistakes in the threading code.

			2. Developing a rule with correct load/save behavior can be hard. Did you correctly restart your threads when necessary? Did you accidentally restart your threads when you weren't supposed to? Was there a message in flight during the save which you lost by reloading, and have you handled that loss correctly? ConditionalScenarioBehavior can help with a lot of that kind of thing, leaving you to worry about your rule-specific implementation only.

			3. Developing a rule with correct child-rule-handling behavior can be really hard. You need to have a thorough understand of everything listed in this document, and you need to ensure that you don't make any mistakes which could cause your rule to violate any of the principles in this document, even in edge-case behaviours. Because this is the real world, you also need to handle child rules which don't necessarily follow the rules to the letter. ConditionalScenarioBehavior does all of this automatically with no effort on your part.

			4. Inheriting from ConditionalScenarioBehavior means that many future issues can be fixed automatically by [[N3V Games]] without you having to update your rule. This includes both fixes to our own code (hey, we're human too) and also new changes to adapt our code to future requirements.

			5. Inheriting from ConditionalScenarioBehavior typically means that there's a lot less semi-custom boilerplate in your rule, making your rule much simpler to read and maintain. This helps you while you're debugging your own rule, helps you when you're coming back in a year's time and wondering how it all worked, and perhaps helps others in the community if they need to update your rule in 10 years time after you've moved on from developing Trainz script code.

Windwalkr: /* COMPLETE */

2018-11-27T17:10:40Z

COMPLETE

← Older revision		Revision as of 17:10, 27 November 2018
Line 26:		Line 26:
	The rule may optionally respond to specific changes in the game world by deflagging the COMPLETE status. For example, a rule which specifically implements a condition check may choose to become COMPLETE when that condition is met, but return to an incomplete state when the condition is no longer met (again, remembering that a change in either direction should only happen while the rule itself is not PAUSED).		The rule may optionally respond to specific changes in the game world by deflagging the COMPLETE status. For example, a rule which specifically implements a condition check may choose to become COMPLETE when that condition is met, but return to an incomplete state when the condition is no longer met (again, remembering that a change in either direction should only happen while the rule itself is not PAUSED).

	When a rule's COMPLETE state ~~changes~~, a "ScenarioBehavior", "Touch" message is sent ~~'''(TBD: BY WHAT MECHANISM?)'''~~ to its parent rule (if any), unless the parent is in the PAUSED state. This allows the parent to react to changes in its child rules' states. It is important to note that the message indicates a possible change which the parent may be interested in, but it is the parent rule's responsibility to determine whether the state change is worth reacting to.		When a rule's COMPLETE state is changed via ScenarioBehavior.SetComplete(), a "ScenarioBehavior", "Touch" message is sent to its parent rule (if any), unless the parent is in the PAUSED state. This allows the parent to react to changes in its child rules' states. It is important to note that the message indicates a possible change which the parent may be interested in, but it is the parent rule's responsibility to determine whether the state change is worth reacting to.

	=== WAS COMPLETE ===		=== WAS COMPLETE ===

Windwalkr: /* Ordered Execution of Children */

2018-11-27T17:05:41Z

Ordered Execution of Children

← Older revision		Revision as of 17:05, 27 November 2018
Line 88:		Line 88:
	This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules will follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.		This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules will follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.

	Rules which follow this style should derive from ConditionalScenarioBehavior in order to avoid re-implementing the control flow logic, as it is exceedingly complex to implement correctly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.		Rules which follow this style should derive from [[ConditionalScenarioBehavior]] in order to avoid re-implementing the control flow logic, as it is exceedingly complex to implement correctly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.

	Child rules should be tagged appropriately in the rule editor list to denote execution order.		Child rules should be tagged appropriately in the rule editor list to denote execution order.