Randsum Dice Notation Spec

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

Basic syntax

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

Arithmetic

Add or subtract a fixed value from the total.

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

Drop

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

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

Cap

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

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, max M attempts

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

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

Roll additional dice when a die shows its maximum value.

Notation	Description
`!`	Explode: one additional die per max result (single pass)

When a die shows its maximum value, it “explodes” — one new die is rolled and added to the result. This is a single pass: the newly added dice are not checked for further explosions. For recursive explosions, use compound (!!) or penetrate (!p).

Example: 3d6! rolls [6, 4, 6]. The two 6s explode, adding [5, 3]. Final result: [6, 4, 6, 5, 3] = 24.

Compound

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

Notation	Description
`!!`	Compound once per die
`!!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 modifies the existing die.

Difference from explode:

Explode (!): Creates new dice — [6, 4, 6] becomes [6, 4, 6, 5, 3] (5 dice)
Compound (!!): Modifies existing die — [6, 4, 6] becomes [15, 4, 12] (still 3 dice)

Penetrate

Exploding dice where each subsequent explosion subtracts 1 (Hackmaster-style).

Notation	Description
`!p`	Penetrate once per die
`!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.

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

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.

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

Combining modifiers

Modifiers can be chained together. They are applied in a fixed priority order:

Priority	Modifier	Notation	Description
10	Cap	`C{...}`	Limit roll values to a range
20	Drop	`H`, `L`	Remove dice from pool
21	Keep	`K`, `kl`	Keep dice in pool
30	Replace	`V{...}`	Replace specific values
40	Reroll	`R{...}`	Reroll dice matching conditions
50	Explode	`!`	Roll additional dice on max
51	Compound	`!!`	Add explosion to existing die
52	Penetrate	`!p`	Add explosion minus 1 to die
60	Unique	`U`	Ensure no duplicate values
85	Multiply	`*N`	Multiply dice sum (pre-arithmetic)
90	Plus	`+N`	Add to total
91	Minus	`-N`	Subtract from total
95	Count Successes	`S{...}`	Count dice meeting threshold
100	Total Multiply	`**N`	Multiply entire final total

Multiple groups

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