EasyDice

Install

Via npm:

npm i easydice

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

Randomness

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(count)
console.log(EasyDice.highestValue(count) - EasyDice.lowestValue(count))

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

Documentation

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.

Contribution

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

License

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