## README

# 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.