Roll Options
Configure dice rolls with numbers, notation strings, options objects, or any combination.
Argument types
Section titled “Argument types”Number
Section titled “Number”Pass a number to roll a single die with that many sides.
Notation string
Section titled “Notation string”Pass a dice notation string. See the Notation Syntax Guide for full syntax.
Options object
Section titled “Options object”Pass a RollOptions object for full programmatic control.
import { roll } from '@randsum/roller'
roll({sides: 6,quantity: 4,modifiers: { drop: { lowest: 1 }}})Multiple arguments
Section titled “Multiple arguments”Pass multiple arguments to combine rolls into a single total.
import { roll } from '@randsum/roller'
// Attack + damageroll('1d20+5', '2d6+3')
// Mix argument typesroll(20, '2d6', { sides: 8, quantity: 1, modifiers: { plus: 3 } })RollOptions
Section titled “RollOptions”The RollOptions interface provides full control over a roll.
interface RollOptions<T = string> {sides: number | T[] // requiredquantity?: numberarithmetic?: 'add' | 'subtract'modifiers?: ModifierOptionskey?: string | undefinedlabel?: string | undefined}sides (required)
Section titled “sides (required)”Number of sides on each die, or an array of custom face values.
import { roll } from '@randsum/roller'
// Numeric sidesroll({ sides: 20 })
// Custom facesroll({ sides: ['+', '+', ' ', ' ', '-', '-'], quantity: 4 })quantity
Section titled “quantity”Number of dice to roll. Defaults to 1.
import { roll } from '@randsum/roller'
roll({ sides: 6, quantity: 4 }) // 4d6arithmetic
Section titled “arithmetic”How this roll combines with others in a multi-roll expression. Either 'add' (default) or 'subtract'.
import { roll } from '@randsum/roller'
// 2d12 minus 1d6roll({ sides: 12, quantity: 2 },{ sides: 6, quantity: 1, arithmetic: 'subtract' })modifiers
Section titled “modifiers”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 modifiersroll({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.
RollConfig
Section titled “RollConfig”An optional final argument to roll() that configures execution behavior.
interface RollConfig {randomFn?: RandomFn}Custom RNG
Section titled “Custom RNG”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 randomnessconst cryptoRandom = () =>crypto.getRandomValues(new Uint32Array(1))[0] / 2 ** 32
roll('2d6', { randomFn: cryptoRandom })Result object
Section titled “Result object”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 modifiersconsole.log(result.values) // Every die value across all groupsconsole.log(result.rolls) // Array of RollRecord objects (one per dice group)
The final numeric total after all modifiers, drops, and arithmetic have been applied.
values
Section titled “values”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 fromnotation: DiceNotation // dice notation stringdescription: string[] // the roll in Englishparameters: RollParams<T> // full resolved roll parametersrolls: number[] // die values after modifiersinitialRolls: number[] // die values before modifiersmodifierLogs: ModifierLog[] // logs from each modifier applicationappliedTotal: number // total including arithmetic modifierscustomResults?: T[] // faces, for custom-faced dicelabel?: string // annotation, e.g. 'fire'total: number // total for this group}See the API Reference for the full RollRecord and RollParams types.
Error handling
Section titled “Error handling”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.