Skip to content
RANDSUMroller

Roll Options

Configure dice rolls with numbers, notation strings, options objects, or any combination.

Pass a number to roll a single die with that many sides.

Pass a dice notation string. See the Notation Syntax Guide for full syntax.

Pass a RollOptions object for full programmatic control.

import { roll } from '@randsum/roller'
roll({
sides: 6,
quantity: 4,
modifiers: {
drop: { lowest: 1 }
}
})

Pass multiple arguments to combine rolls into a single total.

import { roll } from '@randsum/roller'
// Attack + damage
roll('1d20+5', '2d6+3')
// Mix argument types
roll(20, '2d6', { sides: 8, quantity: 1, modifiers: { plus: 3 } })

The RollOptions interface provides full control over a roll.

interface RollOptions<T = string> {
sides: number | T[] // required
quantity?: number
arithmetic?: 'add' | 'subtract'
modifiers?: ModifierOptions
key?: string | undefined
label?: string | undefined
}

Number of sides on each die, or an array of custom face values.

import { roll } from '@randsum/roller'
// Numeric sides
roll({ sides: 20 })
// Custom faces
roll({ sides: ['+', '+', ' ', ' ', '-', '-'], quantity: 4 })

Number of dice to roll. Defaults to 1.

import { roll } from '@randsum/roller'
roll({ sides: 6, quantity: 4 }) // 4d6

How this roll combines with others in a multi-roll expression. Either 'add' (default) or 'subtract'.

import { roll } from '@randsum/roller'
// 2d12 minus 1d6
roll(
{ sides: 12, quantity: 2 },
{ sides: 6, quantity: 1, arithmetic: 'subtract' }
)

An object containing modifier options. See the Modifiers reference for all available modifiers.

import { roll } from '@randsum/roller'
roll({
sides: 6,
quantity: 4,
modifiers: {
drop: { lowest: 1 },
reroll: { exact: [1] },
plus: 5
}
})
// More modifiers
roll({
sides: 6,
quantity: 5,
modifiers: { wildDie: true } // D6 System wild die
})
roll({
sides: 6,
quantity: 4,
modifiers: { integerDivide: 2 } // Integer divide total
})
roll({
sides: 6,
quantity: 4,
modifiers: { modulo: 3 } // Total modulo 3
})
roll({
sides: 10,
quantity: 5,
modifiers: { count: { lessThanOrEqual: 3 } } // Count failures <= 3
})

Optional string identifier for this roll in multi-roll expressions. Defaults to Roll 1, Roll 2 and so on. Game packages use it to tell dice apart, such as the Hope and Fear dice in Daggerheart.

Optional annotation carried through to the roll record, the same as [fire] in 2d6[fire]. It does not change the result.

An optional final argument to roll() that configures execution behavior.

interface RollConfig {
randomFn?: RandomFn
}

Override Math.random with your own random number generator. Must return a number in the range [0, 1).

import { roll } from '@randsum/roller'
// Crypto-based randomness
const cryptoRandom = () =>
crypto.getRandomValues(new Uint32Array(1))[0] / 2 ** 32
roll('2d6', { randomFn: cryptoRandom })

The roll() function returns a RollerRollResult object.

import { roll } from '@randsum/roller'
const result = roll('4d6L+2')
console.log(result.total) // Final total after all modifiers
console.log(result.values) // Every die value across all groups
console.log(result.rolls) // Array of RollRecord objects (one per dice group)

The final numeric total after all modifiers, drops, and arithmetic have been applied.

An array of individual die values across all groups. Numeric dice contribute numbers (e.g., [3, 5, 6]); custom-faced dice contribute their faces.

An array of RollRecord objects, one for each dice group in the roll.

interface RollRecord<T = string> {
argument: RollArgument<T> // the input this group came from
notation: DiceNotation // dice notation string
description: string[] // the roll in English
parameters: RollParams<T> // full resolved roll parameters
rolls: number[] // die values after modifiers
initialRolls: number[] // die values before modifiers
modifierLogs: ModifierLog[] // logs from each modifier application
appliedTotal: number // total including arithmetic modifiers
customResults?: T[] // faces, for custom-faced dice
label?: string // annotation, e.g. 'fire'
total: number // total for this group
}

See the API Reference for the full RollRecord and RollParams types.

roll() throws a RandsumError on invalid input. Valid notation written into your code, like roll('4d6L'), never throws, so validate only input that comes from outside your control.

See Error Handling for validation patterns and the full error hierarchy, or the API Reference for isDiceNotation() and validateNotation() signatures.