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 Xsided die y times. For example, to
roll five sixsided 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 highestN
dice out of the group that were rolled.kl{N}
Keep the lowestN
dice out of the group that were rolled.dh{N}
Drop the highestN
dice out of the group that were rolled.dl{N}
Drop the lowestN
dice out of the group that were rolled.
Reroll Certain Results¶
Specific results may be rerolled by specifying a reroll target or range.
r{y}
Reroll any dice where the result wasy
.r>{y}
Reroll any dice where the result was greater thany
.r>={y}
Reroll any dice where the result was greater than or equal toy
.r<{y}
Reroll any dice where the result was less thany
.r<={y}
Reroll any dice where the result was less than or equal toy
.
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 rollsy
.x>{y}
Roll an additional dice if any dice rolls greater thany
.x>={y}
Roll an additional dice if any dice rolls greater than or equal toy
.x<{y}
Roll an additional dice if any dice rolls less than or equal toy
.x<={y}
Roll an additional dice if any dice rolls less than or equal toy
.
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 TODO. The planned syntax is described below but not yet added
s{y}
Count the number of dice which resulted iny
.s>{y}
Count the number of dice which rolled greater thany
.s>={y}
Count the number of dice which rolled greater than or equal toy
.s<{y}
Count the number of dice which rolled less than or equal toy
.s<={y}
Count the number of dice which rolled less than or equal toy
.
Dice Roll API¶
For mod developers, you may want to customize indepth 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] // Execute the roll r.roll(); // The resulting equation after it was rolled console.log(r.result); // 16 + 2 + 4 // The total resulting from the roll console.log(r.total); // 22

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(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.
render
(chatOptions)¶ Render a Roll instance to HTML
Arguments:  chatOptions (Object) – An object configuring the behavior of the resulting chat message.
Returns: Promise – A Promise which resolves to the rendered HTML

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
(chatData)¶ Dispatch a Roll instance to a new ChatMessage entity
Arguments:  chatData (Object) – The data object to use when creating the message
Returns: Promise.<ChatMessage> – A promise which resolves to the created Chat Message

Roll.
total
¶ Express the total result of the roll