Random

Seeded, deterministic pseudo-random numbers for demos and games. The Random class uses a mulberry32 core so the same seed always produces the same sequence across platforms. Stateless hash1i / hash2i / hash3i (and float forms) give per-coordinate randomness for chunked worlds without storing an RNG per cell. ValueNoise, PerlinNoise, and SimplexNoise add smooth pattern-based fields for terrain, clouds, and organic motion.

import { Random } from 'blit386';

const rng = new Random(1234);

rng.next(); // [0, 1)
rng.float(0, 10); // [0, 10)
rng.int(6); // [0, 6)
rng.int(10, 20); // [10, 20)
rng.intInclusive(1, 6); // [1, 6]
rng.bool(0.25); // true ~25% of the time
rng.sign(); // -1 or 1
rng.pick(['a', 'b', 'c']);
rng.shuffle([1, 2, 3, 4]);
rng.angle(); // [0, 2π) radians
rng.gaussian(0, 1); // Box-Muller sample
rng.direction4(); // cardinal unit vector

Omit the constructor seed to time-seed from Date.now() (lower 32 bits). Call seed(n) later to restart from a known value.

Engine default (BT.random)

The engine keeps one shared Random instance on the BT facade. BT.random is a live reference (same instance across reads, like BT.palette). It is time-seeded when the engine singleton is created; call BT.randomSeed(seed) to make a run reproducible.

import { BT } from 'blit386';

BT.randomSeed(42);
BT.random.int(150, 420);
BT.random.pick(['glitch', 'noise', 'static']);
BT.random.float(0.3, 0.95);

Prefer BT.random for demo and game code. Construct a separate new Random(seed) when you need an independent stream (for example a local procedural subsystem that should not advance the shared engine RNG).

Generators

Integer helpers return true integers (| 0 truncation), matching the engine's Vector2i philosophy. Half-open int ranges match the demo helpers (randInt / randFloat).

Spatial helpers

insideRect / insideRectTo sample the same half-open region as Rect2i.isContaining: x in [rect.x, rect.right), y in [rect.y, rect.bottom). pointInRange / pointInRangeTo use int per axis ([min.x, max.x) and [min.y, max.y)). Empty or inverted ranges throw the same RangeError as int. Prefer the *To(out) variants in update() / render() loops to avoid per-frame allocation.

import { Random, Rect2i, Vector2i } from 'blit386';

const rng = new Random(7);
const rect = new Rect2i(0, 0, 320, 240);
const out = new Vector2i();

rng.insideRect(rect);
rng.insideRectTo(rect, out);
rng.pointInRange(new Vector2i(10, 10), new Vector2i(20, 30));
rng.direction4(); // (1,0) | (-1,0) | (0,1) | (0,-1)
rng.direction8(); // cardinals plus diagonals

Coordinate hashing

Stateless spatial lookups for chunked and procedural worlds. Same coordinates and seed always return the same value - no stored RNG state, so you do not need an instance per chunk. Complements Random (a sequence generator).

Coordinates are truncated toward zero with | 0. Omit seed (or pass 0) for a fixed default world seed. Float forms are the matching hashNi value scaled by 1 / 2^32.

import { hash2, hash2i } from 'blit386';

const tile = hash2i(12, -3, 9001); // uint32, same every call
const chance = hash2(12, -3, 9001); // [0, 1)
const shouldSpawn = chance < 0.15;

Pattern noise

Smooth, seedable spatial noise for terrain, clouds, organic motion, and procedural textures. Lattice corners use the coordinate hashes above. Every sample is in approximately [-1, 1] (the same signed range as trig helpers). These classes are distinct from the post-process Noise display effect (GPU grain).

Omit the constructor seed (or pass 0) for a fixed default world seed - same convention as hash2i. Call seed(n) to switch fields. fBm defaults: octaves = 4, persistence = 0.5, lacunarity = 2. Octave amplitudes are normalized so fBm stays in approximately [-1, 1].

import { PerlinNoise, SimplexNoise, ValueNoise } from 'blit386';

const value = new ValueNoise(9001);
const perlin = new PerlinNoise(9001);
const simplex = new SimplexNoise(9001);

value.noise2D(12.5, -3.25); // [-1, 1]
perlin.fbm2D(0.1, 0.2); // multi-octave, still ~[-1, 1]
simplex.noise3D(1, 2, 3);

Value noise interpolates hashed corner values (smooth but can look blocky at low frequency). Perlin uses lattice gradients (Ken Perlin, SIGGRAPH 2002). Simplex reduces directional artifacts on square grids (Stefan Gustavson).

State and streams

import { Random } from 'blit386';

const rng = new Random(99);
rng.next();
rng.next();

const saved = rng.getState();
const clone = rng.clone(); // same stream from this point
const child = rng.fork(); // independent sub-stream; advances `rng` once

rng.setState(saved); // restore and replay

seedValue reads back the seed itself, not the current position in the sequence - the value getState() returns keeps changing as you draw, but seedValue stays put until the generator is genuinely reseeded. It is normalized to an unsigned 32-bit value, the same representation getState() uses, not necessarily the raw number passed in. setState() clears it, since jumping to an arbitrary saved state does not correspond to any known seed. clone() copies it verbatim (including undefined), matching the identical stream a clone produces. fork()'s child always reports undefined - a fork is a new stream and should not claim a seed its caller never chose.

API history

See also

Last updated on September 9, 2026