Dice Reference

DiceRoller supports a robust syntax to roll dice of all descriptions and modify those rolls in various ways. The most simple way to roll dice is via NdX+Y, which says to roll N dice that each have X sides, and then add Y to the total. An example would be 1d20+4.

In this documentation, any bold green text refers to placeholders, where normal text indicates symbols that should be left as-is. For example, the d in 1d20 must be left as the letter d, it is not a placeholder for something else.

Basic rolls

NdX: This will roll N dice with X sides per die (numbered from 1 to X). The dice are then added together to get the final result.
NdF: This will roll N fudge dice, which are dice with the numbers -1, 0, and 1.
NdFX: This will roll N fudge dice with a custom range, numbered from -X to X.
N: This will just result in the static number N, which is useful for when you just want to add a constant number to something or do pure math without rolling dice. N can be any decimal number, and may be negative.

Basic rolls can be augmented with functions and extras. This guide will mark the functions and extras that can apply to basic rolls with (Basic). For example, 1d20ad rolls 1d20 with advantage (rolls the expression twice and takes the highest result), and 4d6dl1 rolls 4d6 and then drops the lowest roll. These could also be represented as 1d20.advantage() and 4d6.droplowest(1).

Math

Math can be performed with die rolls, with addition (+), subtraction (-), multiplication (*), and division (/) being allowed. Math expressions can be wrapped in parenthesis as well to clearly denote which expressions should be evaluated first, or to inject a math operation into any location where a number would normally be expected. Any roll expression is valid on either side of a math operator, whether that is a roll or just a number. For example, all of the following are valid rolls:

1d20+4
(1d10+2d6+2)*1.5
(1d8)d10 (rolls 1d8, and then rolls that many d10s, returning the sum of the d10s)
10000/6 (divides 10,000 by 6, and returns the result. In other words, rolling dice is not required)

Macros

Whenever a number is expected, a macro can be provided instead. The stand-alone dice roller does not define any macros, but the Play-by-Post helper utility defines some (see below for more details). Additionally, the program which uses the library may define custom macros. Macros are enclosed in square brackets, and can have any text inside of them (except for a right square bracket). An example of a macro may be something that looks up a property on a character sheet, but the possibilities are unlimited.

Examples of macros:

