Skip to content
RANDSUMspec

Notation Syntax Guide

RANDSUM uses an extended version of standard dice notation. All notation is case-insensitive (2d8 = 2D8).

The core format is NdS where N is the number of dice and S is the number of sides.

A geometric die rolls dN repeatedly as long as the maximum face value is rolled, and the result is the sum of all rolls. All notation is case-insensitive.

Notation Description
gN Roll dN until a non-maximum is rolled, result = sum
3gN Three independent geometric rolls

A safety cap of 1000 iterations prevents infinite loops. Use cases include resource depletion tracking, chase mechanics, and survival countdowns.

A draw die samples without replacement from a pool of faces, like drawing cards from a deck. Each face value can only appear once until the pool is exhausted, at which point it reshuffles. All notation is case-insensitive (DD, dd, Dd, dD all work).

Notation Description
DDN Draw one unique value from [1..N]
3DDN Draw 3 unique values from [1..N]
6DD6 Always a permutation of [1,2,3,4,5,6]
8DD6 Full permutation of [1..6] + 2 more (reshuffles)

Use cases include card-deck mechanics, random encounter tables without repeats, draft picks, and Catan-style resource distribution.

A percentile die rolls 1-100. Used in Call of Cthulhu, Warhammer Fantasy, and any system with percentage-based resolution. All notation is case-insensitive.

Argument Equivalent Description
d% roll(100) Roll one d100

d% maps internally to { quantity: 1, sides: 100 }. A quantity prefix rolls several: 2d% is 2d100.

d% takes modifiers like any other die: d%+5, 2d%L.

Fate dice (also called Fudge dice) produce results of -1, 0, or +1 per die. The standard Fate Core roll is 4dF, giving a range of -4 to +4. An extended variant (dF.2) uses five faces: -2, -1, 0, +1, +2. All notation is case-insensitive.

Argument Faces Range per die Description
dF -1, 0, +1 -1 to +1 Standard Fate/Fudge die
dF.1 -1, 0, +1 -1 to +1 Explicit standard variant
dF.2 -2, -1, 0, +1, +2 -2 to +2 Extended Fudge die
4dF -1, 0, +1 -4 to +4 Standard Fate Core roll
4dF.2 -2, -1, 0, +1, +2 -8 to +8 Four extended dice

Internally, dF is a die whose faces are -1, 0 and +1 (or -2 to +2 for dF.2). dF takes modifiers like any other die, so 4dF+1 is a Fate Core roll with a +1 skill. dF, zN and d{...} dice have no maximum face in the usual sense, so !, !! and !p need a condition on them, as in 4dF!{>0}, and !s{...}, !i, !r and W are not available.

Zero-indexed dice that roll 0 to N-1 instead of 1 to N. All notation is case-insensitive.

Notation Description
zN Zero-indexed die (0 to N-1)
z6 Roll 0-5 instead of 1-6
3z10 Three zero-bias d10s (0-9)

Zero-bias dice are notation-only: there is no options object equivalent. Use the notation string form roll('z6') or construct faces manually: roll({ sides: [0, 1, 2, 3, 4, 5] }).

Use cases: Zero-indexed random table lookups, percentile systems that use 0-99, programming-friendly dice for array index selection.

Define dice with arbitrary face values. All notation is case-insensitive.

Notation Description
d{2,3,5,7} Die with faces 2, 3, 5, 7
d{-1,0,1} Die with negative/zero faces
d{fire,ice,lightning} Die with string faces
3d{1,1,2} 3 dice with weighted faces

Duplicate values create weighted distributions: d{1,1,2} has a 2/3 chance of rolling 1 and a 1/3 chance of rolling 2. When faces are non-numeric strings, the roll result contains string values rather than numbers.

Custom faces dice take modifiers like any other die: 2d{1,2,3}+1, 3d{a,b,c}L. !, !! and !p need a condition, as in 3d{1,2,3}!{>2}, and !s{...}, !i, !r and W are not available.

Use cases: Custom damage type dice (fire/ice/lightning), narrative dice (success/failure/complication), weighted probability dice, or any die with non-standard faces.

Add or subtract a fixed value from the total.

Notation Description
+N Add N to total
-N Subtract N from total

Remove dice from the result pool.

Notation Description
L Drop lowest 1
L2 Drop lowest 2
H Drop highest 1
H2 Drop highest 2
D{>N} Drop rolls over N
D{>=N} Drop rolls at or over N
D{<N} Drop rolls under N
D{<=N} Drop rolls at or under N
D{X,Y} Drop exact values X and Y

Keep specific dice from the result (complement of drop).

Notation Description
K Keep highest 1
K3 Keep highest 3
kl Keep lowest 1
kl2 Keep lowest 2

Limit roll values to a specific range.

Notation Description
C{>N} Cap rolls over N to N
C{<N} Cap rolls under N to N
C{<N,>M} Cap both ends

Reroll dice matching certain conditions.

Notation Description
R{>N} Reroll results over N
R{>=N} Reroll results at or over N
R{<N} Reroll results under N
R{<=N} Reroll results at or under N
R{X,Y} Reroll exact values X, Y
R{<N}M Reroll under N, rerolling at most M dice
ro{<N} Reroll each die under N once, keeping the new result

Replace specific results with new values.

Notation Description
V{X=Y} Replace Xs with Y
V{>N=Y} Replace results over N with Y
V{<N=Y} Replace results under N with Y

Force all dice in a pool to show different values.

Notation Description
U All results must be unique
U{X,Y} Unique except X and Y can repeat

Roll additional dice when a die shows its maximum value.

Notation Description
! Explode: an additional die per max result, and again while new dice explode

