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.
Contents |
Creation Methods
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
Method 1 will give you a completely blank slate to start with, and is only recommended for players familiar with rules, rule templates and the editing interface. Method 2 is a useful starting point if you have an existing template that you want to modify. Method 3 is the most common (and easiest) method of creation, and is what is used in the examples below.
It's important to note that no matter which creation method is chosen, the edit interface and 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 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 want to modify, then 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 description, template properties and the current rule configuration. You can then 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 step. Not only does this save time, but it ensures all of your sessions use consistent derailment handling, which creates a better experience for your players.
To create a template in this way, simply right-click on the parent rule 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 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 in just one step.
The first step in building such a template is to 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, as they won't be part of our template. Click the Add button at the bottom of the dialog and add the "Wait for Derailment" rule. This 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. (Be sure to click the tick button when closing the dialogs, or your changes will not be saved.)
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 File:HowTo RuleTemplate Example1.cdp, or from the DLS under <kuid:401543:20026>.
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 area for "Template Properties". If you're interested in learning more about this advanced Rule Template feature, see example 2 below.
Example 2 - Speeding Checks
This Rule Template example examines a more complex rule setup, and introduces the concept of template properties, which allow the Session creator to customise the behavior of a specific template instance. To speed things up, the intricacies of the Rules used are not discussed. To begin, download and install the example session File:HowTo RulesTemplate Example2.cdp (this file is also available on the DLS, as <kuid:401543:20028>).
Open the example Session for edit in Surveyor, then open the Edit Session dialog and have a quick look at the rules list. The template we're creating will use the "Speeding Check" Rule as the parent, right-click on it, and select the "Create template" option.
This Speeding Check is fairly generic, and should be usable in any Session where the player is penalised for speeding, but we want the Session creator to be able to customise two aspects of it. Firstly, the variable which is used to track the session score, and secondly, the specific number of points that are deducted for speeding. For this, we will need two new "Template properties", which can be added by clicking on the '+' button in the Template Properties section of the edit dialog.
Each template property needs an ID, a display name, and a type. The ID is unique, and used internally (within the template itself) to reference the property, and bind it to specific rule options. The display name is the name of that property that will be shown to the session creator in the template instance configuration dialog. The 'type' controls which rule options it can be bound to, and what values are available to configure the property to. Don't worry if this all sounds a bit confusing, it should become clearer once you've played with it a bit.
The first template property we need is the points variable name, so will need a type of 'string'. The second is the number points to deduct for every second of speeding, which is type 'int'. Once you've added these two properties and set their type, give them each a memorable ID and meaningful display name.
Next we need to bind the new Template properties to the desired Rule properties. In the template creation dialog, scroll to the end of the rules list and find the final "Variable Modify Continuous" rule. This rule is responsible for the point deductions when the player is speeding. Select it, and click Edit. You should see the text "Subtract 5 points from variable ranking_points every second". Click on the underlined '5' text as if you were to modify the value. You will be prompted to bind the rule property to a template property, click Yes and select the 'int' property you created earlier. Do the same for the ranking_points variable name, configuring it to the 'string' property you created. Then click the tick to confirm your changes and close the rule edit dialog.
Once you've created and bound the new rule properties you can save the template asset, and return to the Edit Session dialog where the rules have been replaced by a new template instance. You will notice that the new template is in an error state though, because it now has template properties that need to be configured. Select the template and click "Edit" to open the template properties window. Here, you can set the values of the two properties you created. Enter '5' and 'ranking_points' to restore the original behavior, save your changes, and load the Session into Driver to test it.
If you're having issues getting the template to work, you can download and examine a working version of this Session template from the DLS, under <kuid:401543:20029>.
Template Property Limitations
Not all Session Rule options support being bound to Template properties, and you may experience strange issues when trying to bind such options in complex rules. If you do experience such issues, it's usually safest to avoid using those rules within your templates, and try to find another approach. As with all aspects of Session creation there are usually multiple ways to solve a problem, so take a look on the DLS for other 3rd Party rules, or ask around on the Trainz forums.
