pink-coin/README.md

A random bit (coin flip) that you can change the behavior of

# pink-coin

Flip for a random true/false value. By default, a PinkCoin acts as you would expect a normal coin to, however, you can adjust its behavior. Want a player to receive a "random" bonus at the end of a fight with a 5% chance, but don't want them to go more than 20 fights without getting it? Initiate the coin with

```js
const PinkCoin = require("pink-coin");
const coin = new PinkCoin({ initialProbability: 0.05, maxConsecutive: 20 });
```

then use the didChange property on the flip result to see if the player receives the bonus

```js
if (coin.next().didChange === true) {
  // grant bonus
}
```

The coin above will behave with a 5% chance of changing from heads to tails (which will set didChange to true) until it misses 20 times, then there will be a 100% chance of triggering.

## Options

`maxConsecutive` :<br/>
The maximum number of times heads or tails can appear in a row.<br/>
Default : Number.POSITIVE_INFINITY

`initialProbability` :<br/>
The probability of changing from heads to tails or tails to heads (where didChange is true).<br/>
Default : 0.5

`randomFunction` : <br/>
The function used by the coin to generate random, or pseudorandom, numbers used to update the state.<br/>
Default : Math.random

`adjustmentScale` : <br/>
The function used to adjust the probability of a change event occurring for every time it doesn't occur.<br/>
Default : (x) => Math.pow(x, Number.MAX_SAFE_INTEGER) (This means the probability is effectively unchanged until the maxConsecutive value is reached then it is 1)