@3d-dice/dice-parser-interface
v0.2.1
Published
a parser interface that parses roll20 format strings using @3d-dice/dice-roller-parser for @3d-dice/dice-box
Downloads
860
Maintainers
Readme
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