At the core of most tabletop games is the requirement to roll dice. Foundry VTT features an advanced framework for rolling dice, with support for a high level of customization and extensibility through the Dice API.

Regardless of Game System, any user can roll dice using simple chat commands entered into the chat entry field. Foundry Virtual Tabletop provides additional modifiers to the command structure which provide some extended functions, allowing for modifications like re-rolling certain results, keeping the highest (or lowest) results, and many more.


Roll Modes

Roll Mode and Types of Rolls

Before learning to roll dice, it is important to be familiar with the concept of "roll modes" which affect the visibility and presentation of dice rolls.

Every dice roll becomes a message in the chat log, but the visibility of that message and the details of the roll can be controlled by the user. At the bottom of the chat log there is a drop down list of roll types, these determine who can see the roll made by your /roll command.

Public Roll

This is the default type of roll in Foundry, and is visible to all players.

GM Roll

Rolls of this type are only visible to the player that rolled and any Game Master users. To perform a GM roll, use /gmroll or /gmr as the command prefix. A GM or the user who made the roll may choose to reveal this roll.

Blind Roll

A private dice roll only visible to Game Master users. The rolling player will not see the result of their own roll. This is similar to using a dice tower or other device at a physical tabletop where the roller may not get to see the outcome. To perform a blind roll, use /blindroll, /broll, or /br as the command prefix. Only the GM may choose to reveal this roll.

Self Roll

A private dice roll which is only visible to the user who rolled it. To perform a self roll, use /selfroll or /sr as the command prefix. Whether a GM or Player uses a self roll, only the user who made the roll can choose to reveal it.

A roll that is made in private (such as a Private GM Roll, Blind GM Roll, or Self Roll) may be revealed to the other users by right-clicking and choosing Reveal to Everyone.


Simple Roll Commandsback to top

A dice roll can be made by entering the /roll (or /r) chat command followed by some simple syntax to identify the number of dice, and which type of die you wish to roll. This roll command uses whichever Default Roll Mode is currently set by the user.

All of the example rolls on this page may be pasted directly into Foundry VTT exactly as they are, including commented text which will label the roll explaining what it does.

/r {number of dice}d{faces}
/r 5d20 # Rolls five twenty-sided dice, generating random numbers from 1 to 20, and outputting the sum of all rolls.
Described Rolls

Expanding Rolls

Once a roll has been made and appears in the chat log, users can click on that message to expand the results, showing the individual dice rolls that determined its outcome. Clicking the chat message a second time collapses the results again.

Describing Rolls

Users can add a text description to a roll by adding a # and desired text at the end of the /roll chat command. The text appears under the name of the user that made the roll.

/r {roll command} # {desired text}

Example: roll a 20-sided die, adding 2 to the result. Includ some text to describe the roll.

/r 1d20 + 2 # This is my roll!

Describing Dice

In addition to whole rolls, individual rolls inside multiple roll commands can be commented to specify what the roll is for. This is most useful in games where one or more types of die combine to deliver a total amount of damage.

/roll {roll}[desired text for roll]

Roll two six-sided dice with the tag of “slashing damage” followed by one eight-sided die with the tag of “fire damage.”

/roll 2d6[slashing damage]+1d8[fire damage]

Inline Rollsback to top

If a chat message contains a roll formula, Foundry VTT will automatically run the formula for the roll and place the result or command in the message with special style formatting. Anything that a regular roll command can do, an Inline Roll can do.

Inline rolls can also be used in a Journal Entry, or any other place that the TinyMCE Rich Text Editor appears, such as Item or Action description fields.

There are two types of inline roll:

Immediate Inline Rolls

These rolls are processed and the result of the roll is placed in the chat message. This is useful for including simple rolls inside of descriptive actions.

The boulders drop onto the player character, dealing [[2d12]] bludgeoning damage.

Deferred Inline Rolls

