At the core of most tabletop games is the requirement to roll dice. This page details the concepts and syntax used to execute dice rolls with Foundry VTT's specific roll formula syntax.

Roll Modes and Chat Commands

There are four different roll modes in Foundry Virtual Tabletop. Each roll mode implies a different level of visibility for the resulting roll. Every dice roll becomes a message in the chat log but the visibility of that message and the details of the roll vary for each mode. For every roll mode, all players will be able to see that a roll was performed - just as players at a physical tabletop can hear the audible sound of rolled dice - but depending on the roll mode they may not see the results. The available modes are:

Normal Roll

A "normal roll" is a public dice roll which is visible to all players. To perform a normal roll, use /roll or /r as the command prefix.

GM Roll

A "GM roll" is a private dice roll where the result is 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.

Blind Roll

A "blind roll" is a private dice roll which where the result and details of the roll are 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.

Self Roll

A "self roll" is a private dice roll which is only visible to the player who rolled it. To perform a self roll, use /selfroll or /sr as the command prefix.

Roll Formula Syntax

Each dice term in a rolled share the same basic structure which chooses to roll a certain number of dice, each with a number of faces, and then apply optional modifiers to the rolled set.

/roll {number}d{faces}{modifiers}

Each rolled formula can contain multiple terms combined using arithmetic operations, and formulae can also include numeric terms. For example, the following formula will roll two 20-sided dice keeping the highest of the two, a separate 4-sided die, and add 4 to the total result.

/roll 2d20kh + 1d4 + 4

You may also include variable terms in your rolled expressions. These variable terms use the syntax @{data.path} which are evaluated using attributes from the data of your currently controlled Actor. The composition of this data depends on the game system you are using, but as an example, the following roll would add the "Strength modifier" in the D&D5E system.

/roll 1d6 + @abilities.str.mod

Available Roll Modifiers

Each dice term can have "modifiers" applied to it. Each modifier is a set of additional characters which defines a type of operation to apply to the roll that it modifies. Modifiers are applied in order from left to right, so a roll with multiple modifiers will perform those in a predictable order where subsequent modifiers operate on the previously modified result. This section defines the roll modifiers which are currently supported:

Keep or Drop Results

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

Re-roll Certain Results

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

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.

Count Successes

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

Margin of Success

Roll a set of dice and compare the total against some target, keeping the difference as the result.

Parenthetical Expressions

A parenthetical expression allows you to evaluate some inner component of a roll formula before evaluating the outer portion. This allows for options where the number, faces, or modifiers of a dice roll are themselves dynamic in some way. Parenthetical expressions are defined by enclosing the inner expression in parentheses. Using parenthetical expressions can allow you to roll a variable number of dice based on a data attribute or an inner dice roll, for example:

/roll (@abilities.dex.mod)d6
/roll (2d4)d8
/roll (1d6)d(@attributes.proficiency)

Furthermore, parenthetical expressions can allow you to evaluate roll modifiers relative to a dynamically shifting target - for example to count the number of successes relative to some target attribute or opposed dice roll:

/roll 3d12cs<=(@attributes.power)
/roll 3d12ms>(4d6)

Dice Pools

A dice pool allows you to evaluate a set of dice roll expressions 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. Dice pools can be used to choose the better result between two or more alternative rolled formulae, for example:

/roll {4d6 + 4, 3d8 + 3, 2d10 + 2}kh
/roll {1d20, 10}kh

Dice pools can also be used to count the number of inner results which exceeded some threshold, for example:

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

API References

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 Class API documentation for details.