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 |values|(default: undefined)|

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.