Deferred rolls provide a way to embed a button in your chat message which, when clicked by any user, makes a new roll containing that formula.

Can everyone roll a [[/roll 1d10]] for me?
Inline Rolls
Immediate and Deferred Inline Rolls

Using Simple Math with Rollsback to top

Most dice rolls result in a number that is the sum of any dice rolled, and simple math modifiers can be used to increase or decrease this result after rolls are made.

 /roll {number}d{faces}{math}{number}d{faces}

Roll one ten-sided die and add to it the result of rolling a single four-sided die.

/roll 1d10 + 1d4 + 4

Roll one twenty-sided die, divide the number by 2, then add 10 to the result.

/roll 1d20 / 2 + 10 

Roll a one hundred-sided die, that number by 2, then divide it the result of rolling a four-sided die.

/roll 1d100 * 2 / 1d4

Roll one twenty-sided die, and divide it by 3.

/roll 1d20 / 3

Adding Additional Dice

Using simple math, users can also add additional dice of different sizes to a roll. The above simple math expressions to determine how they are meant to interact. Math expressions can also be used to combine rolls of different dice types and add them together.

 /roll {number}d{faces}{math}{number}d{faces}

Roll one ten-sided die and add to it the result of rolling a single four-sided die.

/roll 1d10 + 1d4 + 4

Roll one twenty-sided die, divide the number by 2, then add 10 to the result.

/roll 1d20 / 2 + 10

Roll a one hundred-sided die, that number by 2, then divide it the result of rolling a four-sided die.

/roll 1d100 * 2 / 1d4

DnD 3.5e, Pathfinder - Critical Hit Multiplier: roll one eight-sided die, add 4 to the result, then multiply it by 2.

/r 1d8+4 * 2

Roll Modifiersback to top

In addition to basic arithmetic and adding text comments to rolls, there are a variety of short-hand modifiers which can be used to change the way a dice roll is processed. These modifiers are conditional, and only trigger in certain (defined) circumstances.

Re-rolls and Exploding Dice

r : Reroll
Rerolls the die based on the set condition, keeping the outcome regardless of whether it is better. Reroll (r) will only reroll the die once, for continual rerolling see “x : explode”
x : Explode
Rerolls a die continually based on the set condition, so that each occurrence of the number rolls again, continually adding to the total result.
xo : Explode Once
Rerolls a die once based on the set condition, used primarily by games which use a “dice pool”, adding to the total result.

Examples

Roll one ten-sided die, and re-roll it if the result is a 1.

/roll 1d10r1

Roll one twenty-sided die, and if the result is less than 10, re-roll it.

/r 1d20r<10

Roll five ten-sided dice, and if any of the individual results are a 10, roll another ten-sided die add the result to the total.

/r 5d10x10

Roll one twenty-sided die, rolling additional dice if the result is less than 10, until one of the dice is ten or better, which is the only result it will keep.

/r 1d20x<10kh

Roll six ten-sided dice, and roll one additional die for each 10 rolled, but do not re-roll 10s on the additional die, adding them to the total.

/r 6d10xo10

Chronicles of Darkness - Rote Rolls; roll five ten-sided dice, re-rolling any dice that fall under 8, and re-rolling any dice that score a 10, before counting the total successes in the roll.

/r 5d10xo<8x10cs>=8

Keeping or Dropping Resultsback to top

kh, k : Keep Highest
Whether you use 'kh' or the shorter 'k', this modifier causes the dice roller to keep a number of dice you specify, selecting the highest of the roll results available. Without a specified number it will keep the single highest number. If the number of dice rolled is less than the number of dice being kept, then it will keep all the rolls made.
kl : keep lowest
This modifier causes the dice roller to keep a number of dice you specify, selecting the lowest of the roll results available. Without a specified number it will keep the single lowest number. If the number of dice rolled is less than the number of dice being kept, then it will keep all the rolls made.
dl, d : drop lowest
This modifier causes the dice roller to drop a number of dice you specify, selecting the lowest of the roll results available. If a number of dice to drop is not specified, then it will drop the lowest number rolled. If the number of dice is less than the dice being dropped, then it will keep all the rolls made.
dh : drop highest
This modifier causes the dice roller to drop a number of dice you specify, selecting the highest of the roll results available. If a number of dice to drop is not specified, then it will drop the highest number rolled. If the number of dice is less than the dice being kept, then it will keep all the rolls made.

