Skip to content
RANDSUMroller

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.

  • 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() or validateNotation()
  • Custom RNG: pass a randomFn for seeded, deterministic, or cryptographic randomness
  • Universal runtime: works in Node.js, Bun, Deno, browsers, and edge functions

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-20

Pass a RANDSUM Dice Notation string for complex rolls.

import { roll } from '@randsum/roller'
// 4d6, drop the lowest
const abilityScore = roll('4d6L')
// 2d20, keep highest (advantage), add 5
const attack = roll('2d20K+5')
// Exploding d6s with rerolls below 3
const wild = roll('4d6R{<3}!')

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 + 2

All 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 total
const result = roll('1d20+5', '2d6')
console.log(result.total) // d20 + 5 + 2d6
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.