This library makes it easy to compute dice rolls and generate random numbers. Ideal for games, simulations, and more, it supports different types and amounts of dice. You can easily perform calculations using RPG-style dice notation like 1d4, d6, 2d6+5, 1d20-1.

npm install @2bad/dice

Warning: This package is native ESM and no longer provides a CommonJS export. If your project uses CommonJS, you will have to convert to ESM or use the dynamic import() function. Please don't open issues for questions regarding CommonJS / ESM.

import { roll } from '@2bad/dice'

// Roll a six-sided die with lowercase 'd'
roll('d6')
// same as
roll('D6')

// Roll two eight-sided dice
roll('2d8')

// Roll two twenty-sided dice
roll('2d20').

In addition to rolling a single die or multiple dice, it can also handle roll modifiers. A modifier is a number added to or subtracted from the total value obtained from the dice rolls. For instance, in DnD, instead of just rolling a 20-sided die (d20), you might also add a modifier to reflect a character's skill or level.

To roll a dice with a modifier, just include a plus (+) or minus (-) sign and another integer at the end of your dice-roll string. Here are some examples:

• 2d6+3: Roll two six-sided dice and add 3 to the total value.
• d20-1: Roll a single 20-sided die and subtract 1 from the total value.
• 3d8+12: Roll three eight-sided dice and add 12 to the total value.

Note that the modifier applies to the entire result of the dice roll, not the individual die roll. When using a modifier, it's important to check the rules of your game system to determine which calculations are appropriate.

<dice-notation>   ::= <non-zero-number>? "d" <non-zero-number> <modifier>?
<modifier>        ::= ("+" | "-") <non-zero-number>
<non-zero-number> ::= <non-zero-digit> | <number>
<number>          ::= <non-zero-digit> <digit>*
<digit>           ::= "0" | <non-zero-digit>
<non-zero-digit>  ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

This BNF grammar defines the syntax for a dice notation, which consists of an optional non-zero number of dice to be rolled and a number of sides each die has, optionally followed by a modifier that can be added to or subtracted from the result of the roll.

We welcome contributions! If you find a bug or want to request a new feature, please open an issue. If you want to submit a bug fix or new feature, please open a pull request.