Determinism, saves, and replay
In osrlib, a game is a pure function of its seed and its command sequence. Every random draw comes from a named RngStream forked from a session's master seed, so the same seed, the same sequence of commands, and the same engine version always produce the same game.
You get three things out of that guarantee. A bug report needs only a seed and a short command log to reproduce a failure exactly. Golden tests can assert on exact game state instead of approximate behavior. A saved game loads byte-for-byte, or replays from scratch. Either way it ends in the same state, apart from what listeners returned (see Replay runs with no listeners). Every snippet below comes from the complete program at the end, and running that program checks every claim made here.
The determinism contract
Randomness in osrlib never comes from the stdlib random module or a module-level default. Every roll takes an explicit stream, and every stream is one of the small named set forked from the session's master seed. See RNG streams for the full list and what each stream governs.
Two sessions built from the same seed and driven through the same accepted commands consume every stream in the same order and get the same draws. Their saves are byte-for-byte identical, not just equivalent in effect:
# Same seed, same commands: two independently built sessions save identically.
session_a = play(seed=7)
session_b = play(seed=7)
assert save_game(session_a) == save_game(session_b)
Saves
save_game serializes a running GameSession to a JSON-compatible dict: the party, the embedded adventure content, dungeon state, the clock, every exported RNG stream position, the master seed, the session-state blocks that listeners and authored content write (the flag store, each registered listener's state entry, the record of which triggers have fired, the journal, and quest state), the accepted-command log, and the event log. All of your authored progress survives a save and a load. For more about the session-state blocks, see Listeners and flags and Gates, triggers, and quests.
load_game reconstructs a session from that dict by restoring each piece exactly, RNG stream positions included, so a loaded game continues drawing from precisely where the saved game left off:
# The whole session round-trips through JSON: save -> load -> save is the identity.
document = save_game(session_a)
restored = load_game(document)
assert save_game(restored) == document
The event log is the one piece a save doesn't need. It's a record for a front end to display, and load_game doesn't rebuild any state from it. To make a save smaller, pass include_event_log=False. load_game restores the same state whether the log is in the save or not.
Replay from a seed and a command log
replay_game takes the same seed, the starting party, the adventure, and the accepted-command log, and re-executes every command from scratch through a fresh session, with no saved state at all. It raises ReplayVersionError when the log's recorded engine version doesn't match the running engine. That check runs only when you pass the version a save recorded (through the recorded_engine_version argument). It raises ContentValidationError if a logged command is rejected on replay. That's a divergence, since the log contains only commands that were accepted the first time.
Both paths are deterministic, so restoring a session from its save and replaying the same seed against the same command log produce the same state, apart from what listeners return (see Replay runs with no listeners). osrlib's test suite asserts that equivalence. As a result, a bug report, an audit trail, or a spectator replay needs only the seed and the commands, not a full save file:
# load(save) and replay(seed, commands) are two different paths to the identical state:
# the party document must be the *pre-session* party, the same starting point the
# original session assigned ids from.
pre_session_party = party_to_document(new_party(seed=7).members)
replayed = replay_game(
seed=7,
party_document=pre_session_party,
adventure=build_adventure(),
ruleset=Ruleset(),
commands=session_a.command_log,
)
assert save_game(replayed, include_event_log=False) == save_game(session_a, include_event_log=False)
Pass replay_game the pre-session party document, the output party_to_document gives you before the party ever joined a session, because GameSession.new assigns member ids itself, in party order, the same way both times.
Replay runs with no listeners
replay_game builds its session with no listeners registered. Every command a listener issued during play, like the interpreter's trigger consequences or a game listener's awards, is in the command log, so re-executing the log rebuilds what those commands changed.
Two things a listener produces aren't commands: the state it returns, and the events it returns itself. A replay doesn't rebuild either one. The replayed session's listener_state is empty, and its event_log lacks those events. That's a limit of replay, not a defect, and the equivalence above holds for everything else. If your game needs that state, you have two choices:
- To continue a game, load its save with
load_game. A load restoreslistener_stateand the event log. - If a replay has to rebuild something a listener tracks, have the listener record it with a command, like
SetFlag. The command log then contains it, and the replay sets it again. For more information about flags, see Listeners and flags.
A load and a replay treat listeners differently. After load_game, re-register your listeners before you execute new commands, because a restored session has no listeners registered. replay_game gives you no such choice, because it builds the session itself and takes no listeners at all. The choice comes up only when you drive a replay by hand, building your own session and feeding it the log through execute, and then the answer depends on what the listener does. A listener that only observes, by accumulating listener_state and returning annotation events, can be registered and reproduces its state exactly. Don't register a listener that reacts by issuing commands, and in particular don't register the Interpreter. The log already contains every command that listener issued during play, so registering it would issue those commands a second time, and the replay would diverge from the recorded game.
Schema versions and migrations
The version helpers live in osrlib.versioning. Every serialized document (a save, a command, an event) goes into an envelope that contains a kind, a schema_version, and an engine_version. stamp_document produces the envelope and check_document reads it back. SCHEMA_VERSION is currently 4, one integer shared by every document kind, separate from the package's release version.
A schema version is additive-only: within one version, only new event types, new message codes on an existing event type, and new optional fields can appear. Anything else, like a rename, a removal, or a change in what a field means, bumps SCHEMA_VERSION, and a bump comes with a migration. load_game runs a copy of a document's payload through the ordered chain in MIGRATIONS before it rebuilds anything, so a document stamped at an older schema version still loads, and the document you pass stays as it was.
There are three migrations. The step from version 1 to version 2 drops a recovered_treasure field that a version-2 payload no longer includes, and adds the empty npcs list that version 2 introduced. A payload contains the NPC roster as a list, and load_game rebuilds it into the session's npcs dict keyed by id, which is what the assertion below reads back. The step from version 2 to version 3 is a lossless rewrite: version 3 rejects trigger="enter" on a treasure trap, a value the engine never read on a cache, so the migration rewrites it to "open", the only action that springs a cache's trap. The step from version 3 to version 4 is another lossless rewrite: version 4 drops "withdraw" from a battle declaration's move. The round resolver never moved the party for that value, so the migration removes it from each logged declaration. A declaration whose action was move becomes action="hold" with no move, which is what that round played as. On a declaration with any other action, the engine never read move, so the migration clears it and leaves the action as it is. A document saved at the oldest version, schema version 1, runs the whole chain and loads the same way a fresh one does:
# A version-1 document -- no "npcs" key, and the ledger field version 2 dropped --
# still loads: the migration adds npcs=[] and discards the stale field.
legacy_payload = dict(document["payload"])
legacy_payload.pop("npcs")
legacy_payload["recovered_treasure"] = {"gp": 100}
legacy_document = {
"kind": "save",
"schema_version": 1,
"engine_version": document["engine_version"],
"payload": legacy_payload,
}
migrated = load_game(legacy_document)
assert migrated.npcs == {}
engine_version returns the installed package version, which every envelope records alongside the schema version. The two are separate on purpose. SCHEMA_VERSION governs whether a document still parses. The engine version governs whether a replay still produces the same draws: pass replay_game the recorded engine version and it refuses a log recorded under a different one.
The complete program
from osrlib.core.alignment import Alignment
from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character, party_to_document
from osrlib.core.rng import RngStreams
from osrlib.core.ruleset import Ruleset
from osrlib.crawl.adventure import Adventure, TownSpec
from osrlib.crawl.commands import EnterDungeon, MoveParty
from osrlib.crawl.dungeon import Direction, DungeonSpec, Edge, EdgeKind, LevelSpec
from osrlib.crawl.party import Party
from osrlib.crawl.session import GameSession
from osrlib.persistence import load_game, replay_game, save_game
from osrlib.versioning import SCHEMA_VERSION, engine_version
def build_adventure() -> Adventure:
# The smallest adventure: a town and a one-corridor dungeon, two cells joined west-east.
passage = LevelSpec(number=1, width=2, height=1, entrance=(0, 0), edges={"1,0:west": Edge(kind=EdgeKind.OPEN)})
crypt = DungeonSpec(id="crypt", name="The Old Crypt", levels=(passage,))
town = TownSpec(name="Threshold", travel_turns={"crypt": 1})
return Adventure(name="A First Delve", town=town, dungeons=(crypt,))
def new_party(seed: int) -> Party:
# Rolling from the same seed always rolls the same character: no session involved yet.
rules = Ruleset()
creation = RngStreams(master_seed=seed).get(CHARACTER_CREATION_STREAM)
fighter = create_character(
name="Hild", class_id="fighter", alignment=Alignment.LAWFUL, ruleset=rules, stream=creation
)
return Party(members=[fighter.character])
def play(seed: int) -> GameSession:
session = GameSession.new(new_party(seed), build_adventure(), seed=seed)
session.execute(EnterDungeon(dungeon_id="crypt"))
session.execute(MoveParty(direction=Direction.EAST))
return session
# Same seed, same commands: two independently built sessions save identically.
session_a = play(seed=7)
session_b = play(seed=7)
assert save_game(session_a) == save_game(session_b)
# The whole session round-trips through JSON: save -> load -> save is the identity.
document = save_game(session_a)
restored = load_game(document)
assert save_game(restored) == document
assert document["schema_version"] == SCHEMA_VERSION
assert document["engine_version"] == engine_version()
# load(save) and replay(seed, commands) are two different paths to the identical state:
# the party document must be the *pre-session* party, the same starting point the
# original session assigned ids from.
pre_session_party = party_to_document(new_party(seed=7).members)
replayed = replay_game(
seed=7,
party_document=pre_session_party,
adventure=build_adventure(),
ruleset=Ruleset(),
commands=session_a.command_log,
)
assert save_game(replayed, include_event_log=False) == save_game(session_a, include_event_log=False)
# A version-1 document -- no "npcs" key, and the ledger field version 2 dropped --
# still loads: the migration adds npcs=[] and discards the stale field.
legacy_payload = dict(document["payload"])
legacy_payload.pop("npcs")
legacy_payload["recovered_treasure"] = {"gp": 100}
legacy_document = {
"kind": "save",
"schema_version": 1,
"engine_version": document["engine_version"],
"payload": legacy_payload,
}
migrated = load_game(legacy_document)
assert migrated.npcs == {}
Where next
- Using the rules without a session - the streams and kernel functions this determinism contract is built from.
- RNG streams - every named stream and what it governs.
- Sessions, commands, and events - the command loop that produces the command log
replay_gamere-executes.