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._parseOptions(query)

Parse options and determine their order of operations

Arguments:
  • query (String) – The dice roll options query
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.parts

type: Array

An array of parsed formula 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 – A Promise which resolves to the rendered HTML

Roll.result

type: String

The result of all rolled formula parts

Roll.rgx

Regular expression patterns

Roll.roll()

Execute the Roll, replacing dice and evaluating the total result

Examples:

let r = new Roll("2d6 + 4 + 1d4");
r.roll();
> 12
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


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:

Array – The complete set of rolls

Examples:

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

type: Array

Track the index positions of rolls which have been exploded

Examples:

let die = new Die(6);
die.roll(6);               // Roll 6d6
console.log(die.rolls);    // [6,4,1,2,3,4]
die.explode([4]);          // Explode any 4s
console.log(die.exploded); // [1,5]
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:

Array – The filtered results

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.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:

Array – The complete set of rolls

Examples:

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

type: Array

Track the index positions of rolls which have been rerolled

Examples:

let die = new Die(6);
die.roll(6);               // Roll 6d6
console.log(die.rolls);    // [6,4,1,2,3,4]
die.reroll([1]);           // Reroll any 1s
console.log(die.rerolled); // [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.rolls);    // [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:

Array – The array of results

Examples:

let die = new Die(6);
die.roll(6);             // Roll 6d6
console.log(die.rolls);  // [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);  // [3,1,1,4]
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.rolls)   // [6,17]
console.log(die.total)   // 23