Examples

Roll three ten-sided dice, keeping the highest of the three.

/r 3d10k

Roll four six-sided dice, keeping the three highest rolls available.

/r 4d6k3

DND 5e - Advantage: Roll two twenty sided dice, and use the higher of the two for the final result which has 2 added to it.

/roll 2d20kh + 2

Roll three ten-sided dice, keeping the lowest of the three.

/r 3d10kl

Roll four six-sided dice, keeping the three lowest rolls available.

/r 4d6kl3

DND 5e -Disadvantage: Roll two twenty sided dice, and use the lower of the two for the final result which has 5 added to it.

/roll 2d20kl + 5

Roll three six-sided dice, dropping the lowest number rolled of the three.

/r 3d6d

Roll four ten-sided dice, dropping the two lowest numbers rolled.

/r 4d10d2

Roll three six-sided dice, dropping the highest number rolled of the three.

/r 3d6dh

Roll four ten-sided dice, dropping the two highest numbers rolled.

/r 4d10dh2

Successes and Failuresback to top

Count Successes
cs : Count Successes
This modifier causes each die that rolls a specified result to be counted as a success which is tallied when the roll concludes. Without a specified number to succeed, all dice rolled are considered successes. This modifier can have the requirements for success specified through several comparison symbols, as follows:
cs={y}
Count the number of dice which resulted exactly in y.
cs>{y}
Count the number of dice which rolled greater than y.
cs>={y}
Count the number of dice which rolled greater than or equal to y.
cs<{y}
Count the number of dice which rolled less than y.
cs<={y}
Count the number of dice which rolled less than or equal to y.
cf : Count Failures
The syntax of this modifier works identically to count success, but counts the number of dice that failed to meet the specified criteria.
df : Deduct Failures
This modifier is used to specify the criteria for a die result to be a failure, then deducts the number of failures from the dice result, counting each failure as -1. The criteria for failure are specified identically to count success. It is intended primarily for use with Count Success, but also functions on its own.
sf : Subtract Failures
This modifier sets a failure criteria, and any die that meets that criteria has its roll subtracted from the final result. The criteria for failure are specified identically to count success.
ms : Margin of Success
This modifier subtracts a target value set by the user from the result of the dice rolled, and returns difference as the final total. If the amount rolled is less than the target it outputs a negative number, and a positive number if there is a remainder after subtraction.

Examples

Roll ten twenty-sided dice, and count a success for each die which rolls a 20.

/r 10d20cs20

Roll ten twenty-sided dice and count a success for each die which rolls above a 10.

/r 10d20cs>10

Roll six ten-sided dice and count a success for each die which rolls a 6 or higher.

/r 6d10cs>=6

Roll a single one-hundred sided die and count a success if the result is 20 or lower.

/r 1d100cs<=20

World of Darkness - Dice vs Difficulty: roll five ten-sided dice, counting any roll of a 6 or higher as a success, while deducting a success for any roll that is a 1.

/r 5d10cs>=6df=1

Chronicles of Darkness - Dice vs Difficulty: Roll five ten-sided dice, counting a success for every die that rolls 8 or higher, and rolling an additional die any time a result of 10 is rolled.

/r 5d10cs>=8x=10

Chronicles of Darkness - 9 again and 8 again using exploding dice: roll five dice, counting a success for every die that rolls 8 or higher, and rolling an additional d10 any time a 9 or 10 is rolled.

