DiceRoll

DiceRoll

A DiceRoll handles rolling of a single dice notation and storing the result.

Kind: global class
See: DiceRoller if you need to keep a history of rolls

• DiceRoll
  • new DiceRoll(notation)
  • instance
    • .averageTotal ⇒ number
    • .maxTotal ⇒ number
    • .minTotal ⇒ number
    • .notation ⇒ string
    • .output ⇒ string
    • .rolls ⇒ Array.<(ResultGroup|RollResults|string|number)>
    • .total ⇒ number
    • .export([format]) ⇒ string | null
    • .hasExpressions() ⇒ boolean
    • .hasRolls() ⇒ boolean
    • .roll() ⇒ Array.<RollResults>
    • .toJSON() ⇒ Object
    • .toString() ⇒ string
  • static
    • .import(data) ⇒ DiceRoll

new DiceRoll(notation)

Create a DiceRoll, parse the notation and roll the dice.

If notation is an object, it must contain a notation property that defines the notation. It can also have an optional array of RollResults, in the rolls property.

Throws:

• NotationError notation is invalid
• RequiredArgumentError notation is required
• TypeError Rolls must be a valid result object, or an array

Param	Type	Description
notation	string | Object	The notation to roll
notation.notation	string	If `notation is an object; the notation to roll
[notation.rolls]	ResultGroup | Array.<(ResultGroup|RollResults|string|number)>	If notation is an object; the rolls to import

Example (String notation)

const roll = new DiceRoll('4d6');

Example (Object)

const roll = new DiceRoll({
  notation: '4d6',
  rolls: ..., // RollResults object or array of roll results
});

diceRoll.averageTotal ⇒ number

The average possible total for the notation.

Kind: instance property of DiceRoll
Since: 4.3.0

diceRoll.maxTotal ⇒ number

The maximum possible total for the notation.

Kind: instance property of DiceRoll
Since: 4.3.0

diceRoll.minTotal ⇒ number

The minimum possible total for the notation.

Kind: instance property of DiceRoll
Since: 4.3.0

diceRoll.notation ⇒ string

The dice notation.

Kind: instance property of DiceRoll

diceRoll.output ⇒ string

String representation of the rolls

Kind: instance property of DiceRoll
Example

2d20+1d6: [20,2]+[2] = 24

diceRoll.rolls ⇒ Array.<(ResultGroup|RollResults|string|number)>

The dice rolled for the notation

Kind: instance property of DiceRoll

diceRoll.total ⇒ number

The roll total

Kind: instance property of DiceRoll

diceRoll.export([format]) ⇒ string | null

Export the object in the given format. If no format is specified, JSON is returned.

Kind: instance method of DiceRoll
Returns: string | null - The exported data, in the specified format
Throws:

• TypeError Invalid export format

See: toJSON

Param	Type	Default	Description
[format]	exportFormats	exportFormats.JSON	The format to export the data as

diceRoll.hasExpressions() ⇒ boolean

Check whether the DiceRoll has expressions or not.

Kind: instance method of DiceRoll
Returns: boolean - true if the object has expressions, false otherwise

diceRoll.hasRolls() ⇒ boolean

Check whether the object has rolled dice or not

Kind: instance method of DiceRoll
Returns: boolean - true if the object has rolls, false otherwise

diceRoll.roll() ⇒ Array.<RollResults>

Roll the dice for the stored notation.

This is called in the constructor, so you'll only need this if you want to re-roll the notation. However, it's usually better to create a new DiceRoll instance instead.

Kind: instance method of DiceRoll
Returns: Array.<RollResults> - The results of the rolls

diceRoll.toJSON() ⇒ Object

Return an object for JSON serialising.

This is called automatically when JSON encoding the object.

Kind: instance method of DiceRoll

diceRoll.toString() ⇒ string

Return the String representation of the object.

This is called automatically when casting the object to a string.

Kind: instance method of DiceRoll
See: output

DiceRoll.import(data) ⇒ DiceRoll

Create a new DiceRoll instance with the given data.

data can be an object of data, a JSON / base64 encoded string of such data.

The object must contain a notation property that defines the notation and, optionally, an array of RollResults, in the rolls property.

Kind: static method of DiceRoll
Returns: DiceRoll - The new DiceRoll instance
Throws:

• DataFormatError data format is invalid

Param	Type	Description
data	Object | string	The data to import
data.notation	string	If notation is an object; the notation to import
[data.rolls]	Array.<RollResults>	If notation is an object; the rolls to import

Example (Object)

DiceRoll.import({
  notation: '4d6',
  rolls: ..., // ResultGroup object or array of roll results
});

Example (JSON)

DiceRoll.import('{"notation":"4d6","rolls":[...]}');

Example (Base64)

DiceRoll.import('eyJub3RhdGlvbiI6IjRkNiIsInJvbGxzIjpbXX0=');