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] // 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