/r 5d10cs>=8x>=9

Roll ten dice, counting a success for every die that rolls 8 or higher, and rolling an additional d10 any time an 8 or higher is rolled.

/r 10d10cs>=8x>=8

Rolls ten twenty-sided dice, and counts a failure for each die which rolls a 20.

/r 10d20cf20

Roll ten twenty-sided dice and count a failure for each die which rolls over a 10.

/r 10d20cf>10

Roll six ten-sided dice and count a failure for each die which rolls a 6 or higher.

/r 6d10cf>=6

Roll a single one-hundred sided die and count a failure if the result is 20 or lower.

/r 1d100cf<=20

Roll four six-sided dice, treating any roll of exactly 6 as a success, and removing 1 from the final result for each die that rolls a 1.

/r 4d6cs6df1

Roll ten ten-sided dice, treating any roll of 6 or better as a success, and removing 1 from the final result for each die which rolls a 1.

/r 10d10cs>5df1

Chronicles of Darkness - Chance Rolls: roll a single ten-sided die, counting a 10 as a success and a 1 as a failure.

/r 1d10cs=10df=1

Roll three six-sided dice, and subtract the value of any dice that roll lower than three.

/r 3d6sf<3

Roll three six-sided dice and subtract 10 from the final result.

/r 3d6ms10

Special Diceback to top

Special Dice

Foundry Virtual Tabletop also natively supports two special types of dice: Coins, and Fate Dice.

Coins

Coins are two-sided dice with two results: heads, or tails. They can be rolled as any other die, but are not affected by mathematical expressions, though they can still be combined with other dice types. Coins also allow the roller to call (c) a specific result in advance, which will treat rolling coins similarly to “count success”. By default, Coins tally the number of heads as successes in the results.

/roll 4dc # Flip four coins.
/roll 3dcc1 # Flip three coins and tally the number of coins that result in Heads
/roll 3dcc0 # Flip a number of coins and tally the number of coins that result in Tails

Fate Dice

Fate dice are six-sided dice that can roll a plus, minus, or blank face. They are used in the fudge and fate systems, and are rolled like any other dice in foundry, but are not affected by mathematical expressions, as their faces have no numerical values and are considered a zero.

/r 4df # Roll 4 fate dice, generating a random number of plus, minus, or blank results.

Parenthetical Expressions and Dice Poolsback to top

When a roll command includes Parenthesis ( ) and curly braces { }, Foundry VTT interprets these as instructions to handle the roll in particular ways. These expressions are evaluated first before other elements of hte roll formula.

Parentheses

The contents of a parenthetical expression are always evaluated before the outer portion.This allows for options where the number, faces, or modifiers of a dice roll are themselves dynamic in some way. Using parenthetical expressions can allow you to roll a variable number of dice based on a data attribute or an inner dice roll. Parenthetical expressions can also be used in conjunction with roll modifiers to allow checking a roll against a particular value. For example to count the number of successes relative to some target attribute or opposed dice roll.

Examples

Roll a single die with a number of sides randomly determined by a d20 roll.

/roll 1d(1d20)

Roll between two and eight d8.

/roll (2d4)d8

Roll a number of dice equal to the results of one roll of a 20-sided die multiplied by two, with a number of sides between 1 and 10.

/roll (1d20*2)d(1d10)

Count the number of success based on the selected token’s ‘power’ attribute.

/roll 3d12cs<=(@attributes.power)

Get the margin of success based on an opposed roll of 4d6.

/roll 3d12ms>(4d6)

Dice Poolsback to top

Dice Pools allow you to evaluate a set of dice rolls and combine or choose certain results from the pool as the final total. This allows you to keep, combine, or count results across multiple rolled formulae. Dice pools are defined using comma separated roll terms within brackets.

Examples

Roll 4d6, 3d8, and 2d10, keep only the highest result.

/roll {4d6, 3d8, 2d10}kh

