Philosophically-grounded RNG — principled constraints on randomness.
platonic-randomness is a deterministic PRNG library that draws its structural principles from the five Platonic solids. Each solid's vertex geometry shapes how internal state is rotated between PRNG calls, producing sequences with distinct orbit structures while maintaining excellent statistical quality.
The library includes three backend PRNG algorithms (Mulberry32, SplitMix32, XorShift32), utilities for common distributions (uniform, Gaussian, exponential), value noise, weighted selection, shuffling, dice rolling, and independent stream generation.
The Platonic solids — tetrahedron, octahedron, cube, icosahedron, dodecahedron — represent the five ways to tile the sphere with identical regular polygons. Each encodes a different symmetry group:
| Solid | Vertices | Symmetry | Character |
|---|---|---|---|
| Tetrahedron | 4 | Fastest orbit, sharp periodicity | Minimal, fiery |
| Octahedron | 6 | Tight 6-fold cycling | Airy, balanced |
| Cube | 8 | Classic 8-fold rotation | Earthy, stable |
| Icosahedron | 12 | Rich mid-range | Watery, flowing |
| Dodecahedron | 20 | Deepest orbit structure | Quintessence, golden ratio |
Choosing a solid is choosing the rhythm at which vertex coordinates remix the PRNG state. All backends pass standard uniformity tests regardless of solid choice; the solid affects the texture of the sequence, not its correctness.
npm install @superinstance/platonic-randomnessimport { rng, rngStream, gaussian, diceRoll } from '@superinstance/platonic-randomness';
// Basic usage
const r = rng('my-seed', 'dodecahedron');
console.log(r.next()); // float in [0, 1)
console.log(r.int(1, 100)); // integer in [1, 100]
console.log(r.bool(0.3)); // true ~30% of the time
// Gaussian samples
const samples = gaussian(1000, 'noise', 50, 10); // mean=50, σ=10
// Weighted selection
const r2 = rng('pick');
const idx = r2.weighted([10, 30, 60]); // picks index 2 most often
// Independent streams from one seed
const [stream1, stream2] = rngStream('world', 2);
// Dice
const attack = diceRoll(3, 6, 'combat'); // 3d6| Function | Description |
|---|---|
mulberry32(seed) |
Fast 32-bit PRNG, excellent quality |
splitMix32(seed) |
High-quality, good for seeding |
xorshift32(seed) |
Compact xorshift variant |
xmur3(str) |
String → 32-bit seed hash |
The main class. Combines a backend PRNG with Platonic solid vertex rotation.
const r = new PlatonicRNG(
'seed-string', // string or number
'icosahedron', // solid: tetrahedron | cube | octahedron | dodecahedron | icosahedron
'mulberry32', // backend: mulberry32 | splitMix32 | xorshift32
);
r.next(); // float [0, 1)
r.range(min, max); // float [min, max)
r.int(min, max); // integer [min, max]
r.bool(p); // boolean, true with probability p
r.pick(array); // random element
r.shuffle(array); // Fisher-Yates shuffle (in-place)
r.array(n); // n floats
r.gaussian(μ, σ); // Box-Muller normal sample
r.weighted(weights); // weighted random index| Function | Description |
|---|---|
rng(seed, solid?, backend?) |
Create a PlatonicRNG |
rngStream(masterSeed, count, solid?) |
Multiple independent RNGs from one seed |
| Function | Description |
|---|---|
uniform(n, seed) |
n samples from Uniform[0, 1) |
gaussian(n, seed, mean?, stddev?) |
n samples from Normal(μ, σ) |
exponential(n, seed, rate?) |
n samples from Exp(λ) |
diceRoll(nDice, sides, seed) |
Sum of nDice d-sided dice |
| Function | Description |
|---|---|
valueNoise1D(x, rng, scale?) |
1D smoothstep value noise |
valueNoise2D(x, y, rng, scale?) |
2D smoothstep value noise |
MIT © SuperInstance