Roll Options

The roll() function is the main entry point for all dice rolling in RANDSUM. It accepts several argument types and never throws — errors are returned in the result object.

Argument types

Number

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

roll(20)  // Roll 1d20
roll(6)   // Roll 1d6
roll(100) // Roll 1d100

Notation string

Pass a dice notation string. See the Dice Notation reference for full syntax.

roll('2d6')     // Roll 2d6
roll('4d6L')    // Roll 4d6, drop lowest
roll('1d20+5')  // Roll 1d20 + 5

Options object

Pass a RollOptions object for full programmatic control.

roll({
  sides: 6,
  quantity: 4,
  modifiers: {
    drop: { lowest: 1 }
  }
})

Multiple arguments

Pass multiple arguments to combine rolls into a single total.

// Attack + damage
roll('1d20+5', '2d6+3')

// Mix argument types
roll(20, '2d6', { sides: 8, quantity: 1, modifiers: { plus: 3 } })

RollOptions

The RollOptions interface provides full control over a roll.

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

`sides` (required)

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

// Numeric sides
roll({ sides: 20 })

// Custom faces (e.g., Fate dice)
roll({ sides: ['+', '+', ' ', ' ', '-', '-'], quantity: 4 })

`quantity`

Number of dice to roll. Defaults to 1.

roll({ sides: 6, quantity: 4 }) // 4d6

`arithmetic`

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

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

`modifiers`

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

roll({
  sides: 6,
  quantity: 4,
  modifiers: {
    drop: { lowest: 1 },
    reroll: { exact: [1] },
    plus: 5
  }
})

`key`

Optional string identifier for this roll in multi-roll expressions. Used by game packages to identify individual dice (e.g., hope/fear dice in Daggerheart).

RollConfig

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

interface RollConfig {
  randomFn?: RandomFn
}

Custom random function

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

// Crypto-based randomness
const cryptoRandom = () =>
  crypto.getRandomValues(new Uint32Array(1))[0] / 2 ** 32

roll('2d6', { randomFn: cryptoRandom })

Result object

The roll() function returns a RollerRollResult object.

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

result.total   // Final total after all modifiers
result.rolls   // Array of RollRecord objects (one per dice group)

`total`

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

`rolls`

An array of RollRecord objects, one for each dice group in the roll. Each record contains:

Individual die results before and after modifiers
Modifier logs showing what changed
The notation and options used

Error handling

roll() never throws. If the input is invalid, an error is returned in the result:

const result = roll('invalid')
if (result.error) {
  console.error(result.error) // Error description
}

Validation utilities

`isDiceNotation(value: string): value is DiceNotation`

Type guard that checks if a string is valid dice notation.

import { isDiceNotation } from '@randsum/roller'

if (isDiceNotation(userInput)) {
  // userInput is typed as DiceNotation
  const result = roll(userInput)
}

`validateNotation(notation: string): ValidationResult`

Validates notation and returns a parsed structure or error.

import { validateNotation } from '@randsum/roller'

const validation = validateNotation('4d6L')
// Returns parsed structure with sides, quantity, modifiers