Skip to content
RANDSUMspec

RANDSUM spec

An open standard for dice notation

RANDSUM Dice Notation: one grammar, a fixed modifier order, and conformance levels any roller can implement.

4d6R{1}L+2
roll 4d6 → reroll 1s → drop lowest → add 2

Parse, validate and transform dice notation strings with @randsum/roller. Notation is built into 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.

RANDSUM Dice Notation (RDN) is a formal specification for dice notation syntax used in tabletop RPGs. It defines a staged execution pipeline, a fixed modifier order, and conformance levels any roller can implement. The full specification is published at notation.randsum.dev.

@randsum/roller is the reference implementation and is Level 4 (Full) conformant: it passes every conformance vector.

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')
// [{ quantity: 4, arithmetic: 'add', sides: 6, 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('4d6 L') // '4d6L': removes the space

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, key, category, start, end, description