View source for Session Rules Overview

[[Session Rules Overview]]

This page provides a brief theoretical overview of the components that make up a Trainz session and the rules that control the session. For more information about session 

implementation and structure see [[HowTo/Create a session]].  

=Anatomy of a Session=
A session is a Surveyor-created asset that groups together a variety of components to create a playable environment for Driver. This includes the route, rules, consists and custom 

configuration properties. Rules are scripted Trainz assets used to govern and control the behavior of the session.

[[Image:SessionRulesOverview1.jpg]]

Fig.1 Conceptual view of a session and it's primary components.

The session has a properties database for each rule instance it uses so that rule’s particular configuration for the session can be saved/loaded. Multiple instances of the same type of 

rule can exist in a session, each with its own unique configuration. This works in the same way that multiple instances of a specific type of locomotive can exist in the session where 

each locomotive can have its own name and road number.

Rules can be added, configured or removed from a session via Surveyor's Edit Session dialogue. Rules are designed to perform specific tasks such as monitoring and reacting to 

events, enabling the session creator to direct gameplay.

=Rule Hierarchy and Child Rules=

Rule hierarchy is established in order to pause certain rules unless specific criteria have been met.  Top level or "parent" rules are started automatically when the session is launched in 

Driver. Child rules are executed only when explicitly started by the parent rule.

Fig.2 When Driver is launched, top level rules are initialized and run immediately using the settings defined in Surveyor. 

Fig.3 Child rules are not run until specific criteria defined in the parent rule are met.

Fig.4 Child rules are indented below the parent rule. Note the order of execution is displayed to the left of the child rules. In this example nothing happens until a train enters a a 

particular trigger, at which time a sounds is played and then a popup message is displayed. 

=Rule Behaviour=

A rule's behaviour depends upon the nature of it's task. Some rules complete their task immediately, some check only once for specific criteria, while others wait for a specific event or 

situation. Generally the behaviour of a rule is outlined in it's configuration dialogue. For detailed information about specific rules refer to the list of documented Surveyor Rules.

==Task Rules==

Task rules perform their function the instant the rule is started and then remain idle unless reset by a parent rule. These rules are generally executed at startup or by a parent rule once 

specific criteria have been met.

==Event and Check Rules==

Once started these rules generally wait for specific events to occur before proceeding to execute their task or their child rules. In some cases these rules perform no other function 

beyond executing their child rules.

Fig.5  Generally an event rule completes once it's task and/or any child rules have been executed.


==List Rules==

Some rules do not support child rules, and rules indented below them will be executed simultaneously. List rules are designed specifically to execute and manage the running of child 

rules, and can themselves be child rules.

Fig.6 A list rule with it's own child rules can be parented to an event or check rule.