Roll20 Wiki

Character Sheet Development
Getting Started

General

Reference

Tools & Tips

Git/GitHub

Other

Custom Roll Parsing (CRP) is a new capability for character sheets can now combine the functionality of roll buttons and action buttons to allow for a new custom roll parsing. It was release July 13th, 2021.^[1]

Parts

An action button
sheetworker to parse the roll sent with the action button
Changes to Roll Templates to display the roll

Currently you can only display computed values in the first 10 fields that are sent in the macro.

Example of CRP in use

The functions startRoll and finishRoll will allow sheet authors to access dice rolls and compute their own results for those rolls

Sheetworker Functions

Main Page: Sheetworkers

startRoll( roll, callback? ) (asynchronous)

This function accepts a roll as a string (generally a roll template string). The function will initiate a roll to the roll server, the results for which will be returned to the callback. The roll will wait for a corresponding finishRoll function call before posting the results to chat, however if the finishRoll call is not made within 5 seconds, the roll will be posted automatically. The results from the roll server will be an object containing the following properties

rollId: (string)

A unique identifier for this roll, required to finish the roll

results: (object)

An object containing the roll information from the roll server, where the keys are roll names and the values are an object containing the roll information, for example:

results: {
  roll1: {
      // The result of the roll, as calculated by the roll server
      result: 48,
      // An ordered array of the results of all dice in this roll
      dice: [9,9,20,4,4,1],
      // The original expression for this roll
      expression: ‘4d20+2d4’,
      // A breakdown of each “sub-roll” (each part of an expression is rolled separately)
      [
          {
              // The ‘4’ in ‘4d20’
              dice: 4,
              // The ‘20’ in ‘4d20’
              sides: 20,
              // Array of the results of each die
              results: [9,9,20,4]
          },
          …
      ]
  },
  …
}

finishRoll( rollId, computedResults? )

This function will finish a roll initiated with the startRoll function, and allow for adding computed results to each roll. The function requires the rollId from the startRoll function, and can accept an object, where the keys are roll names and the values are the computed results for that roll, as a string or an integer.

Roll Template Changes

Main Page: BCS/Roll Templates

To use the custom computed results in your roll templates, replace the roll names in the template with computed::<rollname>:

<rolltemplate class="sheet-rolltemplate-test">
    <div class="sheet-template-container">
        <h1>{{name}}</h1>
        <div class="sheet-results">
            <h4>Result = {{roll1}}</h4>
            <h4>Custom Result = {{computed::roll1}}</h4>
        </div>
    </div>
</rolltemplate>

When the roll is output to the chat, hovering the mouse over a custom result will display the quantum roll symbol, and the original results of each die.

In addition, the roll template functions rollTotal, rollGreater, rollLess, and rollBetween can use the computed result of a roll:

<rolltemplate class="sheet-rolltemplate-test2">
    <div class="sheet-template-container">
        <h1>{{name}}</h1>
        <div class="sheet-results">
            <h4>Result = {{roll1}}</h4>
            <h4>Custom Result = {{computed::roll1}}</h4>
            {{#rollTotal() computed::roll1 0}}
                <h5>Total 0!</h5>
            {{/rollTotal() computed::roll1 0}}
            {{#rollGreater() computed::roll1 1}}
                <h5>Greater Than 1!</h5>
            {{/rollGreater() computed::roll1 1}}
            {{#rollLess() computed::roll1 2}}
                <h5>Less Than 2</h5>
            {{/rollLess() computed::roll1 2}}
            {{#rollBetween() computed::roll1 1 3}}
                <h5>Between 1 and 3</h5>
            {{/rollBetween() computed::roll1 1 3}}
        </div>
    </div>
</rolltemplate>

Note that these roll template functions generally expect an integer value to compare, and attempting to use them to compare string values may not not work as expected.

Limitations

Only the first 10 properties passed can be accessed by Custom Roll Parsing

Computed values cannot be used as comparisons in roll template helpers

Only template properties that are rolls i.e wrapped with [[]] will be available in the results object. Attributes containing text only and passed as a roll can cause the startRoll to fail.

Example

Bringing all of these new elements together, here is an example of implementing this feature:

<button type="action" name="act_test">Click me</button>

<rolltemplate class="sheet-rolltemplate-test">
    <div class="sheet-template-container">
        <h1>{{name}}</h1>
        <div class="sheet-results">
            <h4>Result = {{roll1}}</h4>
            <h4>Custom Result = {{computed::roll1}}</h4>
        </div>
    </div>
</rolltemplate>

<script type="text/worker">
    on('clicked:test', (info) => {
        startRoll("&{template:test} {{name=Test}} {{roll1=[[1d20]]}}", (results) => {
            const total = results.results.roll1.result
            const computed = total % 4;

            finishRoll(
                results.rollId,
                {
                    roll1: computed
                }
            );
        });
    });
</script>