Skip to content
RANDSUM

Introduction to RANDSUM

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 strings, get typed results
  • @randsum/games: game-specific roll functions for Salvage Union, D&D 5e, PbtA, and more
  • @randsum/ui: a drop-in dice roller as a web component, with React, Vue, Svelte and React Native bindings
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: the 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')

The core dice engine. Works everywhere.

Terminal window
bun add @randsum/roller

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

Runtime Supported
Node.js 18+ Yes
Bun 1.3.10+ Yes
Deno Yes
Browser (ESM) Yes
Edge functions (Cloudflare, Vercel) Yes