Skip to content

RNG streams

Every random draw in osrlib comes from a named stream, and every stream is forked from the session's master seed. Given the same master seed and the same stream key, a stream produces the same sequence of draws, and it produces that sequence no matter what any other stream does. Drawing a hundred rolls from the treasure stream never changes what the combat stream yields next. That per-key independence is what makes deterministic replays and saved games reliable. Two sessions built from the same seed replay identically, and adding new draws to one subsystem never shifts another subsystem's rolls.

Each stream is identified by a plain string key, like "combat" or "treasure". StreamName defines those keys, and every constant in the table below is one of its members, so a key has one spelling in the library. Draw with a member rather than a string you type out: RngStreams.get forks a new stream for any string, so if you mistype a key, you get plausible numbers from a new stream instead of an error.

Code that uses the kernel functions directly (standalone, outside of a running game) passes an explicit stream into each function call. A GameSession does this for you: it builds an RngStreams container from the session's master seed and passes the correctly named stream to each kernel function that needs one, so you don't need to touch a stream during ordinary play.

The table below lists every key, the constant for it, and what it governs.

Stream key Constant Governs
"character_creation" CHARACTER_CREATION_STREAM Character creation: ability scores, first-level hit points, starting gold.
"advancement" ADVANCEMENT_STREAM In-play advancement: level-up hit point rolls, and the hit points lost to energy drain.
"combat" COMBAT_STREAM Battle resolution: attack rolls, damage rolls, saving throws, morale checks, initiative, reaction rolls.
"effects" EFFECTS_STREAM Draws inside the effects engine: onset and duration dice, revival delays.
"monster_spawn" MONSTER_SPAWN_STREAM Monster spawning: hit point rolls when a monster instance is created.
"npc_party" NPC_PARTY_STREAM NPC adventuring-party generation: composition, class and level, ability scores, hit points, spell picks.
"magic" MAGIC_STREAM Spell resolution: targeting, damage, cast-time forced saves, dispel survival rolls, turning undead.
"treasure" TREASURE_STREAM Treasure generation: presence rolls, quantity dice, per-item resolution, magic item rolls.
"wandering" WANDERING_STREAM Wandering monsters: the wandering check, group counts, variant picks.
"encounter" ENCOUNTER_STREAM Encounter setup: surprise, distance, reaction rolls, distraction, and group counts for monsters or NPC parties spawned by command.
"exploration" EXPLORATION_STREAM Exploration: forcing doors, listening, searching, traps, tinder, and thief skill checks.
"monster_action" MONSTER_ACTION_STREAM Monster action policy during battle: which action a monster group takes each round, which target it picks, and which attack routine a monster uses when it has a free choice.
"adjudication" ADJUDICATION_STREAM The referee's ad-hoc adjudication rolls: freeform dice commanded through the seeded session.

Character streams

Character creation and in-play advancement are split into two separate streams so that changing one never disturbs the other's draws.

The CHARACTER_CREATION_STREAM (key "character_creation") covers one-time creation draws: rolling ability scores, first-level hit points, and starting gold.

The ADVANCEMENT_STREAM (key "advancement") covers hit point rolls when a character levels up during play, and the hit point rolls for the levels or Hit Dice that energy drain takes away.

Combat and effects streams

The COMBAT_STREAM (key "combat") covers the battle-resolution kernel: attack rolls, damage rolls, saving throws, morale checks, initiative, and reaction rolls made in combat.

The EFFECTS_STREAM (key "effects") is separate from combat and covers draws internal to the effects engine: rolled onset and duration dice for conditions like poison or paralysis, and revival delays. Because effects have a separate stream, a change to how battle resolves never shifts which round an effect ticks or expires.

Monster and NPC streams

The MONSTER_SPAWN_STREAM (key "monster_spawn") covers hit point rolls at the moment a monster instance is spawned from its template.

The NPC_PARTY_STREAM (key "npc_party") covers generating an NPC adventuring party through the same character-creation kernel player characters use: party composition, each member's class and level, ability scores, hit points, and spell picks. An NPC party's treasure and any Expert-class magic items are generated on the treasure stream instead, since they are treasure procedures.

Magic stream

The MAGIC_STREAM (key "magic") covers every draw made while resolving a spell: targeting, damage dice, touch-attack rolls, cast-time forced saving throws, dispel-survival rolls, and both rolls involved in turning undead. Durations rolled when an effect attaches, and saves rolled later when that effect ticks (like a charm spell's periodic re-save), draw from the effects stream instead, following the same convention as the rest of the effects engine.

Treasure stream

The TREASURE_STREAM (key "treasure") covers treasure generation end to end, in the order a treasure entry is printed: whether a treasure type is present at all, how much of it there is, and the resolution of each individual coin hoard, gem, piece of jewellery, or magic item. The session also uses this stream to roll the details of a magic item granted with GrantItem, like a wand's charges.

Crawl-session streams

The dungeon-crawl loop has separate streams, defined in osrlib.crawl.session beside GameSession rather than in a kernel module, since they only make sense in the context of a running session.

The WANDERING_STREAM (key "wandering") covers the wandering-monster check itself, how many monsters appear, and which variant appears when a wandering table entry has more than one.

The ENCOUNTER_STREAM (key "encounter") covers everything that happens once an encounter starts: surprise rolls, the distance at which the two sides meet, reaction rolls, and mid-encounter distraction checks. It also covers the group-size roll when a command spawns a monster group or NPC party with dice rather than a fixed count.

The EXPLORATION_STREAM (key "exploration") covers the rest of dungeon exploration: forcing doors, listening at doors, searching for secret doors or traps, disarming or triggering traps, lighting tinder, and thief skill checks like picking locks.

The MONSTER_ACTION_STREAM (key "monster_action") covers the action policy that drives monster groups during battle: which action a group takes on its turn, which target it selects, and which attack routine a monster uses when its stat block offers a free choice. A monster with only one routine to choose from makes no draw for it. Because the policy has a separate stream, swapping in a different monster action policy never shifts the combat stream's attack and damage rolls.

The ADJUDICATION_STREAM (key "adjudication") covers the referee's ad-hoc rolls for freeform adjudication: dice commanded through the seeded session to resolve a chance outcome the content model can't express, like whether a frayed rope holds. Because these rolls have a separate stream, an ad-hoc referee roll never changes the draws of any other stream. The outcomes of encounters, combat, and exploration stay the same under replay, however many adjudication rolls the referee makes in between them.

Stream independence in practice

The following example creates two independent RngStreams containers from the same master seed and shows that the "combat" stream produces the same sequence in both, even after one of the containers draws from an unrelated "treasure" stream:

from osrlib.core.rng import RngStreams

streams_a = RngStreams(master_seed=42)
streams_b = RngStreams(master_seed=42)

combat_a = streams_a.get("combat")
combat_b = streams_b.get("combat")

# Same master seed and same stream key always yield the same draw sequence.
assert combat_a.next_uint64() == combat_b.next_uint64()

# Drawing from an unrelated stream doesn't perturb the combat stream's sequence.
streams_a.get("treasure").next_uint64()
assert combat_a.next_uint64() == combat_b.next_uint64()