Skip to main content

Getting started

Dice notation

Complete map of the grammar, shortcuts, and pages for every roll type.

Choose a roll type

Expression shape

NdX rolls N dice with X sides; operators and functions build expressions. Modifiers are die suffixes: 4d6kh3. A braced list forms a group: {d8,d10}kh1. N# repeats one formula; ; splits a mixed batch, including special systems. Compact notation is conventional, but input may contain whitespace.

Compare points

Conditional modifiers accept =, !=/<>, <, <=, >, and >= followed by a numeric literal, signed if needed. r<3 rerolls 1 or 2 on d20; !>=5 explodes on 5 or 6 on d6; >=8f=1 counts successes and failures. Immediately after a die, ! starts an explosion, so d6!=3 means “explode on 3”; for a “not equal to 3” target use d6<>3.

Normalization shortcuts

d becomes d20; f becomes 4dF; 2f becomes 2dF; ei6 becomes !>=6; km becomes kl1; k becomes k1. -pool(N) becomes pool(-N), while +step(N) becomes step(+N). normalizeRpgDiceNotation() returns normalized text; inspectRpgDiceNotation() validates without consuming RNG.

import { normalizeRpgDiceNotation, inspectRpgDiceNotation } from '@erpg/dicecore/core'
console.log(normalizeRpgDiceNotation('d + 2f')) // d20+2dF
console.log(inspectRpgDiceNotation('4d6kh3').isValid) // true

Runtime modifiers follow a fixed order: min, max, explode, reroll, unique, keep, drop, target, critical success, critical failure, and sort. Structural pool, adv, dis, and step resolve first. If a modifier kind appears more than once, the last one wins.

Try the examples