Computed Properties and CRP Roll Templates

I have described Custom Roll Parsing as taking these steps.

1. First, you click the button or trigger the ability linked to that button.
2. The sheet worker now starts to run. It might have a getAttrs phase, and might do some normal sheet worker stuff. This is often when the roll string is constructed (as described earlier).
3. The startRoll function runs, and makes the roll described in your roll string. The result of that roll isn’t sent to chat yet. First, a roll object is created, which contains properties for the completed roll.
4. You can now examine the roll that was just made, extract dice from it, do whatever you want with it. You might make changes to the roll, and store them in variables here.
5. Now the finishRoll function runs, taking the roll just made and any extra details you have created, and sends them to a roll template.
6. The roll template runs, and the modified result is sent to chat

The earlier posts have dealt with steps 1-3 and part of step 4. In this post we’ll do the rest. After this post we’ll be able to make any kind of Custom Roll Parser. In the month of november, we’ll post roughly two systems every week, demonstrating different aspects of CRP. For now, though, let’s describe the computed property.

Creating the Computed Property

Recall that a roll template has key/value pairs. For example:

&{template:example} {{name=My Name}} {{first roll=[[3d6]]}} {{second roll=[[4d6k3]]}}Code language: Markdown (markdown)

This roll has 3 key/value pairs. The keys are name, “first roll”, and “second roll”, and the values are “my name”, and the two rolls shown there.

So, each key has a value, which you can display in a roll template using {{ }} brackets, like this:

<rolltemplate class="sheet-rolltemplate-example">
   <div class="heading">{{name}}
   <div class="key">First Roll</div>
   <div class="value">{{first roll}}</div>
   <div class="key">Second Roll</div>
   <div class="value">{{second}}</div>
</rolltemplate>Code language: CSS (css)

So that’s a basic roll template that shows those keys and values. But with CRP, you can save an extra value4 for each key. You can save anything into the key, and do it in the finishRoll function, like this:

on('clicked:roll', () => {
   getAttrs(['character_name', 'str'], values => {
      const character = values.character_name;
      const str = +values.str || 0;
      const roll_string = '&{template:example} {{name=My Name}} {{first roll=[[3d6]]}} {{second=[[4d6k3]]}}';
      startRoll(roll_string, roll => {
          finishRoll(roll.rollId, {
              second: character,
              'first roll': str
          });   
      });
   });
});Code language: JavaScript (javascript)

So, here the last two keys have two values, one normal value and one hidden one. Something important to reaslise: you can only store computer values on keys that represent a roll. So we can’t use the name key, because its not a roll.

But also, there need be no relationship between the visible value qand the computed value. We aren’t using the hidden value for second, so we can use that for our extra key.

Using the Computed Property

You access the hidden value in the rolltemplate, using computed:: like this

<rolltemplate class="sheet-rolltemplate-example">
   <div class="heading">{{computed::second}}
   <div class="key">Strength</div>
   <div class="value">{{computed::first roll}}</div>
   <div class="key">First Roll</div>
   <div class="value">{{first roll}}</div>
   <div class="key">Second Roll</div>
   <div class="value">{{second}}</div>
</rolltemplate>Code language: CSS (css)

Use the computed:: keyword followed by the name of the key you are accessing.

Here we have a template chat disregards the visible name property, and replaces it with the hidden computed value of second, and displays the hidden value associated with first roll as well as that visible roll.

Notice that if the key contains a space, so does the computed value. But if you want to access that in javascript, you need to put quotes around it (see the finishRoll function.

finishRoll

When you have no computed values, you can simply use:

finishRoll(roll.rollId);Code language: JavaScript (javascript)

But if you have computed values, create an object after rollId to store them, like:

finishRoll(roll.rollId, {
   'name of key': 'computed value'
});Code language: JavaScript (javascript)

This is an object, so must be in this format. It’s best to do any calculations you need before the finishRoll function, and then call variables here.

const str_mod = Math.floor(str/2-5);
finishRoll(roll.rollId, {
   str: str_mod
});Code language: JavaScript (javascript)

Empty Keys

You are sometimes want to include more computed values than you have keys in your roll template. But you can create extra empty keys just to hold those values.

&{template:example} {{name=My Name}} {{first roll=[[3d6]]}} {{second roll=[[4d6k3]]}} {{three=[[0]]}} {{four=[[0]]}}Code language: Markdown (markdown)

Here we have created two extra keys, three and four, that won’t be used – but we can store extra computed values on them.

Concluding Comments

startRoll makes a roll, and lets you access that roll’s properties. Then finishRoll completes the roll, sending the original roll and any additions you make to a roll template.

This sequence allows you to make many modificates, and create a roll template top show any aspect of the roll that you want to. You can also use getAttrs and setAttrs to perform any of the normal stuff you’d do in a sheet worker. With all these things together, you can create all sorts of rolls and events.

In the next month, I’ll post a bunch of example systems so you can see how these are being used.

Series Navigation

<< Using Queries in Custom Roll ParsingCallbacks and Promises with startRoll >>