Randsum

A comprehensive dice rolling monorepo ecosystem for rolling dice and playing games.

📦 Monorepo Structure

This repository contains multiple packages and applications for dice rolling and tabletop RPG mechanics:

Core Packages

• @randsum/roller - Core dice rolling engine with advanced notation support
• @randsum/blades - Blades in the Dark system mechanics
• @randsum/daggerheart - Daggerheart RPG system support
• @randsum/fifth - D&D 5th Edition mechanics
• @randsum/root-rpg - Root RPG system implementation
• @randsum/salvageunion - Salvage Union mechanics

Applications

• @randsum/mcp - Model Context Protocol server for AI integration
• @randsum/robo - Discord bot with dice rolling capabilities using Robo.js (standalone repository)
• @randsum/site - Documentation and marketing website built with Astro

All packages are built with TypeScript, thoroughly tested, and published to NPM with full type definitions.

🚀 Quick Example

import { roll } from "@randsum/roller"

// Simple d20 roll
roll(20) // Returns 1-20
// or
roll("1d20") // Returns 1-20

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

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

roll("4d6L!R{<3}") // Roll 4d6, drop lowest, reroll below 3

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

🛠️ 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 ESLint checks across the monorepo
• bun run typecheck - Run TypeScript checks for all packages
• bun run check:all - Complete CI pipeline (lint, format check, typecheck, test)
• bun run fix:all - Run ESLint with auto-fix and format code
• bun 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/blades build     # Build @randsum/blades only
bun run --filter @randsum/mcp typecheck    # Type check the MCP server

Site-Specific Tasks:

bun run site:build    # Build the documentation site
bun run site:dev       # Start the development server
bun run site:preview   # Preview the production build locally

Bun automatically handles inter-package dependencies through workspace linking, ensuring packages are built in the correct order.

📚 Documentation

Package Documentation

Each package includes comprehensive documentation:

• API Reference: Generated TypeDoc documentation for all packages
• README Files: Individual package documentation in each packages/*/README.md
• Examples: Usage examples and integration guides

Key Resources

• Randsum Dice Notation - A guide for using Dice Notation with randsum
• Sophie's Dice Notation - a great dice notation guide that helped me along the way
• _why's poignant guide to ruby - _why not?

Website Deployment

The documentation site (@randsum/site) is automatically deployed to:

• Netlify: Configured via packages/site/netlify.toml and deployed on push to main
• GitHub Pages (Repository): Deployed to the gh-pages branch via GitHub Actions
• GitHub Pages (Organization): Deployed to randsum.github.io repository via GitHub Actions

All deployments are triggered automatically on push to the main branch. The site build is included in the CI pipeline via check:all.

🤝 Contributing

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

---

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.

---

LLM Statement

I have used LLM ("AI") tools while making this library. Unless I am mis-remembering, it was entirly Claude Sonnet, used through the tool Augment Code.

I love this thing we call programming. It seems as if this tech might be a part of it moving forward.

You will find the extent of my comfort with these tools in this project, for it is the closest thing I have on this earth to a life's work.

Is the use of this profane? Is my work perma-tainted? I don't know. The type-ahead suggests I say "I am not ashamed", and so I remain comforted that it is not yet able to accurately imitate my mind.

Check the git history of this paragraph (and README, where it used to live.) for a makeshift changelog of my evolving feelings on the subject.

---

Made with 👹 by RANDSUM