This repository contains multiple packages and applications for dice rolling and tabletop RPG mechanics:
- @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
- @randsum/discord-bot - Discord bot with dice rolling capabilities using discord.js and Bun
- @randsum/site - Documentation and marketing website built with Astro
- @randsum/mcp - Model Context Protocol server for AI integration
All packages are built with TypeScript, thoroughly tested, and published to NPM with full type definitions.
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("2d20H") // Roll with advantage (2d20, keep highest)
roll("2d20L") // Roll with disadvantage (2d20, keep lowest)
// Multiple arguments: combine rolls
roll("1d20+5", "2d6+3") // Attack roll + damage roll
roll("4d6L!R{<3}") // Roll 4d6, drop lowest, reroll below 3Or 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 advantageThis monorepo uses Bun for package management, building, and task execution.
# 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 formatBun'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- Complete CI pipeline (lint, format check, typecheck, 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/blades build # Build @randsum/blades only
bun run --filter @randsum/mcp typecheck # Type check the MCP serverSite-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 locallyBun automatically handles inter-package dependencies through workspace linking, ensuring packages are built in the correct order.
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
- 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?
The documentation site (@randsum/site) is automatically deployed to:
- Netlify: Configured via
apps/site/netlify.tomland deployed on push to main - GitHub Pages (Repository): Deployed to the
gh-pagesbranch via GitHub Actions - GitHub Pages (Organization): Deployed to
randsum.github.iorepository 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.
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.
Though this project predates the existence of Large learning machines by a clean decade, since their popularization I have used LLM (so-called "AI") tools while making this library. I've used a collection of different tools or models - I prefer the Claude collection of models, though I've played with a lot of it. I spent a lot of time with Augment, then Cursor, now I dance between Claude and Cursor and staring in the mirror wondering what happened.
Is the use of this profane? Is my work perma-tainted? I don't know. The type-ahead (powered by LLM's) suggests I say "I am not ashamed", and so I remain comforted that it is not yet able to accurately imitate my mind.
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, with programming ("what the machines do for me") is the closest thing I have to a craft. One grandfather was an engineer, the other a bricklayer. In my career thus far, I have been blessed to be some combination of both.
You can be grateful for the efficiency and still mourn what it cost. You can use the tools every day and still feel the weight of what they’ve changed about your craft, your career, your sense of what it means to be good at this.The code was never the point, maybe. But for a lot of us, it felt like it was. And that feeling doesn’t just disappear because the tools got better.
- Dave Kiss, Stop Calling it Vibe Coding