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

type: String

The cleaned formula

Roll.fromMessage(message)

Parse a chat message into a roll formula by removing the initial roll prefix.

Arguments:
  • message (String) – A chat message starting with “/roll” or “/r”
Roll.parts

type: Array

An array of parsed formula parts

Roll.result

type: String

The parsed and evaluated formula converted back to a final string

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

type: Number

The cumulative numeric result of the entire rolled formula