Parse for dice and dice callback features

[Zkaij]

I've been unable to find information to help me understand exactly how the dice callback option works, in particular, what the appropriate return format is when multiple die expressions should be extracted. I've looked at the relevant section of the readme, but this doesn't explain how it renders the results. For one, from looking at the HP/HD field, it seems like the die expression is added in brackets after the die expression. Could we get more documentation about using the dice callback feature, and how it works?

Additionally, it seems like there are some important implementation details for automatic die parsing: for example, the to-hit roll reads '(Attack +X)' after the roll (rather than '(d20 + X)'). Is it possible to replace the (seemingly complex) automatic parsing which is applied to actions by using a dice callback?

I originally started looking into this because I wanted to remove the average result from the extracted attack roll, as well as add a missing space after the closing brackets: (the latter of which I see was fixed just four hours ago :P)

Edit: Seems like the text which is being replaced is what appears in the brackets ('Attack +X'; '1d6 + 2'; etc). Is this only how the automatic die parsing works?

[jyrodgers]

I've been playing around recently with the Dice Callback field. My goal has been to combine two values from the statblock body and atheletics add them and combine that sum with a 1d10 roll.
Here are the results of my tests. You can see that in test 6 I successfully got rollable dice equal to "1d20 + body + athletics" by composing a string in the text object.

My next step is to try and display the value of athletics ( or some text ) followed by the rollable dice equal to "1d20 + body + athletics". Any suggestions?

dice: 1d20 + 5

1. return 1d20
   • no result
2. return "1d20"
   • "1d20"
3. return [{ text: "1d20" }]
   • rollable dice of "1d20)"
4. return [{ text: "1d20 + 5" }]
   • rollable dice of "(1d20 + 5)"
5. return [{ text: "1d20 + " + monster["body"] }]
   • rollable dice of "(1d20 + 2)"
6. return [{ text: "1d20 + " + monster["body"] + " + " + monster["athletics"] }]
   • rollable dice of "(1d20 + 2 + 10)"
7. return [{ text: "(1d20)" }]
   • rollable dice of "((1d20))"
8. return [{ text: "myText; (1d20)" }]
   • "myText; (1d20)"
9. return "text: " + [{ text: "1d20 + " + monster["body"] + " + " + monster["athletics"] }]
   • "text: object Object"

[Zkaij]

If you look at the callback function in the Hit Points field of the default 5e layout, you can see that it pretty much matches 'test' 5 (but with property only), resolving to 3. or 4 based on the value. From what I can tell, there's no way to return text surrounding a die roll.

[valentine195]

Yes, the automatic dice parsing looks for specific text patterns to replace with dice.

The dice callback expects you to return an array of strings or objects, that it will then combine into a combination of text and dice rollers.

The object is:

interface DiceCallbackObject {
    text: string //string to be parsed into a dice roll
    original?: string //optional. will be placed after the dice roll in parenthesis
}

For example:

return ["The monster has: ", { text: "1d20 + 2" }];

will result in "The monster has <dice roll 1d20 + 2>"

also, yeah, there’s no documentation around this, sorry!

[Zkaij]

This is perfect, thank you! Would you mind putting some version of this in the dice callback section of the Readme for others? That the functions should return (arrays of) strings or objects with this pattern would be sufficient.

Having just tried this, I'm having some trouble getting it to work. While I was able to get a die working with the |text modifier in a new property line, |none didn't work (the average result still was there to start), and in both cases, the die created two status messages per roll, the above one being "Average", and the die result in the block remaining so (in the tooltip as well, just reading 'Average').

Minor question perhaps not worth its own discussion: as the 'Enable Export to PNG' option supposed to be tied to the 'Integrate Dice Roller' option? I tried to disable the former and found that it disabled the latter; then re-enabling the latter enabled the former!

[valentine195]

The dice callback doesn’t really support the full fledged dice roll syntax. It uses the DR engine under the hood to generate a basic dice roller from the formula directly, it doesn’t pass it through the lexer.

[valentine195]

But yea the documentation needs work!