When a die shows its maximum value, it “explodes”: a new die is rolled and added to the result. A new die that also shows its maximum explodes again, up to 1000 new dice per original die.

Example: 3d6! rolls [6, 4, 6]. The first 6 explodes into a 6, which explodes into a 2; the second 6 explodes into a 3. Final result: [6, 4, 6, 6, 2, 3] = 27.

Exploding dice that add to the triggering die instead of creating new dice.

Notation Description
!! Compound while the added roll is also a max (capped at 1000)
!!N Compound with max depth N
!!0 Compound unlimited (capped at 1000)

Example: 1d6!! rolls 6. This compounds, rolling 4. The die value becomes 6 + 4 = 10. Unlike regular exploding, this does not create new dice: it adds to the existing die.

Difference from explode:

  • Explode (!): Creates new dice: [6, 4, 6] becomes [6, 4, 6, 5, 3] (5 dice)
  • Compound (!!): Adds to the existing die: [6, 4, 6] becomes [15, 4, 12] (still 3 dice)

Exploding dice where each added roll counts 1 less (Hackmaster-style).

Notation Description
!p Penetrate while the added roll is also a max (capped at 1000)
!pN Penetrate with max depth N
!p0 Penetrate unlimited (capped at 1000)

Example: 1d6!p rolls 6. This penetrates, rolling 5. The value added is 5 - 1 = 4, so the die becomes 6 + 4 = 10.

The D6 System wild die modifier (West End Games). The last die in the pool is designated as the “wild die” with special behavior. All notation is case-insensitive.

Notation Description
W Last die is the “wild die”

Wild die behavior:

  • Wild die = max value (6): The wild die compound-explodes: keep rolling and adding while the maximum is rolled.
  • Wild die = 1: Remove the wild die AND the highest non-wild die from the pool.
  • Otherwise: No special effect, the wild die acts as a normal die.

Example: 5d6W rolls [4, 3, 5, 2, 6]. The wild die (6) compound-explodes: rolls 4, so wild die becomes 10. Result: [4, 3, 5, 2, 10] = 24.

Example (wild 1): 5d6W rolls [4, 3, 5, 2, 1]. The wild die (1) triggers removal: remove the 1 (wild) and the 5 (highest non-wild). Result: [4, 3, 2] = 9.

Multiply the dice sum before adding/subtracting arithmetic modifiers.

Notation Description
*N Multiply dice sum by N

Example: 2d6*2+3 rolls [4, 5] = 9. Multiplied by 2 = 18. Plus 3 = 21.

Count dice meeting a threshold instead of summing values. Used in dice pool systems.

Notation Description
S{N} Count dice >= N
S{N,B} Count successes >= N, subtract botches <= B

Example: 5d10S{7} rolls [8, 3, 10, 6, 9]. Successes >= 7: [8, 10, 9] = 3 successes.

Count how many dice rolled at or below a threshold. The total becomes the failure count. All notation is case-insensitive.

Notation Description
F{N} Count dice that rolled <= N

Example: 5d10F{3} rolls [8, 2, 10, 1, 9]. Failures <= 3: [2, 1] = 2 failures.

Sort dice results for display purposes without changing the total. All notation is case-insensitive.

Notation Description
sa Sort ascending
sd Sort descending

Sort reorders the dice results for display without changing the total. Useful for readability when reviewing large pools.

Integer divide the total, truncating toward zero. All notation is case-insensitive.

Notation Description
//N Integer divide total by N (truncates via Math.trunc)

Example: 4d6//2 rolls [3, 5, 4, 2] = 14. Integer divided by 2 = 7.

Use cases: Halving damage (e.g., resistance in D&D), averaging mechanics, systems that use integer math for resource calculation.

Apply modulo to the total. All notation is case-insensitive.

Notation Description
%N Total modulo N

Example: 4d6%3 rolls [3, 5, 4, 2] = 14. 14 % 3 = 2.

Use cases: Wrapping values into ranges, clock mechanics, cyclic resource systems.

Multiply the entire final total after all other modifiers.

Notation Description
**N Multiply final total by N

Difference from pre-arithmetic multiplier:

  • Pre-arithmetic (*): 2d6*2+3 = (sum x 2) + 3
  • Total (**): 2d6+3**2 = (sum + 3) x 2

Notation sugar that repeats a roll expression N times. All notation is case-insensitive.

Notation Description
xN Repeat the preceding notation N times

The xN suffix is detected during notation parsing. It strips the suffix, then repeats the base notation N times as separate roll groups. N must be >= 1.

Example: 4d6Lx6 expands to six separate 4d6L rolls, which generates all six D&D ability scores in a single call.

Use cases: D&D ability score generation (4d6Lx6), rolling multiple identical damage dice groups, batch stat generation.

Attach labels to dice terms. Labels are flavor text with no mechanical effect, and their text keeps its case.

Notation Description
[text] Label attached to a roll group
2d6+3[fire]+1d4[cold] Labels on specific dice groups

Labels are enclosed in square brackets and attached to the preceding dice term. They are stripped before modifier parsing and stored in the roll result. Labels are valid notation: isDiceNotation accepts notation with labels.

Use cases: Tracking damage types in D&D, labeling ability score rolls, annotating complex multi-group rolls for display purposes.

Modifiers can be chained together. Whatever order you write them in, they run in one fixed order: values are capped, replaced and rerolled first, then dice explode, then the pool is trimmed (unique, drop, keep), then dice are counted, and arithmetic comes last. The application order table gives each modifier’s exact priority.

Roll different dice types in a single expression:

import { roll } from '@randsum/roller'
// Attack roll + damage
roll('1d20+5', '2d6+3')
// Subtract a die group
roll('2d12-1d6') // Roll 2d12, subtract 1d6