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 2Parse, 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.
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 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.
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 DiceNotationif (isDiceNotation(userInput)) {// userInput is typed as DiceNotation}
// Full validation with error infoconst 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 spaceTokenization: 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, descriptionLearn more
Section titled “Learn more”- Getting Started: install and use notation in your project
- Notation Syntax Guide: the full notation syntax reference
- Validation & Parsing: a deep dive into validation, parsing, and transformation
- API Reference: all exported functions and types
- Formal Specification: the language-agnostic RANDSUM Dice Notation spec with conformance levels, execution pipeline, and modifier taxonomy