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:'rust'})

Arguments

Argument	Type	Default Value	Description
notation	string | array | notation object | array of notation objects	n\a	See notation description
options	object	see options	options 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

Key	Type	Default Value	Description
theme	string - optional	undefined	the systemName of a theme for the roll. This value will override theme values that appear in the notation object
newStartPoint	boolean - optional	true	will toss the collection of 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

Argument	Type	Default Value	Description
notation	string | array | notation object | array of notation objects	n\a	Same as roll notation description
options	object	see roll options	options 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

Argument	Type	Default Value	Description
notation	notation object | array of notation objects	n\a	See notation note below. Valid notation includes objects returned from roll and add promises.
options	object	see options	options 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

Key	Type	Default Value	Description
remove	boolean - optional	false	indicates the die being rerolled should be removed from the scene
newStartPoint	boolean - optional	true	will toss the collection of 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

Argument	Type	Default Value	Description
notation	notation object | array of notation objects	n\a	Same 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. If a className is provided, then it will be added to the <canvas> element in order to enable a CSS based transition. If no className is provided then visibility is toggled off without an effect.

diceBox.hide(className:string)

Arguments

Argument	Type	Default Value	Description
className	string	n\a	Sets a CSS class on the canvas in order to use CSS transition effects for hide.

Show

This will show the canvas element that the Dice-Box is rendered to. If a className was defined on hide() then this class name will be removed from the canvas to reverse the hide effect. Otherwise visibility is toggled on.

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 immediately, but theme/dice color changes will only take effect before or after a roll.

diceBox.updateConfig({configObject})