npm package: @manticorp/gamerng
Description: The most powerful RNG in the world for game use - flexible, performant, seedable, serializable, reliable.
Author: Harry Mustoe-Playfair
Latest version: 0.3.1

# GameRNG - a Game Focussed RNG

This is a random number generator that is:

🏎️ highly performant  
🌱 seedable  
📅 serializable  
⚡flexible input (Chancy!!)  
⌨️ written in TypeScript

And more! It has been designed with **🤸‍♂️ extreme flexibility 🤸‍♂️** in mind

This library is capable of generating:

* Uniform random numbers ```rng.random()```
* Normal random numbers ```rng.normal({ mean: 50, stddev: 10 })```
* Random integers ```rng.randInt()```
* Random uniform/normal numbers/integers in a range ```rng.random(5, 10)```
* Biased random numbers ```rng.random({ skew: -1 })```
* Random numbers from the following distributions:
  * Irwin-Hall
  * Bates
  * Bates Gaussian
  * Bernoulli
  * Exponential
  * Pareto
  * Poisson
  * Hypergeometric
  * Rademacher
  * Binomial
  * Beta-Binomial
  * Beta
  * Gamma
  * Wigner Semicircle
  * Kumaraswamy
  * Hermite
  * Chi-Squared
  * Rayleigh
  * Log-Normal
  * Cauchy
  * Laplace
  * Logistic

It's also able to:

* Roll dice ```rng.dice('2d6+7')```
* Pick random items from a list ```rng.choice(['a', 5, (a) => 'foo'])```
* Pick random items from a weighted/biased list ```rng.weightedChoice({a: 1, b: 2, c: 3})```
* Shuffle arrays ```rng.shuffle(['a', 'b', 'c'])```
* Be called flexibly from a single function ```rng.chancy({min: 5, max: 10}) / rng.chancy('4d10-1')```
* Give you min/max possible results from function calls ```rng.diceMin/diceMax``` and ```rng.chancyMin/chancyMax```

# Installation

Run ```npm install @manticorp/ultraloot``` or include the dist file in browser.

## Browser

Download release and include ultraloot in browser:

```html
<script src="https://unpkg.com/@manticorp/gamerng@latest/dist/gamerng.min.js"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/@manticorp/gamerng/dist/gamerng.min.js"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/gh/manticorp/gamerng@latest/dist/gamerng.min.js"></script>
<! -- or -- >
<script src="dist/gamerng.js"></script>
<script>
  const rng = new GameRng();
  rng.random();
</script>
```

## Node

```ts
const { GameRng } = require('@manticorp/gamerng');
```

## ES Module

```ts
import GameRng from '@manticorp/gamerng';
```

# Usage

## Instantiate

```ts
const rng = new GameRng();

// or with a seed
const mySeed = 'hellothere';
const rng = new GameRng(mySeed);

// seeds can be strings or numbers
const rng = new GameRng(77618576514768);

// you can also seed afterward
const rng = new GameRng();
rng.seed(12345);

// Or call a predictable method statically, or on an instance
const rng1 = new GameRng();
const rng2 = GameRng.predictable(12345);
const rng3 = rng1.predictable(12345);

assert(rng2.getSeed() === rng3.getSeed()); // true
```

## Generate a random number

```ts
const rng = new GameRng('my_seed');

rng.random(); // A uniform random float between [0, 1)
rng.random(0, 10); // A uniform random float between [0, 10)
rng.randInt(0, 10); // A uniform random integer between [0, 10)

rng.normal({ mean: 5, stddev: 1 }); // A normally distributed random float with a mean of 5 and a standard deviation of 1
rng.normal({ min: 0, max: 10 }); // A normally distributed random float with a minimum value of 0 and a maximum value of 10

rng.dice('2d6+10'); // A dice roll of 2 x d6 + 10
rng.diceExpanded('2d6+10'); // returns the following: { dice: [3, 6], plus: 10, total: 19 }

rng.choice([1, 2, 3]); // A random choice from an array, e.g. 2
```

## Chancy

The special ```chancy``` function takes a broad range of inputs.

```ts
rng.chancy(5); // Always returns 5
rng.chancy({min: 1, max: 10}); // Random number between [1, 10), e.g. 2.71828
rng.chancy({min: 5, max: 50, type: 'integer', skew: -1}); // Random uniform integer between [5, 50] with a skew to the left / lower numbers, e.g. 10
rng.chancy({type: 'normal', mean: 0, stddev: 1}); // Random normally distributed integer around 0 with a stddev of 1
rng.chancy('2d10+1'); // Rolls the dice string, e.g. 17
rng.chancy([1, 3, 5, 7, 9]); // Picks a random number from the list, e.g. 5
rng.chancy(['a', 'b', 'c']); // Picks a random element from the list (note: this is the only way chancy will not return a number...), e.g. 'a'
```

You can easily use the calling interface anywhere you might want a randomised number with highly flexible input.

There is also a second function called ```chancyInt``` which always returns an integer. Usually uses ```Math.round``` to round things:

```ts
rng.chancyInt(5.3); // Always returns 5
rng.chancyInt({min: 1, max: 10}); // Random number between [1, 10)
rng.chancyInt({min: 5, max: 50, type: 'integer', skew: -1}); // Random uniform integer between [5, 50] with a skew to the left / lower numbers
rng.chancyInt('2d10+0.5'); // e.g. 17
rng.chancyInt([1.1, 3.3, 5.5, 7.7, 9.9]); // e.g 3 or 8
rng.chancyInt(['a', 'b', 'c']); // Will throw an Error
```

# Full Documentation

See the [full docs](https://manticorp.github.io/gamerng) for more information.

[Code docs](https://manticorp.github.io/gamerng/code)    
[Examples](https://manticorp.github.io/gamerng/examples)