The Structure of a Custom Roll Parsing Function

In this post, we’ll see how Custom Roll Parsing is constructed, using a simple example. In the later posts, we’ll see how to build in this structure to create more complex rolls.

When you run a custom roll parsing function, here are the steps the code runs through:

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

This procedure can be very quick – some steps might be skipped or be handled seamlessly. But you also have the ability to step in at any point and do things. This series will show you how to do that.

The Simple Example

Let’s say you want to roll 3d6. The easiest way to do this would be with a roll button. You could do this:

<button type="roll" name="roll_simple" value="/roll 3d6">3d6<button>Code language: HTML, XML (xml)

Or if you wanted the output to look a bit prettier, maybe you’d do this:

<button type="roll" name="roll_simple" value="&{template:default} {{name=Simple Roll}} {{roll=[[3d6]]}}">3d6<button>Code language: HTML, XML (xml)

If you are creating such a simple roll, this is better than Custom Roll Parsing. But let’s show what that would take as CRP.

Custom Roll Parsing Example

First we create the action button. Remember, it needs a unique name.

<button type="action" name="act_simple">3d6<button>Code language: HTML, XML (xml)

Notice that the action button doesn’t include the roll expression. You need to include that in the startRoll function.

We have created the button, now we need a sheet worker. Here are both versions of the roll.

on('clicked:simple', () => {
  startRoll('/roll 3d6', roll => {

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

on('clicked:simple', () => {
  startRoll('&{template:default} {{name=Simple Roll}} {{roll=[[3d6]]}}', roll => {
    finishRoll(roll.rollId);
  });
});Code language: JavaScript (javascript)

This starts like any normal action button worker, with clicked:button-name. Then we have a startRoll function – here we declare the roll string, and create a variable name. Here I’ve used roll. The official example (shown at the wiki) uses results, but this can create confusion as you’ll see later. It’s best to choose a unique name that matches what your roll is for. I could have used roll_3d6, or simple_roll_example, or anything that is a valid JavaScript variable name. I tend to use roll when I’m not sure what to call it.

Then you need a finishRoll function which uses the name you just created, and the .rollId key. You must include this in this format. Remember the roll name in startRoll and finishRoll must match. For example:

on('clicked:simple', () => {
  startRoll('/roll 3d6', simple_test_roll => {
    finishRoll(simple_test_roll.rollId);
  });
});Code language: JavaScript (javascript)

More Complex Rolls

You can use this method to create any kind of roll that is possible with the Roll20 dice mechanics. For example:

on('clicked:simple', () => {
  startRoll('/roll {1d10,1d8,1d6}kh1', simple_test_roll => {
    finishRoll(simple_test_roll.rollId);
  });
});Code language: JavaScript (javascript)

As you’ll see in upcoming posts, you can make rolls that are far more complex than are posisble with those mechanics.

Future Posts

You can create simple CRP rolls using the post above. In the following weeks, there’ll be two posts per week. One will describe a topic like those blow, and one will describe how to create a roll for a specific system using techniques described up to that week.

The topics covered will include:

The Roll String and Many-to-One Buttons

You need to create a string for your roll, just as you do with a Roll Button. Since it is placed in the startRoll function, you can manipulate it in your function. This creates the opportunity to make a single sheet worker that can handle many different action buttons. Instead of a dozen roll buttons for a dozen rolls, you might have a single sheet worker that handles those dozen rolls.

The startRoll Object

When run, the startRoll function rolls your dice. The variable you define (whether you call it roll, simple_start_roll, or whatever) contains all the properties of the roll. So if you rolled 3d6, it’ll tell you that you rolled 3d6, what each die was, and what they totalled to.

So you need to be able to analyse the properties of a dice roll. We’ll look at how you do that.

Spending Resources and Changing Attributes

We’ll also look at how you can make changes to attributes at the same time as a roll is made. Maybe you’re shooting a bow and expending ammunition or casting spells and marking off spell level slots. Maybe you expend a resource only if you fumble a roll, or spending an ammount of mana based on the effect of your roll. The possibilities are endless.

The finishRoll Function and Roll Templates

Not surprisingly, the startRoll function starts the roll, and finishRoll finishes it. After a roll is triggered, you can write code which intercepts that roll and does things with it, then the finishRoll function posts the roll to chat (possibly through a roll template).

In a coming post, we’ll see how you can do things that weren’t possible before, and create complex output. The more advanced features of CRP are only possible with a roll template. You can use the default roll template, or create your own custom template – whichever is most fitting.

Conclusion

In the coming posts, we’ll see how you can do many things that weren’t possible before.Get ready to unlock the potential of Custom Roll Parsing.