RDN v0.9.0 Level 4 (Full) Conformant — implements the complete RANDSUM Dice Notation Specification
📦 Monorepo Structure
This repository contains multiple packages and applications for dice rolling and tabletop RPG mechanics:
Core Packages (published to npm)
- @randsum/roller - Zero-dependency dice rolling engine with built-in notation parsing and validation
- @randsum/games - TTRPG game packages with subpath exports per system:
@randsum/games/blades - Blades in the Dark@randsum/games/daggerheart - Daggerheart@randsum/games/fifth - D&D 5th Edition@randsum/games/pbta - Powered by the Apocalypse@randsum/games/root-rpg - Root RPG@randsum/games/salvageunion - Salvage Union
- @randsum/cli - One-shot CLI for rolling dice notation from the terminal
Applications (private)
🚀 Quick Example
import { roll } from "@randsum/roller"
// Argument types: number, notation string, or options object
roll(20) // Number: 1d20 (returns 1-20)
roll("1d20") // Notation: same as above
roll({ sides: 20, quantity: 1 }) // Object: same as above
// Complex dice notation
roll("4d6L") // Roll 4d6, drop lowest
// Options object (equivalent to 4d6L)
roll({ sides: 6, quantity: 4, modifiers: { drop: { lowest: 1 } } })
// Advantage and disadvantage
roll("2d20L") // Roll with advantage (2d20, drop lowest)
roll("2d20H") // Roll with disadvantage (2d20, drop highest)
// Multiple arguments: combine rolls
roll("1d20+5", "2d6+3") // Attack roll + damage roll
roll("4d6L!R{<3}") // Roll 4d6, drop lowest, reroll below 3
Or directly from your terminal:
npx @randsum/cli 2d20 # Roll two twenty-sided dice
npx @randsum/cli 4d6L # Character stat roll (drop lowest)
npx @randsum/cli 2d20L # Roll with advantage (drop lowest)
echo 4d6L | npx @randsum/cli # Read notation from stdin (pipe mode)
🛠️ Development
This monorepo uses Bun for package management, building, and task execution.
Getting Started
# Clone the repository
git clone https://github.com/RANDSUM/randsum.git
cd randsum
# Install dependencies for all packages
bun install
# Build all packages (roller is built first, then others)
bun run build
# Run tests
bun run test
# Run type checks
bun run typecheck
# Lint and format
bun run lint
bun run format
Monorepo Workflow
Bun's workspace features handle tasks across all packages with automatic dependency management:
Global Tasks (run across all packages):
bun run build - Build all packages in dependency order (roller first, then others)bun run test - Run all testsbun run lint - Run ESLint checks across the monorepobun run typecheck - Run TypeScript checks for all packagesbun run check:all - Run all package-level checks (build, typecheck, lint, format, test)bun run fix:all - Run ESLint with auto-fix and format codebun run format - Format code using Prettier
Package-Specific Tasks:
bun run --filter @randsum/roller test # Run tests for @randsum/roller only
bun run --filter @randsum/games build # Build @randsum/games only
Site-Specific Tasks:
bun run site:build # Build the documentation site
bun run site:dev # Start the documentation site dev server
Bun automatically handles inter-package dependencies through workspace linking, ensuring packages are built in the correct order.
📚 Documentation
Key Resources
