Skip to content
RANDSUM — TypeScript Dice Rolling Library for Tabletop RPGs RANDSUM

Dice Notation

Parse, validate, and transform dice notation strings — all built into @randsum/roller. Notation is a core capability of the roller, not a separate package. It supports 19 modifier schemas, special dice types (geometric, draw), annotations, and the repeat operator, with zero runtime dependencies.

What is RDN?

Section titled “What is RDN?”

RANDSUM Dice Notation (RDN) is a formal specification for dice notation syntax used in tabletop RPGs. It defines a three-stage execution pipeline, 26 modifiers, and four conformance levels. The full specification is published at notation.randsum.dev.

@randsum/roller implements the complete RDN specification at Level 4 (Full) conformance.

What it does

Section titled “What it does”

Validation — check if a string is valid dice notation, with type narrowing or structured error details.

import { isDiceNotation, validateNotation } from '@randsum/roller'


// Type guard — narrows to DiceNotation
if (isDiceNotation(userInput)) {
// userInput is typed as DiceNotation
}


// Full validation with error info
const result = validateNotation(userInput)
if (!result.valid) {
console.error(result.error.message)
}

Parsing — convert notation strings into structured ParsedNotationOptions arrays.

import { notationToOptions } from '@randsum/roller'


const options = notationToOptions('4d6L')
// [{ sides: 6, quantity: 4, modifiers: { drop: { lowest: 1 } } }]

Transformation — convert structured options back to notation strings or human-readable descriptions.

import { optionsToNotation, optionsToDescription } from '@randsum/roller'


const options = {
sides: 6,
quantity: 4,
modifiers: { drop: { lowest: 1 } }
}


optionsToNotation(options)     // '4d6L'
optionsToDescription(options)  // ['Roll 4 6-sided dice', 'Drop lowest']

Suggestion — offer corrected notation for invalid input.

import { suggestNotationFix } from '@randsum/roller'


suggestNotationFix('d20')  // '1d20' — adds missing quantity

Tokenization — break notation into typed tokens for syntax highlighting or UI display.

import { tokenize } from '@randsum/roller'


const tokens = tokenize('4d6L+5')
// Each token has: text, type, start, end, description

Learn more

Section titled “Learn more”
Section titled “Links”