tweed-random

A random number generator.

It aims to provide a clean, memorable API for doing basically everything you'd want to do with random number generation for games, bots and procedural generation.

Numeric and string seeds are supported, it'll generate numbers along custom distribution curves (so you can weight generation toward low or high numbers, for example), it'll shuffle arrays, and has a bunch of handy methods for choosing things from a collection.

The focus is on ease-of-use and programmer comfort rather than speed or cryptographic security, so if those are priorities for you, this probably isn't the package you're looking for.

Installation

Install via yarn or npm.

yarn add tweed-random
npm install --save tweed-random

Usage

Really basic usage:

var RNG = require('tweed-random');

var generator = new RNG();
// or
var generator = new RNG('seeded');

var x = generator.random() * map_width;
var y = generator.random() * map_height;

var numApples = generator.randomInt(0, 5);

var job = generator.choose(['Mayor', 'Baker', 'Alchemist']);
var deck = generator.shuffle(['A', 'K', 'Q', 'J', '10', '9', ...]);

Nifty usage:

var RNG = require('tweed-random');

var generator = new RNG('another seed');
var straws = ['long', 'long', 'long', 'long', 'short'];
var myChoice = generator.pluck(straws);  // will remove one from the array

// clone this generator and weight it so now it'll be
// much more likely to generate lower numbers
var lowNumbersProbably = generator.clone().weightFront();
var number = lowNumbersProbably.randomInt(0, 6); 

// why not join the two approaches:
var lootRemaining = ['trash', 'common', 'uncommon', 'rare', 'epic'];
var drop = lowNumbersProbably.pluck(lootRemaining);

Generator

A random number generator. This is the main class exported by the package. By default, it uses an implementation of the Mersenne twister algorithm (from the mersenne-twister npm package).

If a number is passed to the constructor, it'll be used to seed the generator. If a string is provided, it'll be hashed (using the string-hash package) and then used as a seed. If nothing is provided, a random seed will be used.

If an object is provided, the generator will use the random property of that object as a random number source instead of using its own.

Kind: global class

• Generator
  • new Generator([seed])
  • .random() ⇒ number
  • .randomInt(min, max) ⇒ int
  • .choose(array) ⇒ *
  • .pluck(array, [limit]) ⇒ *
  • .pluckCycle(array, [limit]) ⇒ *
  • .shuffle(array) ⇒ array
  • .shuffleInPlace(array) ⇒ array
  • .clone() ⇒ Generator
  • .weightCustom(curve) ⇒ Generator
  • .weightFront() ⇒ Generator
  • .weightBack() ⇒ Generator

new Generator([seed])

| Param | Type | Description | | --- | --- | --- | | [seed] | string | number | object | The seed or source for this generator. |

Example

// use Math.random instead of Mersenne twister
var rng = new Generator({ random: () => Math.random() });

generator.random() ⇒ number

Generate a random number in the range [0, 1).

Kind: instance method of Generator

generator.randomInt(min, max) ⇒ int

Generate a random integer in the range [min, max). (that is, including min, not including max), If the max argument is omitted, the min argument will be used instead and will return [0, min).

Kind: instance method of Generator
Returns: int - random integer

| Param | Type | Description | | --- | --- | --- | | min | int | Lowest value (or highest if it's the only argument) | | max | int | Maximum value (not inclusive) |

generator.choose(array) ⇒ *

Return a random element of the given array.

Kind: instance method of Generator
Returns: * - a random element

| Param | Type | Description | | --- | --- | --- | | array | array | the source array. |

generator.pluck(array, [limit]) ⇒ *

Return a random element of the given array, removing it from the array.

Kind: instance method of Generator
Returns: * - a random element

| Param | Type | Default | Description | | --- | --- | --- | --- | | array | array | | the source array (will be modified) | | [limit] | int | 0 | the number of elements from the end of the array to ignore. This is mainly to be used internally by pluckCycle. Defaults to none. |

generator.pluckCycle(array, [limit]) ⇒ *

Return a random element of the given array, placing it at the end of the array. Note that limit defaults to 1 in this function, NOT zero, unlike pluck! The reason for this is that this function is designed to be called multiple times in a row to generate a sequence that is semi-random, but with the additional property that any individual item will be guaranteed to be separated by at least limit other items.

This is especially neat if the generator has been weighted to generate lower numbers. Repeated calls to this function with the same array will result in a very half-hearted shuffle, with items roughly in their original order but with some perturbation.

This is great for situations like footstep sound effects, which occur very regularly and sound awful if the same sound is played consecutive and also if there's a recognisable repeating sequence.

Kind: instance method of Generator
Returns: * - a random element

| Param | Type | Default | Description | | --- | --- | --- | --- | | array | array | | the source array (will be modified) | | [limit] | int | 1 | the number of elements from the end of the array to ignore. |

generator.shuffle(array) ⇒ array

Create a copy of the given array and shuffle it.

Kind: instance method of Generator
Returns: array - a shuffled copy of the array

| Param | Type | Description | | --- | --- | --- | | array | array | the source array. Will not be modified. |

generator.shuffleInPlace(array) ⇒ array

Randomly rearrange the elements of a given array.

Kind: instance method of Generator
Returns: array - the given array

| Param | Type | Description | | --- | --- | --- | | array | array | the array to shuffle |

generator.clone() ⇒ Generator

Create a new generator with the same random source. That is, any action that advances this generator's source will also advance the newly-created generator's source and vice-versa.

This is useful if you want to use some weighted generation and some non-weighted from the same seed, and don't want to have to keep setting and un-setting the source.

Kind: instance method of Generator

generator.weightCustom(curve) ⇒ Generator

Change the weighting curve of this generator to a custom function.

curve should take one parameter, a number in [0, 1), and return a number of the same format.

For example, the default curve is (n) => n, while the front-weighted curve is (n) => n * n.

You can also use a curve function that returns numbers outside those bounds; that can give some interesting behaviour to the number generators but the array functions (choose, pluck etc) will certainly stop working correctly.

Kind: instance method of Generator
Returns: Generator - this

| Param | Type | Description | | --- | --- | --- | | curve | function | the function to apply to numbers generated by this new generator. |

generator.weightFront() ⇒ Generator

Alter the curve of this generator so that results are weighted toward the low end of the [0, 1) range. (the new results will average around 1/3). This is achieved by squaring the results.

Kind: instance method of Generator
Returns: Generator - this

generator.weightBack() ⇒ Generator

Alter the curve of this generator so that results are weighted toward the high end of the [0, 1) range. (the new results will average around 2/3). This is achieved by taking the square root of each result.

Kind: instance method of Generator
Returns: Generator - this