Dice Rolling API

For mod developers, you may want to customize in-depth the behavior of dice rolling. You can interact directly with the Roll API by creating instances of the Roll() class.


The Roll Interface

Most frequently when dispatching or executing dice rolls, you will want to use the Roll() API directly, which handles the parsing of dice syntax, the evaluation of dynamic attributes and more.

class Roll(formula, data)

This class provides an interface and API for conducting dice rolls. The basic structure for a dice roll is a string formula and an object of data against which to parse it.

Arguments:
  • formula (String) – The string formula to parse
  • data (Object) – The data object against which to parse attributes within the formula

Examples:

// Attack with advantage!
let r = new Roll("2d20kh + @prof + @strMod", {prof: 2, strMod: 4});

// The parsed components of the roll formula
console.log(r.parts);    // [Die, +, 2, +, 4]

// Execute the roll
r.roll();

// The resulting equation after it was rolled
console.log(r.result);   // 16 + 2 + 4

// The total resulting from the roll
console.log(r.total);    // 22
Roll._formula

type: String

The original provided formula This formula will be reinterpreted once components have been parsed

Roll._parseOptions(query)

Parse options and determine their order of operations

Arguments:
  • query (String) – The dice roll options query
Roll._result

Cache the rolled total to avoid re-evaluating it multiple times

Roll._total

Cache the evaluated total to avoid re-evaluating it

Roll.alter(add, multiply)

Alter the Roll formula by adding or multiplying the number of dice included in each roll term

Arguments:
  • add (Number) – A number of dice to add to each Die term
  • multiply (Number) – A multiplier for the number of dice in each Die term

Examples:

let r = new Roll("4d8 + 4 + 2d4");
r.alter(1, 2);
r.formula;
> 9d8 + 4 + 5d4
Roll.data

type: Object

The original provided data

Roll.dice

type: Array

Get an Array of any Die() objects which were rolled as part of the evaluation of this roll

Roll.formula

Express the Roll as a formatted string formula

Roll.fromJSON(json)

Recreate a Roll instance using a provided JSON string

Arguments:
  • json (String) – Serialized JSON data representing the Roll
Returns:

Roll – A revived Roll instance

Roll.getActorData()

Acquire data object representing the most-likely current actor. This data can be included in the invocation of a Roll instance for evaluating dynamic attributes.

Returns:Object – An object of data representing the current Actor (if any)
Roll.getTooltip()

Render the tooltip HTML for a Roll instance

Returns:Promise.<HTMLElement>
Roll.parts

type: Array

An array of evaluate Roll parts

Roll.render(chatOptions)

Render a Roll instance to HTML

Arguments:
  • chatOptions (Object) – An object configuring the behavior of the resulting chat message.
Returns:

Promise.<HTMLElement> – A Promise which resolves to the rendered HTML

Roll.reroll()

Create a new Roll object using the original provided formula and data Each roll is immutable, so this method returns a new Roll instance using the same data.

Returns:Roll – A new Roll object, rolled using the same formula and data
Roll.result

The resulting arithmetic expression after rolls have been evaluated

Roll.rgx

Regular expression patterns

Roll.roll()

Execute the Roll, replacing dice and evaluating the total result

Returns:Roll – The rolled Roll object, able to be chained into other methods

Examples:

let r = new Roll("2d6 + 4 + 1d4");
r.roll();
> 12
Roll.terms

type: Array

An array of parsed formula terms

Roll.toJSON()

Structure the Roll data as an object suitable for JSON stringification

Returns:Object – Structured data which can be serialized into JSON
Roll.toMessage(chatData)

Dispatch a Roll instance to a new ChatMessage entity

Arguments:
  • chatData (Object) – The data object to use when creating the message
Returns:

Promise.<ChatMessage> – A promise which resolves to the created Chat Message

Roll.total

Express the total result of the roll and cache the result to avoid re-evaluating


The Basic Die

There may be cases where you want more fine-grained control over dice rolling. In such cases, you can also create instances of the base Die() class directly.

class Die(faces)

The base Die class.

Each Die instance represents a distinct term in a roll equation which transacts rolls of an die with some number of faces. The Die instance provides controls for rerolling, exploding, counting, or modifying the set of results from the Die.

Arguments:
  • faces (Number) – The number of faces for this Die

Examples:

// Define a 6-sided die
let die = new Die(6);

// Roll the die 4 times
die.roll(4);

// Roll another 2 times, adding the new results to the existing set
die.roll(2);

// For all 6 of the initial rolls, reroll if any result was a 1
die.reroll([1]);

// For set of remaining results, roll a bonus die if any result was a 6
die.explode([6]);

// Count the total number of rolls which was greater than 3
die.countSuccess(3, ">");

// Display the total number of successes
console.log(die.total);
Die.countSuccess(target, operator)

Map results to 0 or 1 depending on whether they match a success condition

Arguments:
  • target (Number) – The target result to test against
  • operator (String) – The comparison operator against which to test. Default is ‘>=’

Examples:

let die = new Die(3);
die.roll(6);               // Roll 6d3
console.log(die.results);  // [1,3,1,2,2,3]
die.countSuccess(3);       // Count the results where a 3 was rolled
console.log(die.results);  // [0,1,0,0,0,1]
console.log(die.total);    // 2
Die.explode(range)

Explode the rolls in this set by rolling additional dice for each roll which achieved a certain result Dice which have been re-rolled or have already exploded cannot explode

Arguments:
  • range (Array) – The range of target results which would trigger an explode
Returns:

Die – The updated die containing new rolls

Examples:

let die = new Die(8);
die.roll(6);               // Roll 6d8
console.log(die.results);  // [8,3,6,4,2,7]
die.explode([7,8]);        // Explode on 7s and 8s, rolling additional dice
console.log(die.results);  // [8,3,6,4,2,7,7,2,3]
Die.faces

type: Number

The number of faces for this Die

Examples:

let die = new Die(6);    // A 6-sided die has six faces
console.log(die.faces)   // 6
Die.keepHighest(n)

Filter the result set, keeping the highest n results in order

Arguments:
  • n (Number) – The number of results to keep
Returns:

Die – The updated die containing new rolls

Examples:

let die = new Die(6);
die.roll(4);               // Roll 4d6
console.log(die.results);  // [6,2,1,5]
die.keepHighest(2);        // Keep the best 2 results
console.log(die.results);  // [6,5]
Die.keepLowest(n)

Filter the result set, keeping the lowest n results in order

Arguments:
  • n (Number) – The number of results to keep
Returns:

Array – The filtered results

Examples:

let die = new Die(6);
die.roll(4);               // Roll 4d6
console.log(die.results);  // [6,2,1,5]
die.keepLowest(3);         // Kepe the lowest 3 results
console.log(die.results);  // [2,1,5]
Die.options

Any additional options which may be required by the Die

Die.reroll(targets)

Re-roll any results with results in the provided target set Dice which have already been re-rolled will not be re-rolled again

Arguments:
  • targets (Array) – Target results which would trigger a reroll
Returns:

Die – The updated die containing new rolls

Examples:

let die = new Die(4);
die.roll(3);               // Roll 3d4
console.log(die.results);  // [1,3,4]
die.reroll([1,2]);         // Re-roll 1s or 2s
console.log(die.results);  // [3,4,2]
Die.results

type: Array

Track the set of kept results out of all rolls

Examples:

let die = new Die(6);
die.roll(6);               // Roll 6d6
console.log(die.results);  // [6,4,1,2,3,4]
die.keepHighest(2);        // Keep the 2 best results
console.log(die.results);  // [6,4]
Die.roll(nd)

Roll the initial set of results for the Die

Arguments:
  • nd (Number) – The number of times to roll the die
Returns:

Die – The updated die containing new rolls

Examples:

let die = new Die(6);
die.roll(6);               // Roll 6d6
console.log(die.results);  // [5,2,4,4,1,6]
console.log(die.total);    // 22
Die.rolls

type: Array

Track all dice which have ever been rolled

Examples:

let die = new Die(4);
die.roll(4);             // Roll 4d4
console.log(die.rolls);  // [{...}, {...}, {...}, {...}]
Die.sides

type: Array

An Array representing the faces of the die

Examples:

let die = new Die(6);    // One side for each of the possible faces
console.log(die.sides)   // [1,2,3,4,5,6]
Die.total

type: Number

The sum of all kept results

Examples:

let die = new Die(20);
die.roll(2);               // Roll 2d20
console.log(die.results)   // [6,17]
console.log(die.total)     // 23