Package Exports
- @randsum/roller
- @randsum/roller/package.json
- @randsum/roller/types
Readme
TypeScript-first dice notation engine for JavaScript and TypeScript. Throw Dice, Not Exceptions.
Installation
npm install @randsum/roller
# or
bun add @randsum/rollerUsage
import { roll } from "@randsum/roller"
// Three ways to roll: number, notation string, or options object
roll(20) // Roll 1d20
roll("4d6L") // Roll 4d6, drop lowest
roll({ sides: 6, quantity: 4, modifiers: { drop: { lowest: 1 } } })
// Complex modifiers
roll("2d20H") // Advantage (keep highest)
roll("4d6!R{<3}") // Exploding dice, reroll below 3
roll("1d20+5", "2d6+3") // Multiple rolls combinedCLI
npx randsum 2d20 # Roll two d20s
npx randsum 4d6L # Roll 4d6, drop lowest
npx randsum 3d8+2 # Roll 3d8 and add 2API
roll(...args)
The main function accepts numbers, notation strings, or options objects.
const result = roll("2d6+3")
result.total // Final total after all modifiers
result.result // Array of individual die values
result.rolls // Full roll records with modifier history
result.error // null on success, RandsumError on failureNotation Reference
| Notation | Description |
|---|---|
4d6 |
Roll 4 six-sided dice |
4d6+2 |
Add 2 to total |
4d6L |
Drop lowest |
4d6H |
Drop highest |
2d20H |
Keep highest (advantage) |
2d20L |
Keep lowest (disadvantage) |
4d6! |
Exploding dice |
4d6R{<3} |
Reroll values below 3 |
4d6U |
Unique rolls only |
See RANDSUM_DICE_NOTATION.md for the complete notation guide.
Other Exports
import {
// Validation
validateNotation,
isDiceNotation,
validateRollOptions,
// Conversion utilities
optionsToNotation,
optionsToDescription,
// Probability analysis
analyze,
// Game system helpers
createGameRoll,
createMultiRollGameRoll,
// Error types
RandsumError,
NotationParseError,
ValidationError
} from "@randsum/roller"Related Packages
- @randsum/blades - Blades in the Dark
- @randsum/daggerheart - Daggerheart
- @randsum/fifth - D&D 5th Edition
- @randsum/root-rpg - Root RPG
- @randsum/salvageunion - Salvage Union
Made with 👹 by RANDSUM