Dnd-dice-roll NPM

D&D Dice Roll NPM Package

A lightweight and versatile dice-rolling package for D&D and other tabletop RPGs. This package supports rolling various types of dice, applying modifiers, and even simulating advantage (inspiration) and disadvantage (disspiration).

Version 1.2.0

Replaced inspiration() and disspiration() with advantage() and disadvantage() methods.
added abilityScore() method.
added hundredSides() method.

Installation

Install the package via npm:

npm install dnd-dice-roll

Usage

Import the package in your project:

import rollDice from 'dnd-dice-roll';

Basic Rolls

Roll a single d20:

console.log(rollDice.twentySides());
// Example output: 15

Roll 3d6 with a +2 modifier:

console.log(rollDice.numberOfRolls(3).sixSides(2));
// Example output: 14

Helper Methods

`roll()`

Explicitly returns the total roll value.

const roll = rollDice(1, 20);
console.log(roll.roll());
// Example output: 12

`advantage()`

Simulates rolling with advantage by rolling an additional die and taking the higher result.

console.log(rollDice.twentySides().advantage());
// Example output: 18 (higher of the two rolls)

`disadvantage()`

Simulates rolling with disadvantage by rolling an additional die and taking the lower result.

console.log(rollDice.twentySides().disadvantage());
// Example output: 10 (lower of the two rolls)

`average()`

Returns the average of the rolls, including any modifiers.

console.log(rollDice.numberOfRolls(5).sixSides().average());
// Example output: 3.80

`noZero()`

Ensures the total roll value is at least 1.

console.log(rollDice.twentySides(-20).noZero());
// Example output: 1

`minValue(min)`

Ensures the total roll value is at least the specified minimum.

console.log(rollDice.tenSides(-5).minValue(10));
// Example output: 10

`abilityScore()`

Returns an object with the results of rolling 4d6, discarding the lowest roll, and summing the remaining three.

console.log(rollDice.abilityScore());
// Example output: { roll1: 4, roll2: 6, roll3: 3, roll4: 2, total: 15 }

Predefined Dice Rollers

The package includes shortcuts for common dice types:

fourSides(numRolls = 1, modifier = 0)
sixSides(numRolls = 1, modifier = 0)
tenSides(numRolls = 1, modifier = 0)
twentySides(numRolls = 1, modifier = 0)
hundredSides(numRolls = 1, modifier = 0)

Example:

console.log(rollDice.fourSides());
// Example output: 3
console.log(rollDice.hundredSides(2, 5));
// Example output: 112

Chaining Methods

Methods like .noZero(), .inspiration(), and .disspiration() can be chained for complex rolls.

console.log(rollDice.numberOfRolls(3).sixSides(-2).noZero().inspiration());
// Example output: 12

Error Handling

The package ensures valid inputs:

Number of Rolls: Must be a positive integer.
Number of Sides: Must be a positive integer.
Modifier: Must be an integer.

Invalid inputs throw an error.

Example:

try {
    console.log(rollDice(-1, 6));
} catch (error) {
    console.error(error.message);
    // Output: Number of rolls must be a positive integer.
}