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
- .averageTotal ⇒
- static
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 invalidRequiredArgumentError
notation is requiredTypeError
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
});
number
diceRoll.averageTotal ⇒ The average possible total for the notation.
Kind: instance property of DiceRoll
Since: 4.3.0
number
diceRoll.maxTotal ⇒ The maximum possible total for the notation.
Kind: instance property of DiceRoll
Since: 4.3.0
number
diceRoll.minTotal ⇒ The minimum possible total for the notation.
Kind: instance property of DiceRoll
Since: 4.3.0
string
diceRoll.notation ⇒ The dice notation.
Kind: instance property of DiceRoll
string
diceRoll.output ⇒ String representation of the rolls
Kind: instance property of DiceRoll
Example
2d20+1d6: [20,2]+[2] = 24
Array.<(ResultGroup|RollResults|string|number)>
diceRoll.rolls ⇒ The dice rolled for the notation
Kind: instance property of DiceRoll
number
diceRoll.total ⇒ The roll total
Kind: instance property of DiceRoll
string
| null
diceRoll.export([format]) ⇒ 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 |
boolean
diceRoll.hasExpressions() ⇒ Check whether the DiceRoll has expressions or not.
Kind: instance method of DiceRoll
Returns: boolean
- true
if the object has expressions, false
otherwise
boolean
diceRoll.hasRolls() ⇒ Check whether the object has rolled dice or not
Kind: instance method of DiceRoll
Returns: boolean
- true
if the object has rolls, false
otherwise
Array.<RollResults>
diceRoll.roll() ⇒ 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
Object
diceRoll.toJSON() ⇒ Return an object for JSON serialising.
This is called automatically when JSON encoding the object.
Kind: instance method of DiceRoll
string
diceRoll.toString() ⇒ 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
DiceRoll.import(data) ⇒ 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=');