Skip to content
RANDSUM

Ecosystem Overview

RANDSUM is one dice engine with several ways in. The npm packages hold the code, an open spec defines the notation, and the API, Roller app, Discord bot and agent plugin put the same engine in front of people who are not writing TypeScript. Every package ships ESM with full type declarations and is published to npm under @randsum.

@randsum/roller (zero dependencies, includes the notation parser)
|
+-- @randsum/games (one package, a subpath per game)
| +-- /blades (Blades in the Dark)
| +-- /daggerheart (Daggerheart)
| +-- /fate (Fate Core)
| +-- /fifth (D&D 5e)
| +-- /pbta (Powered by the Apocalypse)
| +-- /root-rpg (Root RPG)
| +-- /salvageunion (Salvage Union)
|
+-- @randsum/ui (roller Web Components, one import each)
|
+-- @randsum/mcp (MCP server: roll, validate, roll_game)

Every package depends only on packages above it in the tree. Games never depend on each other.

@randsum/roller

The zero-dependency dice engine with built-in notation parsing and validation. Accepts numbers, notation strings, or options objects and returns typed results with every modifier step. Also exports isDiceNotation, validateNotation, notationToOptions, optionsToNotation, tokenize and more, so most projects only need this package.

Learn more

@randsum/games

Ready-made rules for seven tabletop games, each a subpath export. Every game is generated from an open .randsum.json spec and wraps @randsum/roller with that system’s dice pools, modifiers and outcomes.

Learn more

@randsum/ui

The roller as Web Components: one element in three sizes, Max, Compact and Mini, plus every part it is built from, with React, Vue and Svelte bindings and React Native components. Each component is its own import, so a page ships only what it uses.

Learn more

RANDSUM API

Random Numbers as a service: a free, keyless REST API at api.randsum.dev. It can roll notation, roll for any supported game, or draw random integers, from any language.

Learn more

Roller app

An installable dice roller for your phone that shows every step and rolls offline.

Learn more

Discord bot

Slash commands for any notation and for six of the games, with every step of the roll shown in the reply.

Learn more

Plugin and connector

Real dice for Claude and other agents: a Claude Code plugin with skills and a /roll command, and the hosted MCP server as a Claude connector.

Learn more

RANDSUM Dice Notation

The formal specification for the notation: one grammar, a fixed modifier order, and four conformance levels any roller can implement.

Read the spec

Pick the one that matches your use case:

Use case Install Start here
Roll dice in any JS/TS project bun add @randsum/roller Roller Getting Started
Parse or validate notation strings bun add @randsum/roller Notation Getting Started
Build a TTRPG app with game-specific mechanics bun add @randsum/games Games Getting Started
Put a dice roller in any web app bun add @randsum/ui UI Getting Started
Roll from another language or a no-code tool nothing RANDSUM API
Give an AI agent dice the plugin or connector Dice for AI Agents

Most developers should start with @randsum/roller. It includes the full notation parser and validator along with all rolling functionality and types.

  • RDN conformant: @randsum/roller implements the RANDSUM Dice Notation (RDN) Specification at Level 4 (Full) conformance
  • Zero core dependencies: @randsum/roller has no runtime dependencies and includes the full notation parser and validator
  • Throws on invalid input: roll() throws typed errors on bad input (ValidationError, ModifierError, or NotationParseError); validate user-provided strings with isDiceNotation() or validateNotation() before rolling
  • Games are code-generated: every game is a .randsum.json spec compiled into TypeScript by the games package’s codegen
  • Strict TypeScript: isolatedDeclarations, exactOptionalPropertyTypes, noUncheckedIndexedAccess, no any
  • Bundle size enforced: every roller and games entry point has a size budget checked in CI by size-limit; the budgets live in each package’s size-limit config (packages/roller/package.json, packages/games/.size-limit.ts)