RANDSUM roller
Write the roll, get every step back
The dice engine. Parses any notation, rolls it, and tells you what each modifier changed and why the total is what it is.
import { roll } from '@randsum/roller'
const { total, rolls } = roll('4d6L')rolls[0].description // ['Roll 4 6-sided dice', 'Drop lowest']Roll dice with a single function call: numbers, notation strings, or options objects. @randsum/roller is the core engine that powers the entire RANDSUM ecosystem: full TypeScript types, strict input validation, and zero dependencies. Notation parsing is built in.
Features
Section titled “Features”- Three input modes: pass a number, a notation string, or a typed options object
- Advanced notation: drop/keep, reroll, exploding, compounding, penetrating, cap, replace, unique, count successes/failures, wild die, integer division, modulo, annotations, and repeat
- Special dice: geometric die (
gN), draw die (DDN), percentile (d%), and Fate/Fudge (dF) - Modifier pipeline: modifiers execute in a defined priority order, composable and predictable
- Multiple arguments: combine rolls into a single total:
roll('1d20+5', '2d6') - Strict validation: throws on invalid input; validate user strings with
isDiceNotation()orvalidateNotation() - Custom RNG: pass a
randomFnfor seeded, deterministic, or cryptographic randomness - Universal runtime: works in Node.js, Bun, Deno, browsers, and edge functions
Argument types
Section titled “Argument types”Number
Section titled “Number”Pass a number to roll one die with that many sides.
import { roll } from '@randsum/roller'
const result = roll(20)console.log(result.total) // 1-20Notation string
Section titled “Notation string”Pass a RANDSUM Dice Notation string for complex rolls.
import { roll } from '@randsum/roller'
// 4d6, drop the lowestconst abilityScore = roll('4d6L')
// 2d20, keep highest (advantage), add 5const attack = roll('2d20K+5')
// Exploding d6s with rerolls below 3const wild = roll('4d6R{<3}!')
Options object
Section titled “Options object”Pass a typed object for full control over the roll without notation parsing.
import { roll } from '@randsum/roller'
const result = roll({sides: 6,quantity: 4,modifiers: { drop: { lowest: 1 }, plus: 2}})
console.log(result.total) // Sum of best 3d6 + 2All three input types produce the same RollerRollResult, so you can mix them in a single call:
import { roll } from '@randsum/roller'
// Combine multiple arguments into one totalconst result = roll('1d20+5', '2d6')console.log(result.total) // d20 + 5 + 2d6Notation quick reference
Section titled “Notation quick reference”| Pattern | Description | Example |
|---|---|---|
NdS |
Roll N dice with S sides | 4d6 |
+X / -X |
Add/subtract from total | 1d20+5 |
L / H |
Drop lowest/highest | 4d6L |
K / kl |
Keep highest/lowest | 4d6K3 |
! |
Exploding dice | 3d6! |
!! |
Compounding exploding | 3d6!! |
!p |
Penetrating exploding | 3d6!p |
U |
Unique results | 4d20U |
W |
Wild die (D6 System) | 5d6W |
F{N} |
Count failures | 5d10F{3} |
//N |
Integer divide total | 4d6//2 |
%N |
Total modulo | 4d6%3 |
gN |
Geometric die | g6 |
DDN |
Draw die (no replacement) | 3DD6 |
[text] |
Annotation/label | 2d6[fire] |
xN |
Repeat notation | 4d6Lx6 |
See the full Notation Syntax Guide for reroll conditions, caps, replacements, success counting, and multipliers.
Learn more
Section titled “Learn more”- Getting Started: install, first roll, result types
- Roll Options: every option the
roll()function accepts - Modifiers: how the modifier pipeline works, priority order, and examples
- Error Handling: validation patterns for user-provided input
- API Reference: all exported functions and types