Skip to content
RANDSUM

Introduction

RANDSUM is a modular TypeScript dice rolling ecosystem built for tabletop RPGs. Whether you are building a simple dice roller, a full virtual tabletop, or integrating dice mechanics into a Discord bot, RANDSUM provides the foundation you need.

Why RANDSUM?

Section titled “Why RANDSUM?”
  • Zero dependencies — the core roller has no runtime dependencies
  • Full TypeScript support — strict types, branded notation strings, and exhaustive result types
  • Never throws — errors are returned in the result, not thrown as exceptions
  • Modular architecture — install only the packages you need
  • Game-specific packages — first-class support for D&D 5e, Blades in the Dark, PbtA, and more

How it works

Section titled “How it works”

At its simplest, RANDSUM lets you roll dice with a single function call:

import { roll } from '@randsum/roller'


// Roll a d20
const result = roll(20)
console.log(result.total) // 1-20


// Roll 4d6, drop the lowest
const abilityScore = roll('4d6L')


// Roll with advantage
const attack = roll('2d20H+5')

The roll() function accepts numbers, notation strings, or options objects — and you can mix and match them freely.

The ecosystem

Section titled “The ecosystem”

RANDSUM is organized as a monorepo with several packages:

PackageDescription
@randsum/rollerCore dice engine — notation parsing, modifiers, roll execution
@randsum/fifthD&D 5th Edition mechanics
@randsum/bladesBlades in the Dark action rolls
@randsum/pbtaPowered by the Apocalypse (2d6+stat)
@randsum/daggerheartDaggerheart hope/fear dice
@randsum/root-rpgRoot RPG mechanics
@randsum/salvageunionSalvage Union table rolls

Every game package depends only on @randsum/roller — they never depend on each other.

Learning path

Section titled “Learning path”
  1. Installation — Get RANDSUM installed in your project
  2. Quick Start — Learn the basics with hands-on examples
  3. Dice Notation — Master the full notation syntax
  4. Game Packages — Explore game-specific integrations
Section titled “Links”