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, get typed results
@randsum/notation — parse and validate Randsum Dice Notation strings independently
@randsum/games — game-specific roll functions for Salvage Union, D&D 5e, PbtA, and more

Your first roll

import { roll } from '@randsum/roller'

const result = roll(20)
console.log(result.total) // => a number between 1 and 20

roll() accepts numbers, notation strings, or options objects — mix and match freely:

// 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.

bun add @randsum/roller

npm install @randsum/roller

yarn add @randsum/roller

Game-specific mechanics. Installs @randsum/roller automatically.

bun add @randsum/games

npm install @randsum/games

yarn add @randsum/games

Then import from the subpath for your game:

// Pick one:
import { roll } from '@randsum/games/salvageunion' // Salvage Union
import { roll } from '@randsum/games/fifth'        // D&D 5e
import { roll } from '@randsum/games/pbta'         // Powered by the Apocalypse

Parse and validate dice notation strings without the roll engine. Install this only if you don’t need roll() — @randsum/roller already re-exports validateNotation, isDiceNotation, and notation.

bun add @randsum/notation

npm install @randsum/notation

yarn add @randsum/notation

Runtime support

All packages ship as ESM and CJS 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

Where to go next

Roller — Getting Started — learn the roll() function, modifiers, and result types
Notation — Getting Started — parse and validate dice notation strings
Games — Getting Started — roll with game-specific mechanics for Salvage Union, D&D 5e, PbtA, and more
Ecosystem Overview — how the packages fit together