Pseudo Random Numbers
Randomness you can replay. Everything procedural here (a galaxy, a planet's craters, where the rocks go, who spawns) is drawn from a generator started from a number, the SEED. Same seed, same numbers, in every browser, so the same seed is the same world: you can share it, test it, and come back to it.
Nothing here uses Math.random(). It cannot be seeded, so it can never give
you the same world twice, and it is not very random: the standard does not
say which algorithm it is, so its quality is whatever the browser shipped.
That has been bad. V8's before 2015 (MWC1616) had cycles short enough, and
patterns plain enough, to see in a picture of its output; engines are better
now, but "better now, in some browsers" is not something to build on.
We implement two generators, each for a job:
PRNG(on xoshiro128**) for the general case: a stream of good numbers with convenience methods (ranges, a bell curve, weighted picks).CheapPRNG(on mulberry32) for derived data: one tiny generator per object, built, drawn from a few times, and dropped, millions of times over (a star's name and its details).
Demo
import { PRNG } from 'tosijs-3d'
import { elements } from 'tosijs'
const { div, p, button, pre } = elements
let output = ''
const prng = new PRNG(42)
output += 'Seed: 42\n\n'
output += 'value(): ' + prng.value().toFixed(6) + '\n'
output += 'range(1, 100): ' + prng.range(1, 100) + '\n'
output += 'realRange(0,1): ' + prng.realRange(0, 1).toFixed(6) + '\n'
output += 'gaussrandom(): ' + prng.gaussrandom().toFixed(6) + '\n'
output += 'probability(0.5): ' + prng.probability(0.5) + '\n'
output += 'pick([a,b,c]): ' + prng.pick(['a', 'b', 'c']) + '\n'
output += 'pick weighted: ' + prng.pick(['rare', 'common'], [1, 99]) + '\n\n'
output += 'Deterministic check (new PRNG(42)):\n'
const prng2 = new PRNG(42)
output += 'value(): ' + prng2.value().toFixed(6) + ' (same as above)\n'
preview.append(pre(output))
Why these two
What we need from a generator, in order: the same sequence everywhere
(pure 32-bit integer arithmetic, Math.imul and shifts, so no engine's
floating point can change it), seeded by one number, then cheap to
start, and good enough statistically for games. Cryptographic strength is
not on the list: nothing here is a secret.
Measured in Bun, building one and drawing 8 numbers:
| Generator | State | Build + 8 draws | One draw |
|---|---|---|---|
| Mersenne Twister (MT19937) | 624 words | 13 µs | 0.02 µs |
xoshiro128** (PRNG) |
4 words | 0.09 µs | 0.01 µs |
mulberry32 (CheapPRNG) |
1 word | 0.03 µs | 0.008 µs |
xoshiro128** (Blackman and Vigna) is behind PRNG, not the Mersenne
Twister this page is named after: MT has a huge state that it fills before its
first draw, so merely starting one costs about 13 µs, and a star system starts one per planet while scoring candidate
systems starts thousands. xoshiro128** starts about 150× faster, has a period
of 2¹²⁸, and passes the BigCrush and PractRand test batteries, which MT does
not (it fails the linear-complexity tests). Its one integer seed is spread
over its four words by splitmix32, which also keeps it out of the all-zero
state it could never leave.
mulberry32 is smaller still: one 32-bit word, a few multiplies a draw. It is weaker (a period of 2³², and each seed is one short stream), and that does not matter for what it does: a handful of draws per star, each a pure function of the star's seed. It is about 3× cheaper than xoshiro to start, which counts at galaxy scale, and more to the point its output IS the galaxy: star names and spectral details are drawn from it, so changing its engine would rename every star. It stays.
The Mersenne Twister is still exported (MersenneTwister), for sequences
that must match older PRNG output, which was built on it. Nothing here uses it.
A few places hash rather than generate: noise lattices (noise-volume,
climate-noise) fill bytes with xorshift32, and latticeHash turns a grid
point into a number directly. A hash answers "what is the number AT this
place" with no sequence to step through, which is what a texture or an
infinite grid needs.
API
Xoshiro128, MersenneTwister
The bare engines, for when you want numbers and nothing else.
| Method | Returns | Description |
|---|---|---|
constructor(seed) |
Create with a numeric seed (required: pass Date.now() for a different sequence each run) |
|
random() |
number |
Random float in [0, 1) |
int32() |
number |
Random 32-bit unsigned integer |
PRNG
| Method | Returns | Description |
|---|---|---|
constructor(seed) |
Create with numeric seed | |
value() |
number |
Random float in [0, 1) |
range(min, max) |
number |
Random integer in [min, max] |
realRange(min, max, skew?) |
number |
Random float in [min, max) with optional skew function |
gaussrandom(dev?) |
number |
Gaussian random with given standard deviation (default 1) |
probability(p) |
boolean |
Returns true with probability p |
pick(array, weights?) |
T |
Weighted random selection from array |
CheapPRNG
The same surface as PRNG less gaussrandom (value, range,
realRange, probability, pick), on mulberry32. RandomLike is the part
both share, for a function that takes either.