# Introduction

RANDSUM is a TypeScript-first dice engine for tabletop RPGs and game development.

- **`@randsum/roller`** — roll dice with a single function call, apply modifiers, parse and validate [Randsum Dice Notation](https://randsum.dev/notation/randsum-dice-notation/) strings, get typed results
- **`@randsum/games`** — game-specific roll functions for Salvage Union, D&D 5e, PbtA, and more

## Your first roll

<CodeExample code={`const result = roll(20)
console.log(result.total) // => a number between 1 and 20`} />

<NotationRoller defaultNotation="1d20" client:only="react" />

`roll()` accepts numbers, [notation strings](https://randsum.dev/notation/randsum-dice-notation/), or options objects — mix and match freely:

<CodeExample code={`// Notation string — 4d6, drop the lowest
const abilityScore = roll('4d6L')

// Options object — same thing
const abilityScore2 = roll({
  sides: 6,
  quantity: 4,
  modifiers: { drop: { lowest: 1 } }
})

// Multiple arguments — combine rolls into one total
const attackDamage = roll('1d20+5', '2d6')`} />

## Install the one you need

The core dice engine. Works everywhere.
    <CodeExample lang="bash" code={`bun add @randsum/roller`} />
      <CodeExample lang="bash" code={`npm install @randsum/roller`} />
      <CodeExample lang="bash" code={`yarn add @randsum/roller`} />
      Game-specific mechanics. Installs `@randsum/roller` automatically.
    <CodeExample lang="bash" code={`bun add @randsum/games`} />
      <CodeExample lang="bash" code={`npm install @randsum/games`} />
      <CodeExample lang="bash" code={`yarn add @randsum/games`} />
      Then // Salvage Union
// D&D 5e
// Powered by the Apocalypse`} />
  ## Runtime support

All packages ship as ESM with full type declarations. No Node.js built-ins required.

| Runtime | Supported |
|---|---|
| Node.js 18+ | Yes |
| Bun 1.0+ | Yes |
| Deno | Yes |
| Browser (ESM) | Yes |
| Edge functions (Cloudflare, Vercel) | Yes |
**When does roll() throw?:** `roll()` throws on invalid input — `NotationParseError` for bad notation strings, `ValidationError` or `ModifierError` (both extending `RandsumError`) for impossible option values or unsatisfiable modifier conditions. Hardcoded notation in your source code will never throw. For user-provided strings, validate first with `validateNotation()` or `isDiceNotation()` (available from `@randsum/roller`). See [Error Handling](https://randsum.dev/roller/error-handling/) for the full pattern.

## Where to go next

- **[Roller — Getting Started](https://randsum.dev/roller/getting-started/)** — learn the `roll()` function, modifiers, and result types
- **[Dice Notation](https://randsum.dev/notation/getting-started/)** — parse and validate dice notation strings
- **[Games — Getting Started](https://randsum.dev/games/getting-started/)** — roll with game-specific mechanics for Salvage Union, D&D 5e, PbtA, and more
- **[Ecosystem Overview](https://randsum.dev/welcome/ecosystem-overview/)** — how the packages fit together

## Links

- [GitHub Repository](https://github.com/RANDSUM/randsum)
- [npm: @randsum/roller](https://www.npmjs.com/package/@randsum/roller)