JSPM

  • Created
  • Published
  • Downloads 40
  • Score
    100M100P100Q87970F
  • License MIT

TypeScript-first dice notation engine for tabletop RPGs, game development, and probability simulations

Package Exports

  • @randsum/roller
  • @randsum/roller/package.json
  • @randsum/roller/types

Readme

Randsum Logo. A Dotted D6 rolled a 6 with the dots arranged to look like an R.

@randsum/roller

TypeScript-First Dice Notation Ecosystem

Throw Dice, Not Exceptions.

npm version bundle size Types License Downloads codecov

TypeScript-first dice notation engine for JavaScript and TypeScript. Throw Dice, Not Exceptions.

Installation

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

Usage

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 combined

CLI

npx randsum 2d20    # Roll two d20s
npx randsum 4d6L    # Roll 4d6, drop lowest
npx randsum 3d8+2   # Roll 3d8 and add 2

API

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 failure

Notation 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"
Made with 👹 by RANDSUM