Skip to content

API reference

Old-School Essentials (B/X) rules engine for turn-based dungeon crawlers.

osrlib is the rules authority and game-state engine; the game supplies presentation, input, and content. The library is headless and sans-I/O: it never renders, prompts, sleeps, or touches the network, and all randomness flows through named deterministic streams (see osrlib.core.rng).

Every symbol has exactly one import home: the kernel under osrlib.core, the crawl framework under osrlib.crawl, and the shared services at the top level — osrlib.data (compiled SRD catalogs), osrlib.errors (the typed exception hierarchy), osrlib.messages (message-code formatting), osrlib.persistence (saves and replay), and osrlib.versioning (schema and engine version stamping). The package root re-exports nothing.

The quickstart below crosses the whole loop — characters, party, adventure, session, commands, events, save, and load. Full documentation, including a stepwise version of this example: https://mmacy.github.io/osrlib-python/

from osrlib.core.alignment import Alignment
from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character
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, SessionMode
from osrlib.crawl.dungeon import Direction, DungeonSpec, Edge, EdgeKind, LevelSpec
from osrlib.crawl.party import Party
from osrlib.crawl.session import GameSession
from osrlib.messages import format_message
from osrlib.persistence import load_game, save_game

# Roll two 1st-level characters; every random draw comes from a named, seeded stream.
rules = Ruleset()
creation = RngStreams(master_seed=7).get(CHARACTER_CREATION_STREAM)
fighter = create_character(name="Hild", class_id="fighter", alignment=Alignment.LAWFUL, ruleset=rules, stream=creation)
cleric = create_character(name="Osric", class_id="cleric", alignment=Alignment.LAWFUL, ruleset=rules, stream=creation)
party = Party(members=[fighter.character, cleric.character])

# The smallest adventure: a town and a one-corridor dungeon, two cells joined west-east.
crypt = DungeonSpec(
    id="crypt",
    name="The Old Crypt",
    levels=(LevelSpec(number=1, width=2, height=1, entrance=(0, 0), edges={"1,0:west": Edge(kind=EdgeKind.OPEN)}),),
)
town = TownSpec(name="Threshold", travel_turns={"crypt": 1})
adventure = Adventure(name="A First Delve", town=town, dungeons=(crypt,))

# A session starts in town; entering the dungeon switches it to exploring.
session = GameSession.new(party, adventure, seed=7)
session.execute(EnterDungeon(dungeon_id="crypt"))
assert session.mode is SessionMode.EXPLORING

# Commands in, events out: every rules resolution is a typed event with a message code.
result = session.execute(MoveParty(direction=Direction.EAST))
assert result.accepted
lines = [format_message(event) for event in result.events]
assert lines  # every event formats to a default English line

# The whole session round-trips through JSON: same seed, same commands, same game.
document = save_game(session)
restored = load_game(document)
assert save_game(restored) == document

One page per module, each rendering that module's public (importable) surface:

The core kernel

  • osrlib.core.abilities — Ability scores: modifier tables, checks, prime requisites, and the adjustment step (21 symbols)
  • osrlib.core.alignment — The three alignments, in a home importable by both characters and monsters (1 symbols)
  • osrlib.core.character — The player character: model, stepwise creation, and stamped serialization (17 symbols)
  • osrlib.core.classes — Class definitions, level progression, XP awards, and leveling up (25 symbols)
  • osrlib.core.clock — Time units and the game clock (7 symbols)
  • osrlib.core.combat — The combat kernel: initiative, attacks, damage, saving throws, morale, and targeting (48 symbols)
  • osrlib.core.dice — Dice expression parsing and rolling (5 symbols)
  • osrlib.core.effects — Named conditions and the effect lifecycle engine (18 symbols)
  • osrlib.core.events — The event base class, the emission contract, and the first kernel events (35 symbols)
  • osrlib.core.items — Equipment, inventories, magic items, identification, and curses (61 symbols)
  • osrlib.core.monsters — Monster templates, instances, spawning, and the entity ID allocator (24 symbols)
  • osrlib.core.npc — NPC adventuring parties: the SRD generation procedure from the character model (4 symbols)
  • osrlib.core.rng — Named deterministic RNG streams backed by pure-Python PCG64 (4 symbols)
  • osrlib.core.ruleset — The Ruleset model: optional-rule and adaptation flags (3 symbols)
  • osrlib.core.spells — Spell memorization, casting, spell resolution, and turning undead (30 symbols)
  • osrlib.core.tables — The rules tables as data: attack matrix, saves, XP, turning, reaction, encounters (28 symbols)
  • osrlib.core.treasure — Treasure tables and generation: types A–V, gems, jewellery, and magic item rolls (25 symbols)
  • osrlib.core.validation — Structured rejection reasons returned by pure validators (1 symbols)

The crawl framework

  • osrlib.crawl.adventure — The adventure container: dungeons, the base town, and scenario metadata (3 symbols)
  • osrlib.crawl.battle — The range-track battle state machine and the pluggable monster action policy (10 symbols)
  • osrlib.crawl.commands — The command set: typed models, the discriminated union, and the result envelope (52 symbols)
  • osrlib.crawl.dungeon — The multi-level dungeon grid: cells, edges, doors, areas, traps, and state (28 symbols)
  • osrlib.crawl.encounter — The encounter procedure: surprise, distance, reaction, parley, evasion, pursuit (7 symbols)
  • osrlib.crawl.events — The crawl event types, the combined registry, and the any-event parser (46 symbols)
  • osrlib.crawl.exploration — The exploration turn: movement, doors, searching, traps, light, rest, wandering checks (11 symbols)
  • osrlib.crawl.party — The crawl party: marching order, group movement, and combat ranks (1 symbols)
  • osrlib.crawl.session — GameSession: the command loop, the event log, listeners, flags, and views (12 symbols)
  • osrlib.crawl.views — The projection API: the player's safe whitelist and the referee's full state (11 symbols)

Shared services

  • osrlib.data — Generated SRD data and its typed loaders (12 symbols)
  • osrlib.errors — Exception hierarchy for out-of-fiction failures (4 symbols)
  • osrlib.messages — The default English message formatter (1 symbols)
  • osrlib.persistence — Save/load and replay: two paths to a running session, guaranteed to agree (5 symbols)
  • osrlib.versioning — Schema and engine version stamping (4 symbols)