Getting Started with Roller

Install @randsum/roller and roll your first die in under a minute.

Install

bun add @randsum/roller

npm install @randsum/roller

yarn add @randsum/roller

Your first roll

import { roll } from '@randsum/roller'

const result = roll(20)
console.log(result.total) // a number between 1 and 20

Pass a number to roll() and it rolls one die with that many sides. The return value is a typed result object with a total property.

Notation strings

RANDSUM supports standard dice notation. The format is NdS — N dice with S sides.

import { roll } from '@randsum/roller'

roll('2d6')      // two six-sided dice
roll('4d8')      // four eight-sided dice
roll('1d20+5')   // one d20, add 5 to the total
roll('4d6L')     // four d6, drop the lowest

Try changing the notation in the playground above. See the Randsum Dice Notation Spec for the full syntax.

Options object

Every notation string has an equivalent options object. Use this when you need programmatic control:

import { roll } from '@randsum/roller'

// These are equivalent:
roll('4d6L')
roll({
sides: 6,
quantity: 4,
modifiers: { drop: { lowest: 1 } }
})

See Roll Options for the full options API.

Result object

roll() returns a RollerRollResult with three key properties:

import { roll } from '@randsum/roller'

const result = roll('4d6L+2')

result.total   // Final total after all modifiers
result.values  // String representations of die values, e.g. ['3', '5']
result.rolls   // Array of RollRecord objects with full history

Each entry in result.rolls is a RollRecord containing the original rolls, modifier logs, and final values for that dice group.

Multiple groups

Roll different dice types in a single call. The total sums across all groups:

import { roll } from '@randsum/roller'

// Attack + damage in one call
const result = roll('1d20+5', '2d6+3')
console.log(result.total)  // combined total
console.log(result.rolls)  // two RollRecord entries

Testing your rolls

Inject a custom random function to make rolls deterministic in tests:

import { roll } from '@randsum/roller'

function seededRandom(seed: number) {
let s = seed
return () => {
  s = (s * 1664525 + 1013904223) % 2 ** 32
  return s / 2 ** 32
}
}

// Pass { randomFn } as the last argument
const result = roll('2d6', { randomFn: seededRandom(42) })
// Same seed always produces the same total

The randomFn must return a number in [0, 1) — the same contract as Math.random(). Pass it as the last argument in a RollConfig object.

What’s next

Roll Options — all options object fields and argument types
Modifiers — drop, keep, reroll, explode, cap, and more
Error Handling — how roll() validates input and what errors to expect
API Reference — complete list of exports from @randsum/roller