Overview
A deterministic and reversible random number generator.
Ideal for generative art, as well as games for varied entity behavior.
Features
- Is deterministic (provide the same seed to get same stream of random values)
- Is reversible (see next/prev section)
- Internal state only takes up 32bits
- Has a period length of 2^32
- Each value from [0, 2^32) is generated exactly once in the total period
- Has great test coverage
Demos
Installation
npm install arbitrary
Usage
Basics
import arbitrary from 'arbitrary';
let generate = new arbitrary.Generator();
console.log( generate.next.number(-10, 10) );
console.log( generate.next.percent() );
console.log( generate.next.bits(1) );
console.log( generate.next.bits(32) );
Deterministic
import arbitrary from 'arbitrary';
let deterministic = new arbitrary.Generator(42);
console.log( deterministic.next.percent() );
console.log( deterministic.next.bits(8) );
console.log( deterministic.next.number(0, 10000) );
Reversing
import arbitrary from 'arbitrary';
let generate = new arbitrary.Generator();
console.log( generate.next.number(0, 10000) );
console.log( generate.next.number(-10, 10) );
console.log( generate.next.percent() );
console.log( generate.next.bits(1) );
console.log( generate.next.bits(32) );
console.log( generate.prev.bits(1) );
console.log( generate.prev.percent() );
console.log( generate.prev.number(-10, 10) );
console.log( generate.prev.number(0, 10000) );
Scramble / Descramble
The scramble function is best used for turning sequences of ordered numbers (Ex. an increasing counter)
and scrambling the bits to get random number. It also reversible via arbitrary.descramble()
.
A few obvious utilizing scrambling:
- Jump back and forward in a stream of randomly generated numbers.
- To do this, keep an index into a sequence and scramble the index you want a random number. Just
jump or set the index to another point and scramble it again to recoup the random number generated
at that point in time.
- For comparison using
Generator .next/.prev
can be forwarded/reversed, but
it can only do so a single step at a time, making large jumps in a sequence
take proportionally more CPU per distance jumped.
- Use scramble to take a
Generate
state and jump to another point in the sequence it generates.
- This is useful for instance when creating generative art and wanting to fork a
new stream of random values.
Important: Use Generator .next/.prev if
you don't need this focus but just want a series of random numbers as scramble
/unscramble
are computationally
more expensive.
import arbitrary from 'arbitrary';
const scrambled42 = arbitrary.scramble(42);
console.log(scrambled42);
const unscrambled42 = arbitrary.descramble(scrambled42);
console.log(unscrambled42)
API Reference
Coming soon. See examples above.
Contributing
Setup
git clone git@github.com:francoislaberge/arbitrary.git
cd arbitrary
Watching
npm run watch
Building
npm run build
Publishing to NPM
Do the usual npm version bump then publish.
npm version <major|minor|patch>
git push; git push --tags
npm publish
Test
The tests must be built before they can be run. So use either the build or watch approach below before running the tests.
All tests are run automatically on push via our travis-ci integration
npm run test
Watch Tests
Automatically builds tests when any source code changes (test or regular).
npm run watch-test
Build Tests
npm run build-test