Session Rules Overview
This page provides a brief overview of Session Rules (AKA Behaviors), which are the driving force behind gameplay logic in structured Trainz Sessions. If you are unfamiliar with Sessions or Rules, see the HowTo/Create a session guide for an example of how to create a simple Session using some of the builtin Rules.
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 asset type is overlaid atop the Route asset, and can add trains, objects, track etc, alter environmental data such as lighting and weather, modify the properties of objects within the Route, hide Route objects using layer bindings, and/or implement complex gameplay logic using Session Rules. Put simply, Session Rules are scripted Trainz assets which are used to govern and control the gameplay behavior of a Session.
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 running number.
Rules are designed to perform specific tasks such as monitoring and reacting to events, enabling the session creator to direct gameplay. Rules are added, configured or removed from a Session via Surveyor's Edit Session dialog.
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 their 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 particular trigger, at which time a sound is played and then a popup message is displayed...
A Rule's behaviour depends upon the nature of its 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 behavior of a Rule is outlined in its configuration dialog, where it may even allow this behavior to be modified. For more information about a specific rule refer, you can refer to the list of documented Session Rules here.
Task Rules perform their function the instant the rule is started and then remain idle unless reset by a parent Rule. These Rules can be executed at startup in order to set initial Session state, 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 many cases these Rules perform no other function beyond executing their child Rules.
Fig.5 Generally an event Rule completes only once all child Rules have been executed...
Some Rules do not support child rules, and Rules indented below them will not be executed at all. List rules are designed specifically to execute and manage the running of child Rules, and can themselves be child Rules. See Ordered List, Progressive List, Random List, Reset List and Simultaneous List.
Fig.6 A list Rule with its own child Rules can be parented to an event or check Rule...