HowTo/Create a Behavior Template
Session Rule Templates (AKA Behavior templates) allow Session creators to quickly and easily save and reuse common rule configurations. This page is a short guide to creating, editing and using Session Rule Templates.
Rule Template assets are one of the few asset kinds that is created an edited entirely "in game". More specifically, they are created and edited via the rules list on the "Edit Session" dialog, which is opened from the Surveyor menubar.
There are 3 ways that a new template can be created:
- By creating a new blank template
- By editing an existing template
- From an existing set of rules
Option 1 will give you a completely blank slate to start with, and is only recommended for players familiar with templates and the editing interface. Option 2 is a useful starting point if you have an existing template that you want to modify. Option 3 is the most common (and easiest) method of creation, and is what we will focus on for the majority of this guide.
It's important to note that no matter which creation method is chosen, the edit interface final asset(s) will be identical.
New Blank Template
To create a new blank template, click the "Add" button on the bottom of the Edit Session dialog, and select the "New Blank Template" option from the list.
This will open a completely blank version of the edit interface. From here you will need to give your template a name, description, and then add and configure all of the desired rules. When you close the dialog a new template asset will be created, and a new instance of it will be added to the rules list. If you make a mistake or need to tweak the asset, you can edit it later using method 2, described below.
Editing an Existing Template
To edit an existing rule template asset, locate it in the rules list, right-click on it, and select the "Edit template" option from the displayed context menu. If the selected template asset was not created by you, or is builtin to Trainz or on the Download Station, then you may instead see the "Clone template" or "Create new template version" option. These all have similar behavior, but save the modified asset in slightly different ways.
If you don't have a Session which uses the template asset, you can create one, add an instance of the desired template, edit it, save the asset changes, and then discard/delete the Session. Any changes made on the edit interface will be saved into the template asset itself, and affect all future uses of that asset.
When you click "Edit template" (or one of the similar options) the template edit dialog will open pre-populated with the selected template data, including name, description and the current rule configuration. From here, you can make whatever changes are desired, and save them over the old asset or into a new one.
Rules to Template Conversion
Most new template assets will be created from a pre-existing set of rules, usually because of a desire to copy existing functionality from one Session to another. For example, most structured Sessions make use of the "Wait for Derailment" Rule, which will then show a dialog (Message Popup Rule), and end the session (Ranked Session Complete, or End Session Rule). Rather than adding this sequence of rules over and over again in all of your sessions, you can create a rule template asset which lets you add it in one click.
To create a template in this way, you simply right-click on the parent asset in the rule list (e.g. the Wait for Derailment rule) and select "Create template" from the displayed context menu. This will open the rule template edit dialog, where you must give your new asset a name and description before it can be saved. Once you save the template, the rule(s) you created it from will be replaced with an instance of the template.
If this still sounds a little complicated, see Example 1 below, which will run through this same example step-by-step.
Example 1 - Derailment Response
As mentioned earlier, one of the simplest examples of common rule configurations is that of derailment handling. Following a derailment, most structured sessions immediately end, and there's little else to do but show a dialog to the player which explains why. Furthermore, there's usually no need for Session specific text in that dialog, so all derailment handling for most sessions can be handled with the same simple set of rules. This makes it ideal for a rule template, as then this same set of rules can be added to any new Session with just a few clicks.
To start with, we'll create and test a Session with the desired derailment handling. This Session doesn't need to be anything special, as it's merely a test-bed for the Rule setup, and we'll be deleting it when we're done. Create a new route using the option from the game menu. Once Surveyor loads, add a single short stretch of track using any track asset you like, then add any locomotive you like. Next, open the Edit Session dialog using the option on the menubar.
You should see the default Session Rules listed, such as Driver Setup and Driver Commands, these are fine to leave in their default state. Click the Add button at the bottom of the dialog and add the "Wait for Derailment" rule. This rule is a simple reactive rule, which responds to any train derailment by executing it's child rules (the rules indented below it). On it's own it doesn't do anything, so we need to give it some children. Add two more rules, a "Message Popup" and a "End Session".
The Message Popup rule shows a dialog to the player when it's run. The text in this dialog will still need to be entered but we'll come back to that later. First, we want to ensure it runs at the appropriate time, so indent it beneath the Wait for Derailment Rule by clicking the right-arrow button on the bottom right of the Edit Session dialog, or by pressing ctrl+right-arrow. Do the same on the End Session Rule. You should notice that the rules have both moved to the right, and are now children of the Wait for Derailment Rule.
Wait for Derailment executes all child rules simultaneously when a derailment occurs, as indicated by the '=' icon in the tree view next to each of the children. If we left the rules like this, the End Session rule would run at the same time as the Message Popup, and the player would not get to read the message. Indent the End Session Rule again, so that it's a child of the Message Popup, as shown in the image on the right. In this configuration the End Session Rule will not run until the Message Popup is closed by the player.
Finally, lets go back and set the text for the Message Popup. Select the Message Popup rule and click "Edit", then enter some text into the "Custom Message" field. Don't worry if you're not familiar with this particular Rule, no other configuration is necessary. Once you've entered your text, close the Rule edit dialog, and close the Edit Session dialog.
You're now ready to test your Session. Save it, then exit and reload the Session in Driver. Once it loads, drive the locomotive off the end of the track to derail it. You should see the Message Popup with the text you entered. When you close the popup, the Session should exit back the menu. If it all works then great, you're now ready to create the template! If it doesn't work as expected, go back over the steps, listed in this section and double check each Rule. If you're still having issues you can download a preconfigured Route and Session here.
Once you've confirmed the Rules work as intended open the Session for edit in Surveyor and go back to the Edit Session dialog. Locate the Wait for Derailment rule in the list, right-click on it and select "Create template" from the displayed context menu to open the template creation/edit dialog. Enter a brief description for the new asset, then click the tick in the bottom right to confirm asset creation. (This will open a new prompt where you must enter the asset name, and can optionally add a longer asset description.) Once you confirm the asset creation the rules in the Edit Session dialog will be replaced by a template instance.
At this point it's a good idea to test your Session again, just to make sure the new template still behaves as expected, but your template asset can now be added to your other Sessions, or uploaded to the Download Station for sharing.
You may have noticed that the template creation/edit dialog has an extra are for "Template Properties". If you're interested in learning more about this advanced Rule Template feature, see example 2 below.
Example 2 - TDB