Notation Syntax Guide
RANDSUM uses an extended version of standard dice notation. All notation is case-insensitive (2d8 = 2D8).
Basic syntax
Section titled “Basic syntax”The core format is NdS where N is the number of dice and S is the number of sides.
Special dice
Section titled “Special dice”Geometric die
Section titled “Geometric die”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.
Draw die
Section titled “Draw die”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.
Percentile die
Section titled “Percentile die”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/Fudge dice
Section titled “Fate/Fudge dice”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-bias dice
Section titled “Zero-bias dice”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.
Custom dice faces
Section titled “Custom dice faces”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.
Arithmetic
Section titled “Arithmetic”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
Section titled “Reroll”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
Section titled “Replace”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 |
Unique
Section titled “Unique”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 |
Explode
Section titled “Explode”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.
Compound
Section titled “Compound”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)
Penetrate
Section titled “Penetrate”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.
Wild Die
Section titled “Wild Die”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.
Pre-Arithmetic Multiply
Section titled “Pre-Arithmetic Multiply”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 successes
Section titled “Count successes”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 failures
Section titled “Count failures”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
Section titled “Integer divide”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.
Modulo
Section titled “Modulo”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.
Total Multiply
Section titled “Total Multiply”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
Repeat operator
Section titled “Repeat operator”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.
Annotations
Section titled “Annotations”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.
Combining modifiers
Section titled “Combining modifiers”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.
Multiple groups
Section titled “Multiple groups”Roll different dice types in a single expression:
import { roll } from '@randsum/roller'
// Attack roll + damageroll('1d20+5', '2d6+3')
// Subtract a die grouproll('2d12-1d6') // Roll 2d12, subtract 1d6Common use cases
Section titled “Common use cases”D&D 5e ability scores
Section titled “D&D 5e ability scores”
D&D 5e advantage/disadvantage
Section titled “D&D 5e advantage/disadvantage”
Critical hits (double base damage)
Section titled “Critical hits (double base damage)”
Hackmaster penetrating dice
Section titled “Hackmaster penetrating dice”
World of Darkness / Shadowrun dice pools
Section titled “World of Darkness / Shadowrun dice pools”