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
Your first roll
Section titled “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 lowestconst abilityScore = roll('4d6L')
// Options object: the same thingconst abilityScore2 = roll({sides: 6,quantity: 4,modifiers: { drop: { lowest: 1 } }})
// Multiple arguments: combine rolls into one totalconst attackDamage = roll('1d20+5', '2d6')Install the one you need
Section titled “Install the one you need”The core dice engine. Works everywhere.
bun add @randsum/rollernpm install @randsum/rolleryarn add @randsum/rollerGame-specific mechanics. Installs @randsum/roller automatically.
bun add @randsum/gamesnpm install @randsum/gamesyarn add @randsum/gamesThen import from the subpath for your game:
// Pick one:import { roll } from '@randsum/games/salvageunion' // Salvage Unionimport { roll } from '@randsum/games/fifth' // D&D 5eimport { roll } from '@randsum/games/pbta' // Powered by the ApocalypseRuntime support
Section titled “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.3.10+ | Yes |
| Deno | Yes |
| Browser (ESM) | Yes |
| Edge functions (Cloudflare, Vercel) | Yes |
Where to go next
Section titled “Where to go next”- Roller: Getting Started: learn the
roll()function, modifiers, and result types - Dice Notation: 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