randsum

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/fate - Fate Core
  • @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)

• @randsum/discord-bot - Discord bot for dice rolling
• @randsum/site - Documentation site built with Astro + Starlight (randsum.dev)
• @randsum/rdn - RANDSUM Dice Notation specification site (notation.randsum.dev)
• @randsum/dice-ui - Web-only React UI components (notation input, roll visualizer) consumed by the docs site

🚀 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("4d6LR{<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 tests
• bun run lint - Run Biome lint across the monorepo
• bun run typecheck - Run TypeScript checks for all packages
• bun run check:all - Run all package-level checks (build, typecheck, lint, format, test)
• bun run fix:all - Run Biome with auto-fix and format code
• bun run format - Format code using Biome

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: