Advanced Roller

The Advanced Roller module is a part of the @3d-dice/dice-ui package. This UI module provides a simple text input field and a clear button. The field is connect to Dice Parser Interface. On submit, the field will send the roll notation to FDP to be parsed and will return the result to the callback onSubmit. The clear button will clear out any values stored in the parser and invokes the onClear callback, which is usually a good place to clear your dice-box as well.

note

Advanced Roller only works with the following dice types: d4, d6, d8, d10, d12, d20, d100, dfate.

Install

Add the dice-ui module using

npm install @3d-dice/dice-ui

Setup

Then create a new instance of the roller

import { AdvancedRoller } from '@3d-dice/dice-ui'

const Roller = new AdvancedRoller()

Config Options

The AdvancedRoller only has one argument which is a config object

Option	type	default	Description
target	string :dom node selector	document.body	The target DOM node to inject the roller into
onSubmit	function	noop	callback triggered on form submit, after notation has been parsed
onClear	function	noop	callback triggered when form reset event is triggered
onReroll	function	noop	callback triggered when FDP returns reroll results
onResults	function	noop	callback triggered when there are no reRoll results and the final result object has been parsed by FDP

Methods

Method	Arguments	Description
submitForm	event :event - form submit	Take the submit event and passes the input notation to FDP. Calls onSubmit callback with results.
clear	none	Clears any values stored in FDP. Calls the onClear callback
handleResults	results :object	Passes roll results object to FDP to check for rerolls. Gets the final parsed results from FDP. Calls onResults callback

Custom Events

resultsAvailable

When the final results are available, a custom event called resultsAvailable is also dispatched. The final results object can be found on the event.details property.

Example

document.addEventListener('resultsAvailable', (e) => console.log('roll results: ', e.detail))

Callbacks

The advanced roller lets you decide what to do with the results the parser returns.

onSubmit

After the value of the notation input has been processed by FDP, this callback is triggered, passing back the notation object generated by FDP. This can then be passed onto Dice-Box for rolling.

Example

const Roller = new AdvancedRoller({
  target: '#roller',
  onSubmit: (notation) => {
    diceBox.roll(notation)
  }
})

onClear

After clearing out out any values remaining in FDP, this callback is trigger to allow for follow-up actions in the scene

Example

const Roller = new AdvancedRoller({
  target: '#roller',
  onSubmit: (notation) => {
    diceBox.roll(notation)
  },
  onClear: () => {
    diceBox.clear()
    Display.clear()  // Display refers to Display Results module available in @3d-dice/dice-ui
  }
})

onReroll

When the handleResults method is called FDP will parse rollResults looking for anything that would trigger a reroll. If the right conditions are met then DRP will return an array of dice objects that need a reroll. The array is then passed on to this callback to be handled as you see fit.

Example

const Roller = new AdvancedRoller({
  target: '#rollers',
  onSubmit: (notation) => {
    diceBox.roll(notation)
  },
  onClear: () => {
    diceBox.clear()
    Display.clear()
  },
  onReroll: (rolls) => {
    rolls.forEach(roll => diceBox.add(roll))
  }
})

onResults

This callback is triggered when the handleResults method has determined that there are no reroll results and the final result object has been parsed by FDP. The final result object is passed on to this callback to be handled as you see fit.

Example

const Roller = new AdvancedRoller({
  target: '#rollers',
  onSubmit: (notation) => {
    diceBox.roll(notation)
  },
  onClear: () => {
    diceBox.clear()
    Display.clear()
  },
  onReroll: (rolls) => {
    rolls.forEach(roll => diceBox.add(roll))
  },
  onResults: (results) => {
    Display.showResults(results)  // Display refers to Display Results module available in @3d-dice/dice-ui
  }
})