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.

Run 1 3, 6, 1, 1, 4, 2
pick()
  • potion
  • map
  • key
  • scroll
  • gem
shuffle() mage โ†’ scout โ†’ tank โ†’ healer

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.

typescript
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.

typescript
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.

typescript
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.

typescript
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.

typescript
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.

typescript
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.