A type-safe implementation of 5th Edition d20 mechanics with advantage/disadvantage.

Installation

npm install @randsum/fifth
# or
bun add @randsum/fifth

Usage

import { roll } from "@randsum/fifth"

// Basic roll with modifier
const result = roll({ modifier: 5 })

// Roll with advantage
roll({
  modifier: 5,
  rollingWith: "Advantage"
})

// Roll with disadvantage
roll({
  modifier: -2,
  rollingWith: "Disadvantage"
})

// Check against DC
const { total } = roll({ modifier: 5 })
const success = total >= 15 // DC 15 check

API Reference

roll(options)

function roll(options: FifthRollArgument): FifthRollResult

Options:

| Parameter | Type | Description | | ------------- | ------------------------------- | --------------------------------- | | modifier | number | Bonus/penalty to add to roll | | rollingWith | 'Advantage' \| 'Disadvantage' | Roll 2d20 and keep highest/lowest |

Returns:

interface FifthRollResult {
  total: number
  result: "natural_20" | "natural_1" | "standard"
  details: { modifier: number }
  rolls: RollRecord[]
}

Related Packages

• @randsum/roller - Core dice rolling