https://github.com/2bad/dice
Compute dice rolls according to RPG dice notation (e.g. 1d4, d6, 2d6+5, 1d20-1)
https://github.com/2bad/dice
d20 dice dice-roller dice-rolls dnd dnd-tools dnd5e rng roll rpg ttrpg
Last synced: 24 days ago
JSON representation
Compute dice rolls according to RPG dice notation (e.g. 1d4, d6, 2d6+5, 1d20-1)
- Host: GitHub
- URL: https://github.com/2bad/dice
- Owner: 2BAD
- License: mit
- Created: 2023-05-15T23:41:43.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2025-05-12T06:06:57.000Z (28 days ago)
- Last Synced: 2025-05-15T22:16:07.258Z (24 days ago)
- Topics: d20, dice, dice-roller, dice-rolls, dnd, dnd-tools, dnd5e, rng, roll, rpg, ttrpg
- Language: TypeScript
- Homepage:
- Size: 790 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Dice
[](https://www.npmjs.com/package/@2bad/dice)
[](https://www.npmjs.com/package/@2bad/dice)
[](https://github.com/2BAD/dice/actions/workflows/build.yml)
[](https://codecov.io/gh/2BAD/dice)
[](https://github.com/2BAD/dice/search?l=typescript)
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`.
## Install
```shell
npm install @2bad/dice
```
**Warning:** This package is native [ESM](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and no longer provides a CommonJS export. If your project uses CommonJS, you will have to [convert to ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) or use the [dynamic `import()`](https://v8.dev/features/dynamic-import) function. Please don't open issues for questions regarding CommonJS / ESM.
## Usage
```typescript
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, 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.
## Backus–Naur form grammar for dice roll string syntax
```
::= ? "d" ?
::= ("+" | "-")
::= |
::= *
::= "0" |
::= "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.
## 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.