Roller

Overview

@randsum/roller is the core dice rolling engine that powers the entire RANDSUM ecosystem. It provides advanced dice notation support, allowing you to express complex rolling mechanics in a concise, readable format.

Whether you're building a simple dice roller or implementing complex tabletop RPG mechanics, Roller provides the foundation you need with full TypeScript support and comprehensive type safety.

Features

• Advanced dice notation (4d6L, 2d20H, etc.)
• Reroll modifiers
• Exploding dice
• Drop/keep modifiers
• Full TypeScript support

Installation

npm install @randsum/roller
# or
bun add @randsum/roller

Examples

import { roll } from '@randsum/roller';

// Simple d20 roll
roll(20); // Returns 1-20
// or
roll('1d20'); // Returns 1-20

import { roll } from '@randsum/roller';

// Roll 4d6, drop lowest (D&D ability scores)
roll('4d6L');

import { roll } from '@randsum/roller';

// Roll with advantage (2d20, keep highest)
roll('2d20H');

// Roll with disadvantage (2d20, keep lowest)
roll('2d20L');

import { roll } from '@randsum/roller';

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

Dice Notation

Roller supports a wide variety of dice notation patterns:

• 1d20 - Roll a single 20-sided die
• 4d6L - Roll 4d6, drop the lowest (D&D ability scores)
• 2d20H - Roll 2d20, keep highest (advantage)
• 2d20L - Roll 2d20, keep lowest (disadvantage)
• 4d6R{1} - Roll 4d6, reroll any 1s
• 3d6! - Roll 3d6 with exploding dice (reroll and add on max)
• 4d6L!R{<3} - Complex: 4d6, drop lowest, reroll below 3, exploding

For more information on dice notation, see the RANDSUM documentation.

TypeScript Support

Roller is built with TypeScript and provides full type definitions. All functions are fully typed, providing excellent IDE support and compile-time safety.