# Getting Started with Roller

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

## Install

<CodeExample lang="bash" code={`bun add @randsum/roller`} />
  <CodeExample lang="bash" code={`npm install @randsum/roller`} />
  <CodeExample lang="bash" code={`yarn add @randsum/roller`} />
  ## Your first roll

<CodeExample code={`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.

<NotationRoller defaultNotation="1d20" client:only="react" />

## Notation strings

RANDSUM supports standard dice notation. The format is `NdS` -- **N** dice with **S** sides.

<CodeExample code={`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
roll('5d6W')     // D6 System wild die
roll('4d6Lx6')   // six ability scores (repeat operator)
roll('g6')       // geometric die (roll until 1)`} />

<NotationRoller defaultNotation="4d6L" client:only="react" />

Try changing the notation in the playground above. See the [Randsum Dice Notation Spec](https://randsum.dev/notation/randsum-dice-notation/) for the full syntax.

## Options object

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

<CodeExample code={`// These are equivalent:
roll('4d6L')
roll({
  sides: 6,
  quantity: 4,
  modifiers: { drop: { lowest: 1 } }
})`} />

See [Roll Options](https://randsum.dev/roller/roll-options/) for the full options API.

## Result object

`roll()` returns a `RollerRollResult` with three key properties:

<CodeExample code={`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.

<NotationRoller defaultNotation="4d6L+2" client:only="react" />

## Multiple groups

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

<CodeExample code={`// 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:

<CodeExample code={`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](https://randsum.dev/roller/roll-options/) -- all options object fields and argument types
- [Modifiers](https://randsum.dev/roller/modifiers/) -- drop, keep, reroll, explode, cap, and more
- [Error Handling](https://randsum.dev/roller/error-handling/) -- how `roll()` validates input and what errors to expect
- [API Reference](https://randsum.dev/roller/api-reference/) -- complete list of exports from `@randsum/roller`