@3d-dice/dice-parser-interface

Dice Parser Interface

This module simply provides an interface between @3d-dice/dice-roller-parser and @3d-dice/dice-box. Since dice-roller-parser is a fork of another person's module, I did not want to include this interface in that package.

_{FDP (Fantastic Dice Parcer) has been renamed to Dice Parser Interface for symantics. The @3d-dice/fdp npm module has been depricated}

What it does

This module allows for more advanced rolls with dice-box. All the rolls supported are documented at Roll20 Dice Specification

How to use it

Install the library using:

npm install @3d-dice/dice-parser-interface

Then create a new instace of dice-parser-interface

import DiceParser from '@3d-dice/dice-parser-interface'

const DP = new DiceParser()

The DP class now has methods to parse raw notations, process re-rolls and compute the final results from dice-box

<form id="dice-to-roll">
  <input id="input--notation" class="input" placeholder="2d20" autocomplete="off" />
</form>

const form = document.getElementById("dice-to-roll")
const notationInput = document.getElementById("input--notation")

const submitForm = (e) => {
  e.preventDefault();
    const notation = DP.parseNotation(notationInput.value)
}

form.addEventListener("submit", submitForm)

Methods

parseNotation(string, default: '')

Accepts a dice string input, parses it and returns a JSON representation of the parsed input.

Example: DP.parseNotation('4d6')

[
  {
    "qty": 4,
    "sides": 6,
    "mods": [],
    "rolls": [
      {
        "sides": 6,
        "groupId": 0,
        "rollId": 0,
        "id": 0,
        "theme": "sunset",
        "result": 1
      },
      {
        "sides": 6,
        "groupId": 0,
        "rollId": 1,
        "id": 1,
        "theme": "sunset",
        "result": 3
      },
      {
        "sides": 6,
        "groupId": 0,
        "rollId": 2,
        "id": 2,
        "theme": "sunset",
        "result": 6
      },
      {
        "sides": 6,
        "groupId": 0,
        "rollId": 3,
        "id": 3,
        "theme": "sunset",
        "result": 6
      }
    ],
    "value": 16
  }
]

See also: Just parse the value

handleRerolls(array, default:[])

This method accepts an array of dice rolls (generated by parseNotation, updated by dice-box) and returns a new array of dice objects that need to be re-rolled. Examples of rolls that could generate rerolls include, exploding, penetrating, and compounding rolls (e.g.: 6d6!). Reroll and reroll-once notation is also supported (e.g.: 2d12r1).

Dice Object:

Property	Type	Description
groupId	int	The group the reroll target belongs to
rollId	int or string	The roll id of the die being rerolled. This will be incremented by .1 for every reroll made
side	int	The number of sides the reroll die has
qty	int	The number of dice to be rolled. This will always be 1 on rerolls but is needed by dice-box

Example:

[
  {
    "groupId": 0,
    "rollId": "2.1",
    "sides": 6,
    "qty": 1
  },
  {
    "groupId": 0,
    "rollId": "3.1",
    "sides": 6,
    "qty": 1
  }
]

parseFinalResults(array, default: [])

After all rolls and rerolls have completed, you can pass the results object to parseFinalResults to get the final results of the dice roll. This typically happens inside dice-box's onRollComplete callback method.

Example:

const results = DP.parseFinalResults(results)

Putting it all together

Example HTML

Example JavaScript

Caveats

One thing this modules does not do is provide the interface for providing an input for the roll notation string or displaying the final results. It is expected that the developer will create their own inputs and outputs or use modules from @3d-dice/dice-ui