@ms-sol/dice-roll

This library provides a simple way to interpret and execute dice rolls in the format commonly used in Dungeons & Dragons (D&D) and other tabletop roleplaying games (TTRPGs).

Installation

Install the library using npm or yarn:

npm install @ms-sol/dice-roll

Usage

This library offers two functions:

rollDice(input: string | DiceSetup): number Takes a dice notation string (e.g., "2d6", "4d10", "3d8+2", allowed notations below) as input. Alternatively you can pass DiceSetup interface implementing object which is returned by parseDice function.

Returns an object containing the roll results. The object typically includes properties like the total rolled value, the individual dice rolls, and any modifiers applied.

parseDice(notation: string): DiceSetup | null Parses the dice notation string into a more structured representation (DiceSetup interface). Returns an object with properties:

• count: number of dice
• die: depending on your input this object's descripting (A) the die's minimum, maximum and optional modifier or (B) custom sides of the die.

CommonJS (CJS):

const diceRoll = require('@ms-sol/dice-roll');

const result = diceRoll.rollDice('2d6');
console.log(result); // result from 2*1=2 till 2*6=12

ES Modules (ESM):

Importing specific functions:

import { rollDice, parseDice } from '@ms-sol/dice-roll';

const result = rollDice('3d8');
console.log(result); // result from 3*1=3 till 3*8=24

Importing the entire library:

import diceRoll from '@ms-sol/dice-roll';

const result = diceRoll.rollDice('4d10');
console.log(result); // result from 4*1=4 till 4*10=40

Allowed input string formats

"d6" // standard 6-sided die
"3d4" // three 4-sided dice

"d4+2" // 4-sided die with +2 modifier to die roll result
"d4-2" // 4-sided die with -2 modifier to die roll result

"4-17" // range from 4-17, equivalent of d14+3

"2d[10,20,30,40,50,60]" // two dice with 6 custom sides (10,20,30,40,50,60)
"2d[10,20,30,40,50,60]+5" // as above but with additional +5 modifier to dice roll result

// HINT: any spaces you input are discarded
" d 4 - 2" // will be treated as "d4-2"

// HINT 2: both lower- and uppercase 'd' are allowed
" D 4 - 2" // will be treated as "d4-2"

Calculating result probability

It might be usefull to calculate the probability of a given result in certain dice setup.

// use string dice setup
calculateProbability('d6', 1) // returns 0.1667 (16.67%)

// or parsed object
const diceSetup = parseDice('d6');
calculateProbability(diceSetup, 1) // returns 0.1667 (16.67%)

License

This library is licensed under the MIT License. See the LICENSE file for details.