1.3.2 • Public • Published


NPM bundle size NPM downloads per week GitHub open issues GitHub open Pull Requests License GitHub version NPM version


Via npm:

npm i easydice

Try on RunKit

Getting started

After you have installed the package, import it like this:

let EasyDice = require('easydice')
let die = new EasyDice()
// Creates a single die with 6 sides by default
let result = die.throw()
// Returns the result as an integer, since there is a single die
// Use your result
// player.position += result
let die2 = new EasyDice(20)
// Creates a single die with 20 sides
let result2 = die2.throw()
// Returns the thrown value as a number

In some games you decide which player starts by getting everyone to throw a die, and whoever has highest, goes first.

let playerCount = 2
let dice = new EasyDice({ count: playerCount })
// Creates two dice with 6 sides each
let startingThrow = dice.throw()
// Throw both dice, returns an array since there are multiple dice
let whichPlayerStarts = []
while (Array.isArray(whichPlayerStarts)) {
  whichPlayerStarts = dice.throw().highestIndex()
let dice = new EasyDice("5d20") // lowercase or uppercase d can be used
// Creates 5 dice with 20 sides each


The package uses Math.random() internally, so it can be considered random enough for dice. The results should be equally distributed.

You can test it if unsure with a code example like this:

let EasyDice = require('easydice')
let testDie = new EasyDice()
let count = Array(6).fill(0)
for (let i = 0; i < 10000000; i++) {
  count[testDie.throw() - 1]++
console.log(EasyDice.highestValue(count) - EasyDice.lowestValue(count))

Most of the time you will end up with values that are pretty close together


You can specify properties of the dice by giving the constructor some values:

new EasyDice() Returns a die with 6 sides.
new EasyDice(s) Returns a die with s sides.
new EasyDice(s, n) Returns n dice with s sides.
new EasyDice(arr) Returns a custom die where the outcome is any element of arr, with equal probability.
new EasyDice(arr, prob) Returns a custom die where the outcome is any element of arr, with the corresponding relative probability in prob.
new EasyDice(arr, n) Returns n custom dice where the outcome for each die is any element of arr, with equal probability.

You can set more properties by instead passing an object to the constructor.

new EasyDice(obj) Returns dice according to the following table
min specifies the minimum value for the di(c)e (default: 1)
max specifies the maximum value for the di(c)e (default: 6)
count specifies the number of dice (default: 1)
values specifies that this is a custom die with outcomes from the array (default: undefined)
probabilites specifies the relative probabilities of all items in

For example:

new EasyDice({ count: 2 }) Returns 2 dice with 6 sides each.
new EasyDice({ values: ["red", "green", "blue"]}) Returns a die where a throw will result in either "red", "green" or "blue".

New in v1.3.1

EasyDice now has convenience initializers for regular polyhedra:

EasyDice.tetrahedron(c) Returns c tetrahedron shaped dice (4 sides)
EasyDice.hexahedron(c) Returns c cube shaped dice (6 sides)
EasyDice.cube(c) Returns c cube shaped dice (6 sides)
EasyDice.octahedron(c) Returns c octahedron shaped dice (8 sides)
EasyDice.dodecahedron(c) Returns c dodecahedron shaped dice (12 sides)
EasyDice.icosahedron(c) Returns c icosahedron shaped dice (20 sides)

In some RPG games you specify dice with CdM where C is the count of dice and M is the maximum value.

new EasyDice('CdM') Returns C dice with M being the maximum value for each.

C defaults to 1, M defaults to 6.

You can throw the di(c)e with .throw().

New in v1.3.0

It can also take in a number as an argument (.throw(n)), which results in an array of n throws. If n is one, a single Result object is returned.

New in v1.3.0

EasyDice objects now have a .history array, which contains all previously thrown values. If multiple throws are asked at a single time, history still contains them as a flattened array.

If there are more than 1 dice, the returned array contains some special functions:

let EasyDice = require('easydice')
let die = new EasyDice({ count: 2 })
let result = die.throw()

result now has the following special functions:

result.sum() Returns the sum of all thrown dice
result.product() Returns the product of all thrown dice
result.highestIndex() Returns the highest thrown value's index as an integer, or an array if there is a tie
result.highestValue() Returns the highest thrown value
result.lowestIndex() Returns the lowest thrown value's index as an integer, or an array if there is a tie
result.lowestValue() Returns the lowest thrown value
result.notHighestIndex() Returns the all but the highest value's indices as an array
result.notHighestValue() Returns the all but the highest thrown value as an array
result.notLowestIndex() Returns the all but the lowest value's indices as an array
result.notLowestValue() Returns the all but the lowest thrown value as an array

Note: min and max are prioritized over values and probabilities. Do not use the special functions if values is used and it contains elements that are not numbers.


GitHub contributors GitHub commits per month

You are welcome to open Pull Requests which add new functionality, contain bugfixes or general improvements to the code.


This package is licensed with MIT license. See LICENSE for details.

Package Sidebar


npm i easydice

Weekly Downloads






Unpacked Size

17.3 kB

Total Files


Last publish


  • danifoldi