Random

A seeded, deterministic pseudo-random number generator. An identical seed always yields an identical sequence across every operation, on every platform — for reproducible runs, daily seeds, and save-profile reproducibility.

Backed by PCG32 (seeded via SplitMix64) with unbiased bounded integers and an exact float mapping, so the sequence is bit-identical on macOS, Windows, and Linux. The sequence produced by a given seed is a frozen contract: it is locked by engine golden-value tests and will not change between engine versions without a superseding ADR.

Unlike most of the engine API, Random methods are instance methods — construct one (or more) generators with explicit seeds and draw from them independently.

Random

Random.new(seed)

Returns: Random — A new generator initialized from the seed.

Parameters:

• seed (Num) — An explicit integer seed. The fractional part is discarded.

import "engine" for Random

var rng = Random.new(20260629)

Two generators built from the same seed produce the same sequence; different seeds diverge within a few draws.

rng.int(n)

Returns: Num — An integer in [0, n) (from 0 up to but not including n). Returns 0 when n <= 0.

Parameters:

• n (Num) — The exclusive upper bound (e.g. a list count).

var bag = ["A", "B", "C", "D", "E"]
var pick = bag[rng.int(bag.count)]  // a reproducible pick

Values are unbiased (rejection sampling) — every value in the range is equally likely.

Bounds are 32-bit: n (and the intRange span max - min + 1) must be at most 2^32 - 1; larger values are clamped to 2^32 - 1.

rng.intRange(min, max)

Returns: Num — An integer in [min, max], inclusive on both ends. Returns min when max <= min.

Parameters:

• min (Num) — Inclusive lower bound.
• max (Num) — Inclusive upper bound.

var roll = rng.intRange(1, 6)  // a die: 1, 2, 3, 4, 5, or 6

rng.float()

Returns: Num — A float in [0.0, 1.0) (never exactly 1.0), with 24 bits of precision. Exact and portable across platforms.

if (rng.float() < 0.25) {
  // 25% chance, reproducible for this seed
}

rng.shuffle(list)

Returns: List — The same list, shuffled in place (Fisher–Yates).

Parameters:

• list (List) — The list to shuffle.

var deck = []
for (i in 0...52) deck.add(i)
rng.shuffle(deck)  // deck is now permuted; same seed -> same order

Determinism example

import "engine" for Random, Logger

var a = Random.new(42)
var b = Random.new(42)
Logger.info("%(a.int(1000)) == %(b.int(1000))")  // always equal

---

See Engine for Engine.exit, used with the headless testing mode where deterministic seeds make test runs reproducible.