# 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?

**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](https://notation.randsum.dev).

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

## What it does

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

<CodeExample code={`// 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.

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

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

<CodeExample code={`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.

<CodeExample code={`suggestNotationFix('d20')  // '1d20' — adds missing quantity`} />

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

<CodeExample code={`const tokens = tokenize('4d6L+5')
// Each token has: text, type, start, end, description`} />

## Learn more

- **[Getting Started](https://randsum.dev/notation/getting-started/)** — install and use notation in your project
- **[Randsum Dice Notation Spec](https://randsum.dev/notation/randsum-dice-notation/)** — the full notation syntax reference
- **[Validation & Parsing](https://randsum.dev/notation/validation-and-parsing/)** — deep dive into validation, parsing, and transformation
- **[API Reference](https://randsum.dev/notation/api-reference/)** — all exported functions and types
- **[Formal Specification](https://notation.randsum.dev)** — the language-agnostic RANDSUM Dice Notation spec with conformance levels, execution pipeline, and modifier taxonomy

## Links

- [npm package](https://www.npmjs.com/package/@randsum/roller)
- [Source code](https://github.com/RANDSUM/randsum/tree/main/packages/roller)