Show the Derivation of Values (Savage)

Context: HL Kit … Authoring Examples … Savage Worlds Walk-Through 

Overview

Within Savage Worlds, many traits are influenced by a variety of factors. When the user sees one of these traits on the screen, there will be times when the number just doesn't look right. Usually, this will be due to some effect being included that the user has overlooked but the data files are properly tracking. At times like this, it would be incredibly helpful to inform the user how the final trait value was actually calculated for the character, presenting each of the contributing influences so the user can see what he's overlooked. We'll take the time to add this information in a few key spots.

Built-In History Tracking

The first thing we need to do is provide a place to accrue the derivation details for each trait. Your first thought is probably to define a new text-based field where this information can be tracked, and that approach would definitely work. However, the Kit provides built-in handling for just this type of situation.

Fields that are value-based and derived can leverage history tracking that is wholly managed by HL. The tracking can take three different forms. The first is "best" tracking, which only tracks the largest adjustment applied to a given field and is ideally suited for situations where adjustments do not stack. The second is "stack" tracking, where each individual adjustment is tracked. The third is "changes" and is identical to "stack", except that it automatically ignores any adjustments that have no net effect (e.g. adding zero). We'll want to use the second form and present a report to the user that shows all of the adjustments that were applied.

We can enable history tracking very easily by adding a new attribute to the field definition. Since all of the adjustments we want to track are applied to the "trtBonus" field of Traits, we'll add history tracking to that field. The modified field definition should look similar to the one shown below.

<field
  id="trtBonus"
  name="Bonus Value"
  type="derived"
  history="stack">
  </field>

Tracking of Adjustments

At this point, we could reload the data files and everything would continue to work as before. Although history tracking has been enabled for the "trtBonus" field, we can choose when to track adjustments and when not to do so. The tracking mechanism is optional, allowing us to apply adjustments that aren't tracked. This is important, because the same field may need to utilize history tracking for some things and not for others. This also makes it easy for us to integrate history tracking in a step-wise process instead of requiring us to do it all at once.

In order to track an adjustment within the history for a field, we need to utilize the "modify" target reference on the field. This target reference must be given an operator (e.g. "+" or "-"), a value, and a string that describes what the adjustment represents. Adding 2 to the "trtBonus" field for the "trCharisma" trait would look similar to the line of code below.

perform hero.child[trCharisma].field[trtBonus].modify[+,2,"The Reason"]

Since we're going to be using this basic statement in lots of places, we might as well make it easy on ourselves. So we'll define a new script macro for this field that works similarly to the "traitbonus" script macro that we already use whenever modifying the value of a trait. Open the file "definition.def" and locate the various script macros. Now define a new macro that takes four parameters and resolves to the "modify" usage shown above. The new macro should look like the following.

<scriptmacro
  name="traitadjust"
  param1="trait"
  param2="oper"
  param3="value"
  param4="text"
  result="hero.child[#trait].field[trtBonus].modify[#oper,#value,#text]"/>

Since a macro is simply text that gets swapped in during compilation, we could also include the "perform " statement in the macro. If we do not include it, using the macro will look like the first example below. If we do include it, then our code will look like second example below. You are free to choose what works best for you, but we'll use the former approach as we continue this topic.

perform #traitadjust[trCharisma,2,"The Reason"]

#traitadjust[trCharisma,2,"The Reason"]

Revise Adjustments for Derived Traits

We now need to put the adjustment tracking to use within the data files. This entails identifying the places where we need to switch to the new mechanism and converting them appropriately. We'll start by focusing on the four derived traits for Savage Worlds, since these are the most heavily modified via different effects.

The first thing we need to do is setup the basic thing definitions for these traits to properly use the history tracking. Open the file "thing_traits.str" and locate the derived traits. We'll now go through them, one at a time.

The first trait is "trPace". It properly sets up the initial field value of 6, and the Eval script bounds the "trtFinal" field, so there is nothing we need to do here.

The next trait is "trParry", for which the Eval script includes both the starting value of 2 and adds half the Fighting skill. We need to change this so that we define the initial field value to be 2 via a "fieldval" element. Then we need to change the Eval script to utilize the macro to apply to adjustment for half the Fighting skill. We can put the adjustment for the Fighting skill within an "if" statement if we wish, which will only show the adjustment if there is an actual skill, but it's also valid to always include the adjustment and have it report a value of zero. These two changes are shown below.

<fieldval field="trtBonus" value="2"/>

if (hero.childexists[skFighting] <> 0) then
  perform field[trtBonus].modify[+,#traitfound[skFighting],"Half Fighting"]
  endif

Next up is the "trCharisma" trait, which doesn't require any changes. We could be complete and specify a "fieldval" element with an initial value of 0, but that's not truly necessary.

Lastly, we have the "trTough" trait. This trait is similar to the "trParry" trait in its behavior. We need to define the initial field value of 2 via the "fieldval" element. We also need to change the Eval script to apply the proper adjustment for the Vigor attribute. These two changes are shown below.

<fieldval field="trtBonus" value="2"/>

perform field[trtBonus].modify[+,#trait[attrVig],"Half Vigor"]

We can now go through all the places in the data files where we modify the bonus for these four traits, converting each to apply the tracked adjustment. For example, within the "thing_edges.dat" file, the "Berserk" edge applies two separate adjustments to these traits. We need to change the penalty on the "trParry" trait to use the new adjustment macro and do the same for the bonus to the "trTough" trait. We can attribute both to the "Berserk" edge, yielding a new script that looks similar to the one below.

if (field[abilActive].value = 0) then
  perform #traitadjust[trParry,-,2,"Berserk"]
  #traitroll[skFighting] += 2
  perform #traitadjust[trTough,+,2,"Berserk"]
  endif

Go through the data files and locate all instances where the derived traits are being modified. Every instance should be modified to use the new "#traitadjust" macro that logs what adjustment was applied. Be sure to also track the effects of equipped weapons and shields on the Parry trait, as well as the effects of equipped armor on the Toughness trait.

Report the History for Derived Traits

The derivation history should now be getting properly synthesized for each derived trait, so all we need to do now is make that history accessible to the user. Open the file "tab_basics.dat" and locate the "baTrtPick" template that is used to display the various derived traits. Within the template, the "details" portal shows the final value for the trait, and a MouseInfo script is defined that currently just outputs "???".

We can change the script to report the adjustment history for the "trtBonus" field. This is achieved by using the "history" target reference on the field, specifying a suitable separator between each entry. We also want to be sure that the starting value is shown for each derived trait. The derivation details will now be available to the user by simply moving the mouse over the value. The revised portal should look like the one shown below.

<portal
  id="details"
  style="lblLarge">
  <label>
    <labeltext><![CDATA[
      @text = field[trtDisplay].text
      ]]></labeltext>
    </label>
  <mouseinfo mousepos="middle+above"><![CDATA[
    @text = field[trtBonus].history[", ",start]
    ]]></mouseinfo>
  </portal>