Random API

High-quality random number generation based on xoshiro256** — seedable, fast, with multiple distributions.

Overview

The Random API uses the xoshiro256** algorithm (period 2²⁵⁶−1, passes BigCrush). Each instance maintains independent state, allowing reproducible sequences via seeding. Create separate instances for different systems to avoid unwanted correlations.

Factory Function

Creates a random number generator. Without a seed, uses a time-based seed. With a seed, produces a reproducible sequence.

• seed (number, optional) — seed value (use 0 for time-based)

var rng = Random()         // Time-based seed
var rng = Random(12345)    // Reproducible sequence

Basic Generation

Generates a random float in [0, 1).

Generates a random integer in [min, max] (inclusive). Uses rejection sampling to avoid modulo bias.

• min (number) — minimum value (inclusive)
• max (number) — maximum value (inclusive)

Generates a random float in [min, max).

• min (number) — minimum value (inclusive)
• max (number) — maximum value (exclusive)

Returns true with the given probability (0–1).

• probability (number) — probability in [0, 1]

var rng = Random()
var x = rng.random()           // e.g. 0.847263
var dice = rng.randint(1, 6)   // Fair dice roll
var temp = rng.uniform(-10.0, 35.0)

if (rng.chance(0.3)) {
    print("30% chance event occurred!")
}

Collection Operations

Picks a random element from a list.

• list (list) — non-empty list to choose from

Shuffles a list in-place using the Fisher-Yates algorithm.

• list (list) — list to shuffle (modified in place)

Selects k random elements from a list without replacement.

• list (list) — list to sample from
• k (number) — number of elements to sample

Returns: New list containing k randomly selected elements.

var rng = Random()
var fruits = ["apple", "banana", "cherry", "date"]
var picked = rng.choice(fruits)

var deck = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
rng.shuffle(deck)
var hand = rng.sample(deck, 5)

Distributions

Generates a random number from a Gaussian (normal) distribution using the Box-Muller transform.

• mean (number) — center of the distribution
• stddev (number) — standard deviation (must be positive)

var rng = Random()
var height = rng.gaussian(170.0, 10.0)  // Human heights
var noisy = 50.0 + rng.gaussian(0.0, 2.0)  // Add noise

Byte Generation

Generates a list of random bytes (0–255).

• count (number) — number of bytes (0 to 1,000,000)

Fills a Buffer with random bytes from the current position up to capacity. Much more efficient than bytes() for large amounts.

• buffer (Buffer) — buffer to fill

Returns: Number of bytes written (0 if buffer is already full).

var rng = Random()
var data = rng.bytes(16)
// e.g. [142, 67, 201, 34, 89, 156, 23, 91, ...]

var buf = Buffer(1024)
var written = rng.bytesBuffer(buf)
print("Wrote " + str(written) + " random bytes")

Seeding

Reseeds the random number generator. Use 0 for time-based seed.

• value (number) — new seed value

var rng = Random()
rng.seed(12345)
var a = rng.random()
var b = rng.random()

rng.seed(12345)  // Reset
var c = rng.random()  // c == a
var d = rng.random()  // d == b

Examples

Complete Example

var rng = Random(42)

print("Float [0,1): " + str(rng.random()))
print("Int [1,100]: " + str(rng.randint(1, 100)))
print("Uniform [0,10): " + str(rng.uniform(0.0, 10.0)))

if (rng.chance(0.25)) {
    print("Rare event (25% chance)!")
}

var cards = ["Ace", "King", "Queen", "Jack"]
print("Drew: " + rng.choice(cards))

var numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
rng.shuffle(numbers)
print("Shuffled: " + str(numbers))

var scores = []
var i = 0
while (i < 5) {
    push(scores, rng.gaussian(75.0, 10.0))
    i = i + 1
}
print("Test scores: " + str(scores))

Algorithm Details

• Algorithm: xoshiro256** — state-of-the-art PRNG
• Period: 2²⁵⁶−1
• State: 256 bits (4 × 64-bit integers)
• Quality: Passes BigCrush
• Seeding: Seeds processed through SplitMix64
• randint: Rejection sampling (no modulo bias)
• gaussian: Box-Muller transform
• shuffle/sample: Fisher-Yates algorithm