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

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
ParamTypeDescription
notationstring | ObjectThe notation to roll
notation.notationstringIf `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

ParamTypeDefaultDescription
[format]exportFormatsexportFormats.JSONThe 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
ParamTypeDescription
dataObject | stringThe data to import
data.notationstringIf 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=');