@2bad/dice

Dice

TypeScript library that allows you to simulate rolling different types and quantities of dice. You can easily perform calculations and generate random numbers for use in games, simulations, and more.

Install

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.

Usage

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').

Dice-Rolling with Modifier

In addition to rolling a single die or multiple dice, this dice-rolling program can also handle 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, simply 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 each individual die roll. When using a modifier, it's important to check the rules of your game system to determine which calculations are appropriate.

Backus–Naur form grammar for dice roll string syntax

<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 a 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.

Contributing

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.

Changelog

[0.0.3] - 2023-05-16

Added

• Use regular expression to parse dice notation string.
• Calculated and applied any modifiers to the total roll sum.