Rolling Dice
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 rerolling certain results, keeping the highest (or lowest) results, and many more.
Table of Contents
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 rightclicking 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 twentysided dice, generating random numbers from 1 to 20, and outputting the sum of all 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 20sided 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 sixsided dice with the tag of "slashing damage" followed by one eightsided 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?
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.
+
adds the number that follows it to the sum of the roll.
subtracts the number that follows it from the sum of the roll.*
multiplies the sum of the roll by the number given./
divides the sum of the roll by the number given.
/roll {number}d{faces}{math}{number}d{faces}
Roll one tensided die and add to it the result of rolling a single foursided die.
/roll 1d10 + 1d4 + 4
Roll one twentysided die, divide the number by 2, then add 10 to the result.
/roll 1d20 / 2 + 10
Roll a one hundredsided die, multiply that number by 2, then divide it by the result of rolling a foursided die.
/roll 1d100 * 2 / 1d4
Roll one twentysided 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 tensided die and add to it the result of rolling a single foursided die.
/roll 1d10 + 1d4 + 4
Roll one twentysided die, divide the number by 2, then add 10 to the result.
/roll 1d20 / 2 + 10
Roll a one hundredsided die, that number by 2, then divide it the result of rolling a foursided die.
/roll 1d100 * 2 / 1d4
DnD 3.5e, Pathfinder  Critical Hit Multiplier: roll one eightsided 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 shorthand 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.
Rerolls 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 tensided die, and reroll it if the result is a 1.
/roll 1d10r1
Roll one twentysided die, and if the result is less than 10, reroll it.
/r 1d20r<10
Roll five tensided dice, and if any of the individual results are a 10, roll another tensided die add the result to the total.
/r 5d10x10
Roll one twentysided 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 tensided dice, and roll one additional die for each 10 rolled, but do not reroll 10s on the additional die, adding them to the total.
/r 6d10xo10
Chronicles of Darkness  Rote Rolls; roll five tensided dice, rerolling any dice that fall under 8, and rerolling 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 tensided dice, keeping the highest of the three.
/r 3d10k
Roll four sixsided 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 tensided dice, keeping the lowest of the three.
/r 3d10kl
Roll four sixsided 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 sixsided dice, dropping the lowest number rolled of the three.
/r 3d6d
Roll four tensided dice, dropping the two lowest numbers rolled.
/r 4d10d2
Roll three sixsided dice, dropping the highest number rolled of the three.
/r 3d6dh
Roll four tensided dice, dropping the two highest numbers rolled.
/r 4d10dh2
Successes and Failuresback to top
 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 twentysided dice, and count a success for each die which rolls a 20.
/r 10d20cs20
Roll ten twentysided dice and count a success for each die which rolls above a 10.
/r 10d20cs>10
Roll six tensided dice and count a success for each die which rolls a 6 or higher.
/r 6d10cs>=6
Roll a single onehundred sided die and count a success if the result is 20 or lower.
/r 1d100cs<=20
World of Darkness  Dice vs Difficulty: roll five tensided 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 tensided 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 twentysided dice, and counts a failure for each die which rolls a 20.
/r 10d20cf20
Roll ten twentysided dice and count a failure for each die which rolls over a 10.
/r 10d20cf>10
Roll six tensided dice and count a failure for each die which rolls a 6 or higher.
/r 6d10cf>=6
Roll a single onehundred sided die and count a failure if the result is 20 or lower.
/r 1d100cf<=20
Roll four sixsided 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 tensided 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 tensided die, counting a 10 as a success and a 1 as a failure.
/r 1d10cs=10df=1
Roll three sixsided dice, and subtract the value of any dice that roll lower than three.
/r 3d6sf<3
Roll three sixsided dice and subtract 10 from the final result.
/r 3d6ms10
Special Diceback to top
Foundry Virtual Tabletop also natively supports two special types of dice: Coins, and Fate Dice.
Coins
Coins are twosided 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 sixsided 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 20sided 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 twentysided 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 eightsided die and one sixsided 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 rolldata 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 generalpurpose 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.