Skip to main content
Version: 0.6

Methods

Promised based rolls

The methods .roll(),.add(), .reroll() and .remove() are all methods that return a promise containing the results of the dice rolled by the callee. So it is possible to write diceBox.roll('4d6').then(results => console.log(results)). Results can also be retrieved from the onRollComplete callback event or by using the .getRollResults() method (not a promise).

Roll

A roll will clear current dice and start a new roll. Returns a promise with an array of die results

roll(notation:mixed, options = {theme:string, newStartPoint:boolean})

Example

diceBox.roll('2d20',{theme:'#4b8968'})

Arguments

ArgumentTypeDefault ValueDescription
notationstring | array | notation object | array of notation objectsn\aSee notation description
optionsobjectsee optionsoptions that can be set with each roll
Notation

The notation argument can accept the following roll formats

  1. simple string notation described as 'number of dice' + 'd' + 'number of sides on the die'. e.g.: 5d6 rolls five six-sided dice.
  2. an array of string notation. e.g.: ['2d10','2d6']
  3. a Roll Object as described above. e.g.:{qty: 5, sides: 10}
  4. an array of Roll Objects. e.g.:[{qty: 2, sides: 10},{qty: 1, sides: 6}] |
  5. a mixed array of Roll Objects and string notation. e.g.:[{qty: 2, sides: 10},'2d8']

Options

KeyTypeDefault ValueDescription
themestring - optionalundefineda named theme or HEX value for the roll. This value will override theme values that appear in the notation object
newStartPointboolean - optionaltruewill toss the dice in from a new point along the edge of the box
Themes

Themes can be specified in four different places. On the config object at initialization, as an options parameter when using .roll() or .add(), as specified in a roll object and as specified in a die result object. Themes are applied in the order of options parameter first, roll object or die result object second and box config option third. The roll object and die result object are processed at the same level.

Add

This method will add the specified notation to the current roll in a new roll group. Returns a promise with an array of die results for the dice that were added.

add(notation:mixed, options = {theme:string, newStartPoint:boolean})

Example

diceBox.add([{qty: 2, sides: 8},'1d6'],{newStartPoint: false})

Arguments

ArgumentTypeDefault ValueDescription
notationstring | array | notation object | array of notation objectsn\aSame as roll notation description
optionsobjectsee roll optionsoptions that can be set with each roll

Reroll

This method will reroll a die. Returns a promise with an array of die results for the dice that were rerolled.

reroll(notation:mixed, options = {remove:boolean, newStartPoint:boolean})

Example

diceBox.reroll({groupId: 0,rollId: 2})

Arguments

ArgumentTypeDefault ValueDescription
notationnotation object | array of notation objectsn\aSee notation note below. Valid notation includes objects returned from roll and add promises.
optionsobjectsee optionsoptions that can be set with each roll
note

The notation argument here requires an roll object or an array of roll objects identifying the roll group groupId and die rollId you wish to reroll. Die result objects from previous rolls are valid arguments and can be passed in to trigger a reroll.

Options

KeyTypeDefault ValueDescription
removeboolean - optionalfalseindicates the die being rerolled should be removed from the scene
newStartPointboolean - optionaltruewill toss the dice in from a new point along the edge of the box

Remove

Remove dice from the scene. Returns a promise with an array of die results for the dice that were removed.

remove(notation:mixed)

Example

diceBox.remove({groupId: 0,rollId: 2})

Arguments

ArgumentTypeDefault ValueDescription
notationnotation object | array of notation objectsn\aSame as reroll notation description

Clear

This will clear all dice from the scene.

diceBox.clear()

Hide

This will hide the canvas element that the Dice-Box is rendered to.

diceBox.hide()

Show

This will show the canvas element that the Dice-Box is rendered to.

diceBox.show()

Get Roll Results

Get the results of all the dice in the scene at anytime. However, if dice are still rolling they will not have a value yet.

diceBox.getRollResults() // returns an array of roll result objects

Update Config

Use this method to update any of the config settings. Most settings will be applied immediatly, but theme/dice color changes will only take effect before or after a roll.

diceBox.updateConfig({configObject})