# RANDSUM

> TypeScript dice engine implementing the RANDSUM Dice Notation (RDN) specification, at RDN v0.9.0 Level 4 (Full) conformance. Works with D&D 5e, Blades in the Dark, PbtA, Daggerheart, Fate Core, Root RPG, Salvage Union, and more. AI agents should roll through the MCP server or the HTTP API rather than inventing dice results.

`roll()` accepts a number, a notation string, an options object, or several of these combined. It throws on invalid input.

```
npm install @randsum/roller

roll(20)            // 1d20
roll("4d6L")        // D&D ability score: 4d6, drop lowest
roll({ sides: 6, quantity: 4, modifiers: { drop: { lowest: 1 } } })
roll("2d20L+5")     // Advantage attack roll
roll("2d6+3")       // PbtA: 2d6 + stat
roll("d%")          // Percentile: 1d100
roll("4dF")         // Fate Core: 4 Fate dice (-4 to +4)
roll("5d6W")        // D6 System wild die
roll("g6")          // Geometric die
roll("3DD6")        // Draw die
roll("4d6Lx6")      // Repeat operator
roll("2d6+3[fire]") // Annotation
```

## Packages

- [@randsum/roller](https://randsum.dev/roller/introduction/): core dice engine with the built-in RDN notation parser
- [@randsum/games](https://randsum.dev/games/introduction/): game interpretations as subpath exports: `/fifth` (D&D 5e), `/blades` (Blades in the Dark), `/pbta`, `/daggerheart`, `/fate` (Fate Core), `/root-rpg`, `/salvageunion`, and `/schema` (codegen and validation for game specs)
- [@randsum/ui](https://randsum.dev/ui/introduction/): the roller as Lit Web Components, `<randsum-roller size="mini|compact|max">` from `/roller` and each part as its own element (`/notation-field`, `/key-pad`, `/readout` and more), with React (`/react/*`), Vue (`/vue/*`) and React Native (`/native/*`) entries, `/svelte` types and `/ssr`; no root entry
- [@randsum/notation-spec](https://notation.randsum.dev/conformance/): the RDN spec, its conformance vectors and the `rdn-conformance` runner for testing any roller
- [@randsum/mcp](https://randsum.dev/tools/mcp/): the MCP server behind the Claude connector (see AI Agents), also runnable over stdio with `bunx @randsum/mcp`

## HTTP API

- [API introduction](https://randsum.dev/api/introduction/): `https://api.randsum.dev/v1`, public, keyless, CORS. `GET /v1/roll?notation=4d6L[&seed=N]`, `/v1/validate?notation=`, `/v1/games`, `/v1/games/{game}/roll?<inputs>`, `/v1/random?min=&max=&count=`; POST takes the same fields as JSON
- [API reference](https://randsum.dev/api/reference/): every route, parameter and response shape

## Apps

- [Roller app](https://randsum.dev/app/): installable, offline-capable dice roller in the browser at https://app.randsum.dev/, for people rather than agents
- [Discord bot](https://randsum.dev/tools/discord-bot/): slash commands for every supported game

## AI Agents

- [Agent integrations](https://randsum.dev/tools/agents/): overview of every way an agent can roll with RANDSUM
- [Claude connector](https://randsum.dev/tools/mcp/): tools `roll`, `validate`, `roll_game` at `https://api.randsum.dev/mcp`. Add it as a custom connector in Claude; any other MCP client takes the same URL (`claude mcp add --transport http randsum https://api.randsum.dev/mcp`). Local stdio fallback: `claude mcp add randsum -- bunx -y @randsum/mcp`
- [Claude Code plugin](https://randsum.dev/tools/claude-code-plugin/): skills, a `/roll` command and the hosted connector's tools. `/plugin marketplace add RANDSUM/randsum`, then `/plugin install randsum@randsum`

## Specification

- [RDN specification](https://notation.randsum.dev/): taxonomy, execution pipeline, conformance levels, syntax
- [RDN specification, full text](https://notation.randsum.dev/llms-full.txt): the whole spec as plain text
- [Games meta-schema](https://randsum.dev/schemas/v1/randsum.json): JSON Schema for `*.randsum.json` game specs; reference it from a `"$schema"` key for editor completion

## Optional

- [Source on GitHub](https://github.com/RANDSUM/randsum)

## Documentation Pages

- https://randsum.dev/app/
- https://randsum.dev/app-shell/
- https://randsum.dev/spec/conformance/
- https://randsum.dev/spec/v/0.9.0/
- https://randsum.dev/spec/
- https://randsum.dev/api/games/
- https://randsum.dev/api/introduction/
- https://randsum.dev/api/random/
- https://randsum.dev/api/reference/
- https://randsum.dev/api/rolling/
- https://randsum.dev/games/blades/
- https://randsum.dev/games/daggerheart/
- https://randsum.dev/games/fate/
- https://randsum.dev/games/fifth/
- https://randsum.dev/games/getting-started/
- https://randsum.dev/games/introduction/
- https://randsum.dev/games/pbta/
- https://randsum.dev/games/root-rpg/
- https://randsum.dev/games/salvageunion/
- https://randsum.dev/games/schema/contributing-a-game/
- https://randsum.dev/games/schema/overview/
- https://randsum.dev/games/schema/reference/
- https://randsum.dev/games/schema/schema-api/
- https://randsum.dev/notation/api-reference/
- https://randsum.dev/notation/getting-started/
- https://randsum.dev/notation/introduction/
- https://randsum.dev/notation/randsum-dice-notation/
- https://randsum.dev/notation/validation-and-parsing/
- https://randsum.dev/privacy/
- https://randsum.dev/roller/api-reference/
- https://randsum.dev/roller/error-handling/
- https://randsum.dev/roller/getting-started/
- https://randsum.dev/roller/introduction/
- https://randsum.dev/roller/modifiers/
- https://randsum.dev/roller/roll-options/
- https://randsum.dev/tools/agents/
- https://randsum.dev/tools/claude-code-plugin/
- https://randsum.dev/tools/discord-bot/
- https://randsum.dev/tools/http-api/
- https://randsum.dev/tools/mcp/
- https://randsum.dev/ui/components/
- https://randsum.dev/ui/getting-started/
- https://randsum.dev/ui/introduction/
- https://randsum.dev/welcome/attribution/
- https://randsum.dev/welcome/ecosystem-overview/
- https://randsum.dev/welcome/introduction/