@web-engine-dev/math / SeededRNG
Class: SeededRNG
Deterministic seeded pseudo-random number generator.
Uses the mulberry32 algorithm, which provides good statistical properties with fast performance and a small state footprint (single 32-bit integer).
All gameplay systems (physics, AI, pathfinding, particles, netcode) that require randomness MUST use this class instead of Math.random() to ensure determinism for replays, rollback netcode, and synchronized multiplayer.
Example
import { SeededRNG } from '@web-engine-dev/math';
// Create with explicit seed for deterministic sequences
const rng = new SeededRNG(42);
// Generate random numbers
const value = rng.next(); // [0, 1)
const ranged = rng.range(10, 20); // [10, 20)
const integer = rng.int(0, 100); // [0, 100]
// Reset to replay the same sequence
rng.reset(42);Remarks
Thread safety: Each thread/worker should use its own SeededRNG instance. Period: 2^32 (approximately 4.3 billion values before repeating). Algorithm: Mulberry32 -- chosen for its balance of speed, quality, and simplicity. Passes BigCrush and PractRand statistical tests.
Constructors
Constructor
new SeededRNG(
seed):SeededRNG
Creates a new seeded random number generator.
Parameters
seed
number
Initial seed value. Different seeds produce completely different sequences. Must be a non-zero integer for best quality; zero is silently remapped to 1.
Returns
SeededRNG
Accessors
state
Get Signature
get state():
number
Returns the current internal state. Useful for serialization (save/load) to resume the exact same sequence later.
Returns
number
Set Signature
set state(
value):void
Restores the internal state from a previously saved value.
Parameters
value
number
Returns
void
Methods
chance()
chance(
probability):boolean
Returns true with the given probability.
Parameters
probability
number
Probability of returning true (0 to 1)
Returns
boolean
int()
int(
min,max):number
Returns a random integer in the range [min, max].
Parameters
min
number
Minimum value (inclusive)
max
number
Maximum value (inclusive)
Returns
number
next()
next():
number
Returns the next pseudo-random number in the range [0, 1).
Returns
number
Remarks
This is the core generation method. All other methods delegate to this. Uses the mulberry32 algorithm with a 32-bit state.
pick()
pick<
T>(array):T|undefined
Picks a random element from an array.
Type Parameters
T
T
Parameters
array
readonly T[]
Non-empty array to pick from
Returns
T | undefined
A random element, or undefined if the array is empty
range()
range(
min,max):number
Returns a random float in the range [min, max).
Parameters
min
number
Minimum value (inclusive)
max
number
Maximum value (exclusive)
Returns
number
reset()
reset(
seed):void
Resets the RNG to a new seed. The sequence will be identical to a fresh new SeededRNG(seed).
Parameters
seed
number
New seed value
Returns
void
shuffle()
shuffle<
T>(array):T[]
Fisher-Yates shuffle of an array (in-place, deterministic).
Type Parameters
T
T
Parameters
array
T[]
Array to shuffle
Returns
T[]
The same array, shuffled in-place
sign()
sign():
number
Returns a random sign (-1 or 1).
Returns
number