Randsum: Advanced Dice Rolling for JavaScript & TypeScript

A flexible, type-safe dice rolling ecosystem for tabletop RPGs, game development, and simulations

🚀 Quick Example

import { D20, roll } from '@randsum/dice'

// Simple d20 roll
D20.roll() // Returns 1-20

// Complex dice notation
roll('4d6L') // Roll 4d6, drop lowest

// D&D 5e character ability score generation
const abilityScores = Array.from({ length: 6 }, () => roll('4d6L').sum)

// Advantage and disadvantage
roll('2d20H') // Roll with advantage (2d20, keep highest)
roll('2d20L') // Roll with disadvantage (2d20, keep lowest)

Or directly from your terminal:

npx randsum 2d20    # Roll two twenty-sided dice
npx randsum 4d6L    # Character stat roll (drop lowest)
npx randsum 2d20H   # Roll with advantage

📦 Packages

This monorepo contains the following packages and applications:

@randsum/dice

A Flexible, Type-safe, and Tree-shakeable dice rolling implementation. Where it all started. Optimized for minimal bundle size.

npm install @randsum/dice

@randsum/notation

Dice notation parser and validator, for parsing Randsum Dice Notation.

npm install @randsum/notation

@randsum/5e

A dice roller compatible with 5th Edition RPG Systems

npm install @randsum/5e

@randsum/root-rpg

A dice roller for the Root RPG system.

npm install @randsum/root-rpg

@randsum/blades

A dice roller for Blades in the dark (and forged in the dark) RPG systems.

npm install @randsum/blades

@randsum/salvageunion

A dice roller for the Salvage Union RPG system. Contains all official Salvage Union roll tables, and a contextual roll function for determining success.

npm install @randsum/salvageunion

@randsum/core

Internal package containing shared utilities and types. Not intended for direct usage. All types are exported in each subsequent package for ease of use.

randsum-api

A RESTful API for rolling dice using the RANDSUM dice library. Built with Bun for high performance.

Features

• Roll dice using standard dice notation via HTTP requests
• Support for all RANDSUM modifiers (drop, reroll, cap, etc.)
• Simple, well-documented endpoints
• JSON responses with detailed roll results

Example Usage

# Roll two twenty-sided dice
curl "http://localhost:3000/roll?notation=2d20"

# Roll 4d6, drop lowest (common for D&D character creation)
curl "http://localhost:3000/roll?notation=4d6L"

# Roll with advantage (2d20, keep highest)
curl "http://localhost:3000/roll?notation=2d20H"

Response Example

{
  "result": {
    "total": 15,
    "rolls": [7, 8],
    "rawRolls": { "key": [7, 8] },
    "modifiedRolls": { "key": { "rolls": [7, 8], "total": 15 } },
    "rawResult": [7, 8],
    "result": [7, 8],
    "type": "numerical"
  },
  "params": {
    "notation": "2d20"
  },
  "notation": "2d20"
}

🛠️ Development

This is a monorepo powered by Moon and Bun. To get started:

# Clone the repository
git clone https://github.com/RANDSUM/randsum.git
cd randsum

# Install dependencies for all packages
bun install

# Build all packages
bun moon :build

# Run tests
bun moon :test

# Run type checks
bun moon :tsCheck

# Lint and format
bun moon :lint
bun moon :format

Moon Tasks

Moon manages our task pipeline and dependencies. Common tasks include:

• :build - Build all packages
• :test - Run all tests
• :lint - Run ESLint checks
• :format - Run Prettier checks
• :tsCheck - Run TypeScript checks
• :publish - Publish packages (CI only)
• :lint:fix - Run ESLint and fix issues
• :format:fix - Run Prettier and fix formatting issues
• :ci - Run all checks (build, test, lint, format, tsCheck)

Each package can be targeted directly with moon [package]:task, for example:

bun moon dice:test    # Run tests for @randsum/dice only
bun moon blades:build # Build @randsum/blades only

Further Reading

• Getting Started - Installation and Documentation for using randsum

• Randsum Dice Notation - A guide for using Dice Notation with randsum.

• Bundle Size Optimization - Guide to minimizing bundle size when using RANDSUM packages.

• Contributing - help make randsum better!

• Moon Documentation - Learn more about the build system powering this monorepo

• Sophie's Dice Notation - a great dice notation guide that helped me along the way

• _why's poignant guide to ruby - _why not?

Use Cases

Randsum is perfect for:

• Virtual Tabletop Applications - Implement dice rolling for online tabletop RPG platforms
• Game Development - Add dice mechanics to digital games
• RPG Character Builders - Generate character stats and automate dice-based calculations
• Discord Bots - Create dice rolling bots for gaming communities
• Probability Simulations - Run and analyze dice roll statistics
• Educational Tools - Teach probability concepts with interactive dice simulations
• Board Game Companions - Digital companions for physical board games

Why Choose Randsum?

• Type Safety - Full TypeScript support with intelligent type inference
• Modular Design - Use only what you need with tree-shakeable packages
• Comprehensive - Support for multiple game systems out of the box
• Extensible - Easy to extend for custom game systems
• Well-Documented - Clear examples and comprehensive API documentation
• Actively Maintained - Regular updates and responsive maintainers
• Performance Focused - Optimized for speed and minimal bundle size

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to your branch
5. Open a Pull Request

Please read our Contributing Guidelines for more details.

Why did you make this?

Sometime around 2012, I decided I wanted to learn to program. I had installed ruby on the best laptop six-hundred dollars could buy, set to make a dice roller as an easy first project.

I spent an easy 30 minutes trying to figure out how to make rand(n) return 1...n instead of 0...(n-1).

When I found the answer, I laughed and laughed. I've been chasing that high ever since.

---

Made with 👹 by RANDSUM