Rolling Dice

At the core of most tabletop games is the requirement to roll dice. This page details the support for various dice macros which are provided by Foundry VTT. The software has a rich underlying API

Basic Rolls

For basic dice rolls, you and your players will most frequently type a formula in chat which is automatically parsed and evaluated to display a dice roll result. Dice roll formulas begin with either /roll or /r for short. The syntax for a basic roll imitates common RPGs where /roll ydX would roll an X-sided die y times. For example, to roll five six-sided dice (d6):

/roll 5d6

Dice rolls also accept modifiers after the roll which alter the behavior of the group of rolled dice. In general, roll modifiers work by adding extra syntax on to the end of the roll, /roll ydX{mods}.

Keep or Drop Results

A desired number of high or low rolls may be kept or dropped using the following roll modifiers.

  • kh{N} Keep the highest N dice out of the group that were rolled.
  • kl{N} Keep the lowest N dice out of the group that were rolled.
  • dh{N} Drop the highest N dice out of the group that were rolled.
  • dl{N} Drop the lowest N dice out of the group that were rolled.

Re-roll Certain Results

Specific results may be re-rolled by specifying a re-roll target or range.

  • r{y} Re-roll any dice where the result was y.
  • r>{y} Re-roll any dice where the result was greater than y.
  • r>={y} Re-roll any dice where the result was greater than or equal to y.
  • r<{y} Re-roll any dice where the result was less than y.
  • r<={y} Re-roll any dice where the result was less than or equal to y.

Explode Certain Results

“Exploding” dice are supported where further dice of the same type are rolled until no more results of a certain value have been rolled.

  • x{y} Roll an additional dice each time a die rolls y.
  • x>{y} Roll an additional dice if any dice rolls greater than y.
  • x>={y} Roll an additional dice if any dice rolls greater than or equal to y.
  • x<{y} Roll an additional dice if any dice rolls less than or equal to y.
  • x<={y} Roll an additional dice if any dice rolls less than or equal to y.

Count Successes

You can roll a set of dice and count the number of times a certain result or range of results was achieved.

Warning

This is still TO-DO. The planned syntax is described below but not yet added

  • s{y} Count the number of dice which resulted in y.
  • s>{y} Count the number of dice which rolled greater than y.
  • s>={y} Count the number of dice which rolled greater than or equal to y.
  • s<{y} Count the number of dice which rolled less than or equal to y.
  • s<={y} Count the number of dice which rolled less than or equal to y.

Dice Roll 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.

class Roll(formula, data)

This class provides the basic 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
Returns:

Roll – An evaluated Roll object

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]

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

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

A flag for whether the Roll object has been rolled

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("4d8 + 4 + 2d4", 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.result

type: String

The result of all rolled formula parts

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(chatOptions)

Post a Roll instance to the chat log, converting it to a chat message.

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

Express the total result of the roll