1d20+[WIS-mod] (rolls 1d20 and adds the result of the WIS-mod macro)
1d10+[SneakAttack]d6 (rolls 1d10 plus a number of d6's equal to the SneakAttack macro)

Pre-defined Macros

These macros are always defined.

numDice

The numDice macro returns the number of dice rolled so far in the current roll. For example, 5d4 + [numDice] is the same as 5d4 + 5.

Play-by-Post Macros

The following macros are pre-defined if the Play-by-Post helper is used. If dice are rolled individually (not collected in a post containing multiple rolls), these macros are not defined.

roll

The roll macro allows for retrieving the value or other properties of previous dice rolls in the same post. It can be invoked in the following ways. Should an invocation be invalid, nothing happens (which means an error is likely displayed stating that the macro is invalid).

[roll:X]: Retrieves the value of the Xth roll in the post. The first roll in the post is X = 1. This can only be used to retrieve the value of previous rolls, it will not work if X is greater than or equal to the current roll number. If X is negative, it counts backwards from the current post (so X = -1 obtains the value of the previous post). X = 0 is invalid.

[roll:X:Y]: Retrieves the value of the Yth kept die roll in the Xth post. X is counted as per above. Y is counted from left-to-right in the normalized dice expression, and skips over dropped dice. Unlike X, Y cannot be negative (the first die is Y = 1).

[roll:X:critical]: Counts the number of dice in the Xth roll that were marked as criticals.

[roll:X:Y:critical]: This is 1 if the Yth die in the Xth roll is critical, and 0 otherwise.

[roll:X:fumble]: Counts the number of dice in the Xth roll that were marked as fumbles.

[roll:X:Y:fumble]: This is 1 if the Yth die in the Xth roll is a fumble, and 0 otherwise.

[roll:X:success]: Counts the number of dice in the Xth roll that were marked as successes.

[roll:X:Y:success]: This is 1 if the Yth die in the Xth roll is a success, and 0 otherwise.

[roll:X:failure]: Counts the number of dice in the Xth roll that were marked as failures.

[roll:X:Y:failure]: This is 1 if the Yth die in the Xth roll is a failure, and 0 otherwise.

Grouped rolls

N{roll1, roll2, ...} or {roll1, roll2, ...}

Grouped rolls are a complex and powerful mechanism to roll groups of disparate dice and then operate on those groups. A grouped roll is made by enclosing one or more basic rolls inside of curly braces. A number N can be specified in front of the group to evaluate that group that number of times. For example, 6{4d6dl1} rolls 4d6 (dropping the lowest roll) six times, and returns each result.

Grouped rolls can be augmented with functions and extras. This guide will mark the functions and extras that can apply to grouped rolls with (Group). For example, {2d8,3d6}kh1 rolls 2d8 and 3d6, sums each one, and then keeps the highest result. This could also be expressed as {2d8,3d6}.keephighest(1).

Comparisons

Some extras and functions take comparisons as parameters. A comparison is implicit if it just contains a number with no leading comparison operator, or explicit if it has a leading comparison operator. Some extras and functions require explicit comparisons, while others are ok with implicit comparisons as well.

The valid comparisons are as follows:

N (implicit comparison that tests if the result is equal to N)
=N
>N
<N
>=N (tests if the result is greater than or equal to N)
<=N (tests if the result is less than or equal to N)
!=N or <>N (tests if the result is not equal to N)

Extras

Extras can be added at the end of basic or group rolls to modify their behavior. If an extra takes a comparison as its parameter, you can specify that extra multiple times in order to compare against all of them. For example, 1d6rr2rr4rr6 would roll 1d6 and re-roll any even number. Extras can be added in any order, but are always evaluated in the following order:

Explode
Reroll
Keep/Drop/Advantage
Success/Failure
Critical/Fumble
Sort

If an extra is marked with (Basic) it can be used with basic rolls, and if it is marked with (Group) it can be used with group rolls. Those marked (Basic/Group) can be used with both types of rolls. If the extra takes a parameter, it will indicate if it takes a number N, a comparison C, or an explicit comparison EC.

Explode (Basic)

!e: Whenever the maximum value is rolled for a die, that die is rerolled. Both the original and reroll are added to the total. This repeats until something other than the maximum value is rolled. For example, 1d6!e would roll 1d6. If a 6 is rolled, another 1d6 is rolled, and so on. This could lead to a final roll of 6, 6, 4.
!eC: Whenever the comparison succeeds for a die, that die is rerolled. Both the original and reroll are added to the total. This repeats until the comparison fails.
!eo: Per !e, except the dice will be rerolled at most once.
!eoC: Per !eC, except the dice will be rerolled at most once.
!c: Per !e, except that the rerolled values are added to the original die result, rather than adding another die into the final result list. This is called a compounding explosion. For example, 1d6!c would roll 1d6. If a 6 is rolled, another 1d6 is rolled, and so on. This could lead to a final roll of 6, 6, 4, which is represented by a single 6-sided die rolling a value of 16.
!cC: Per !c, except it compares the die result against the comparison C instead of using the maximum value of the die.
!p: Whenever the maximum value is rolled for a die, that die is rerolled and 1 is subtracted from the reroll. Both the original and reroll are added to the total. This repeats until something other than the maximum value is rolled. For example, 1d6!e would roll 1d6. If a 6 is rolled, another 1d6 is rolled, and so on. This could lead to a final roll of 6, 5, 3 (assuming 6, 6, and then a 4 were rolled). This is called penetrating dice. Furthermore, a d100!p penetrates down to d20!p, and d20!p penetrates down to d6!p. This downgrade only happens once (so if 1d100!p rolls 100, then 20, it continues to roll d20s instead of downgrading again to d6).
!pC: Per !p, except it compares the die result against the comparison C instead of using the maximum value of the die. Furthermore, the special downgrading rules are not used, so d100 will penetrate to d100, and d20 will penetrate to d20.
!i: Whenever the minimum value is rolled for a die, that die is rerolled. The original roll is added to the total but all rerolled amounts are subtracted from the total. The die will be rerolled until something other than the minimum value is rolled. For example, 1d6!i would roll 1d6. If a 1 is rolled, another 1d6 is rolled. This could lead to a final result of 1, 1, and 4, for a total of -4 (1 - 1 - 4).
!iC: When the comparison succeeds for the die, it will be rerolled. Like !i, the original roll is added to the total and all rerolls are subtracted from the total. This repeats until the comparison fails.
!io: Per !i, except the dice will be rerolled at most once.
!ioC: Per !iC, except the dice will be rerolled at most once.

Reroll (Basic/Group)

rrC: Whenever the comparison succeeds, it rerolls the die, discarding the previous result. This will happen until the comparison fails.
roC: If the comparison succeeds, it will reroll the die, discarding the previous result. The die is rerolled a maximum of one time, even if the comparison would succeed again.

Keep/Drop (Basic/Group)

khN: Keeps the highest N results, discarding the rest.
klN: Keeps the lowest N results, discarding the rest.
dhN: Discards the highest N results, keeping the rest.
dlN: Discards the lowest N results, keeping the rest.

If multiple keep or drop expressions are applied, they work in sequence. For example, 4d6dl1dl1 would roll 4d6, drop the lowest die, and then drop the next lowest die. In other words, it is equivalent to 4d6dl2. A keep/drop expression cannot be combined with advantage or disadvantage.

Advantage (Basic/Group)

ad: Gives the expression advantage, causing it to be rolled twice and then keeping the highest result.
da: Gives the expression disadvantage, causing it to be rolled twice and then keeping the lowest result.

Advantage or disadvantage cannot be combined with keep/drop expressions.

Success/Failure (Basic/Group)

EC: Each die rolled is compared against EC. If it matches, it counts as one success. If it does not match, it counts as zero successes. The result of the roll is the number of successes, rather than the sum of the dice. For example, 5d10>6 will roll 5d10 and count one success each time the die comes up as 7 or higher.
ECfC: Each die rolled is compared against EC. If it matches, it counts as one success. If it does not match EC, but does match C, it removes one success. Otherwise, it counts as zero successes. The result of the roll is the number of successes (which may be negative), rather than the sum of the dice.

Critical/Fumble (Basic)

csC: Each die rolled is compared against C, and marked as a critical success should it succeed.
csCfC: Each die rolled is compared against both comparisons. The first marks it as a critical success should it succeed, and the second marks it as a fumble (critical failure) should it succeed.
cfC: Each die rolled is compared against C, and marked as a fumble should it succeed.

Critical successes and fumbles do not have any mechanical function by themselves, but can be tracked via macros or functions, and are usually displayed differently. It is possible for a die to be marked as both a critical and a fumble at the same time. If a roll does not have a critical/fumble expression attached to it, then a roll of the maximum result is counted as a critical and the minimum result is counted as a fumble.

Sort (Basic/Group)

sa: Causes each die rolled to be sorted in ascending order for display purposes.
sd: Causes each die rolled to be sorted in descending order for display purposes.

Global functions

Global functions can be used wherever a math expression can be used, and transform the die results in various ways. The following global functions are built-in to the library, however the program which uses the library can also define its own global functions. If the function takes a parameter, it will indicate if it takes an expression E (which can be any arbitrary math or roll expression), or an explicit comparison C.

floor

floor(E)

Takes the mathematical floor of the expression, truncating any decimal portion. Example: 1d20+floor([Levels]/2)

ceil

ceil(E)

Takes the mathematical ceiling of the expression, causing any decimal portion to round up to the next whole number.

round

round(E)

Rounds the result of the expression. Decimal values greater than or equal to 0.5 are rounded away from zero, whereas decimal values less than 0.5 are rounded towards zero. For example, 1.5 and 1.6 both round to 2, 1.4 rounds to 1, -1.5 and -1.6 both round to -2, and -1.4 rounds to -1.

abs

abs(E)

Takes the absolute value of the expression.

max

max(E, E)

Returns the highest Value from the two expressions. Dice rolled in the low-valued expression are all marked as dropped.

min

min(E, E)

Returns the lowest Value from the two expressions. Dice rolled in the high-valued expression are all marked as dropped.

if

if(E₁, C, E₂): If the comparison succeeds for E₁, then this returns the Value of E₂. Otherwise, this returns 0.

if(E₁, C, E₂, E₃): If the comparison succeeds for E₁, then this returns the Value of E₂. Otherwise, this returns the Value of E₃.

Note that all expressions in if() are evaluated, even if they are not returned.

Dice functions

Dice functions, like dice extras, are added to the end of die rolls. All dice functions must come after dice extras, but can otherwise go in any order. The following dice functions are pre-defined by the library, but the program may add more.

If a function is marked with (Basic) it can be used with basic rolls, and if it is marked with (Group) it can be used with group rolls. Those marked (Basic/Group) can be used with both types of rolls. If the function takes a parameter, it will indicate if it takes a number N, an expression E (which can be any arbitrary math or roll expression), or an explicit comparison C. Should a function take a number as a parameter, it must either be a literal number or a macro, it cannot contain any rolls or math.

reroll (Basic/Group)

.reroll(C, C, ...)

This is equal to specifying the rr extra once for each comparison passed into the function. At least one comparison must be specified. For example, to reroll 1d6 whenever an even number comes up, you could specify 1d6.reroll(=2, =4, =6).

rerollN (Basic/Group)

.rerollN(N, C, C, ...)

Like reroll, however will only reroll at most N times before it keeps the final result (even if one of the comparisons would still succeed). At least one comparison must be specified.

rerollOnce (Basic/Group)

.rerollOnce(C, C, ...)

This is equal to specifying the ro extra once for each comparison passed into the function. At least one comparison must be specified.

explode (Basic)

.explode(C, C, ...)

This is equal to specifying the !e extra once for each comparison passed into the function. At least one comparison must be specified.

compound (Basic)

.compound(C, C, ...)

This is equal to specifying the !c extra once for each comparison passed into the function. At least one comparison must be specified.

penetrate (Basic)

.penetrate(C, C, ...)

This is equal to specifying the !p extra once for each comparison passed into the function. At least one comparison must be specified.

compoundPenetrate (Basic)

.compoundPenetrate(C, C, ...)

Like penetrate, except all additional penetration dice rolled are added to the initial value (just like the compound function). At least one comparison must be specified.

keepHighest (Basic/Group)

.keepHighest(E)

This is equal to specifying the kh extra.

keepLowest (Basic/Group)

.keepLowest(E)

This is equal to specifying the kl extra.

dropHighest (Basic/Group)

.dropHighest(E)

This is equal to specifying the dh extra.

dropLowest (Basic/Group)

.dropLowest(E)

This is equal to specifying the dl extra.

advantage (Basic/Group)

.advantage()

This is equal to specifying the ad extra.

disadvantage (Basic/Group)

.disadvantage()

This is equal to specifying the da extra.

success (Basic/Group)

.success(C, C, ...)

This is equal to specifying the success extra once for each comparison passed into the function. At least one comparison must be specified.

failure (Basic/Group)

.failure(C, C, ...)

Specifies one or more failure comparison without specifying a success comparison. At least one success comparison must be specified via other means, such as the success extra or by calling .success(C).

critical (Basic)

.critical(C, C, ...)

This is equal to specifying the cs extra once for each comparison passed into the function. At least one comparison must be specified.

fumble (Basic)

.fumble(C, C, ...)

This is equal to specifying the cf extra once for each comparison passed into the function. At least one comparison must be specified.

sortAsc (Basic/Group)

.sortAsc()

This is equal to specifying the sa extra.

sortDesc (Basic/Group)

.sortDesc()

This is equal to specifying the sd extra.

expand (Group)

.expand()

Normally, grouped rolls display aggregated results instead of showing the value of each individual die rolled. For example, {4d6} will display (for example) (15) instead of (4 + 5 + 3 + 3). The expand function causes it to display the value of each individual die instead, so {4d6}.expand() will display (for example) (4 + 5 + 3 + 3). Expand is applied before sorting, so you can sort the individual rolls of a group if you both expand and sort.

Search