Random
Use one seeded source for rolls, choices, shuffles, procedural content, and replayable game runs.
Try the same seed twice
Every action below uses a deterministic stream. Change the seed, run it again, or repeat it to reproduce the same results.
pick() potionmapkeyscrollgem
shuffle() Start with a source
Use an explicit seed for tests, procedural generation, and replays. Omit it when each run should start from fresh browser entropy.
import { create_random } from "squander/core";
const random = create_random();
const replayable = create_random({ seed: "level-42" });Roll a value
next_float() returns a value from zero up to, but not including, one.
const chance = random.next_float();
if (chance < 0.1) spawn_rare_drop();Choose an integer range
The lower bound is inclusive and the upper bound is exclusive. This avoids hand-written range math at every call site.
const spawn_x = random.next_int(0, world_width);
const die_roll = random.next_int(1, 7); // 1 through 6
const target_index = random.next_int(0, targets.length);Pick or shuffle values
pick() rejects an empty collection. shuffle() returns a new array, so the source collection stays unchanged.
const item = random.pick(["potion", "map", "key", "scroll", "gem"]);
const turn_order = random.shuffle(["scout", "mage", "tank"]);Separate gameplay systems
Fork named streams so a new random call in one system does not silently change another system's sequence.
const loot_random = random.fork("loot");
const enemy_random = random.fork("enemies");
const loot_item = loot_random.pick(loot_table);
const enemy_count = enemy_random.next_int(3, 8);Save a replay point
Snapshots capture the complete stream state. Store one with the run, then recreate the source when you need to continue it.
const checkpoint = random.snapshot();
save_replay({ seed: "level-42", random: checkpoint });
const restored = create_random({ state: checkpoint });Keep security separate
This module is for gameplay and procedural content. It is not a secure token generator, an anti-cheat mechanism, or a cryptographic API.
Browser crypto supplies fresh entropy when create_random() has no seed; the gameplay stream remains deterministic after creation.