Roll one twenty sided die and the result can only be 10 or higher.

/roll {1d20, 10}kh # 

DND 5e - Reliable Talent: compare a die roll against a fixed number (10), selecting the higher of the two for the result. This can be accomplished with an enclosed die roll using the keep highest modifier. Roll one twenty-sided die, and use the higher of its result or the number 10, and add 5 to it.

/r {1d20,10}kh + 5

DND5e - Character Creation: roll a pool of ability scores when creating your character.

/roll {4d6kh3, 4d6kh3, 4d6kh3, 4d6kh3, 4d6kh3, 4d6kh3} # Character Ability Scores

Roll 6d6, 5d8, 4d10, 3d12 and count how many resolve to greater than 15.

/roll {6d6, 5d8, 4d10, 3d12}cs>15

SWADE - Wild Die: roll one eight-sided die and one six-sided die, both of which will roll additional dice of the same size if they roll their maximum value. Use the highest result of rolls.

/roll {1d8x, 1d6x}kh

Data Paths as Variablesback to top

Foundry VTT stores important values in the data for each Entity, regardless of its type. These data paths can be called within rolls in order to provide complex functionality and references to a selected character’s statistics and modifiers.

Understanding The Structure of Roll Data

Each game system has its own particular Data Paths which it defines. There are two ways to resolve what these data paths are which can be used via the Developer Tools console. The first method explores the evaluated roll-data object for a specific Actor.

const actor = game.actors.getName("My Character Name");
console.log(actor.getRollData());

The second method explores the defined game system data template for a certain Actor type.

game.system.model.Actor.<type of actor>

If used correctly, either of these commands will output a clickable list of the object data stored on every character which can be conveniently referenced with rolls using @the.path.to.data.

Using Data Paths as Variables

Once you know the structure of an actor, you can use them as part of any roll formula. When a roll formula resolves a data path variable, it automatically gets the data from the currently controlled token first, and if no token is controlled, gathers the data from whichever Actor has been chosen in the “Select Character” section of player configuration.

Data path variables can take the place of any number in any part of a roll formula.

For example in this screenshot from the dnd5e system, by rolling /roll 1d20 + @abilities.cha.mod you would perform a check of your selected token’s Charisma modifier.


Including Math Functionsback to top

One of the benefits of Foundry VTT’s robust API is that it exposes all of its dice rolling functions to the benefits of the JavaScript Math methods. For more about these methods, see here: Math Expressions. This allows users to leverage complex mathematical functions in their dice rolls.

Examples

Return the largest integer less than or equal to the result of a roll of 1d12 divided by 3.

/r floor(1d12/3)

Return the largest integer greater than or equal to the result of a roll of 1d12 divided by 3.

/r ceil(1d12/3)

Return the value of a roll of 1d12 divided by 3, rounded to the nearest integer in either direction.

/r round(1d12/3)

Return the absolute value of a roll where the result could be either positive or negative.

/r abs(5d6 - 20)

API Referencesback to top

For module and system developers who want to go deeper with dice mechanics - there is a robust JavaScript API which can do even more with dice rolls. See the Roll API documentation for details.


Frequently Asked Questionsback to top

How does Foundry Virtual Tabletop handle randomization?

Foundry utilizes a Mersenne Twister pseudorandom number generator for all of its dice rolls. It was originally developed in 1997 by Makoto Matsumoto and Takuji Nishimura to rectify most of the flaws found in older PRNGs.

It is fast, reliably random over long periods of usage, and easily implemented, which has led to its widespread use in numerous programming languages. In fact, this pseudorandom number generator is the most widely used general-purpose PRNG in existence, and widely viewed as the most reliable for use in dice and other gaming impelementations.

The Mersenne Twister utilizes a seed number that the internal mathematics use to determine the set of random numbers generated. In Foundry VTT, this seed is set at the time each user connects, giving them a unique set of rolls for the rest of that session.