API reference
B/X (1981 Basic/Expert) rules engine for turn-based dungeon crawlers.
osrlib applies the rules of a game and stores its state. It has no user interface (UI), never waits for a player, and makes no network calls. You write the program a player uses, and that program calls osrlib. You pass osrlib a command, an object that describes one player action. osrlib applies the rules and returns typed events, each a record of one thing that happened. Your program turns those events into what the player sees. Every random number comes from a named, seeded stream, so if you replay the same commands from the same seed, you get the same game.
Each name is defined in one module, and the package root doesn't re-export any names, so import each name from the module that defines it. osrlib has three layers of modules.
The core kernel
The kernel, under osrlib.core, contains the rules without a session, a dungeon, or an
adventure. You pass a kernel function the inputs for one rule, plus a seeded stream and a
ruleset, and it returns the outcome and the events that describe it. Call kernel functions
directly to roll a character, resolve an attack, or price a sword without starting a session.
Kernel modules never import from osrlib.crawl, so you can use them without it.
| Module | What it's for |
|---|---|
osrlib.core.rng |
Turn a master seed into a separate random-number stream for each subsystem. |
osrlib.core.dice |
Parse a dice expression like "2d6+1", and roll it. |
osrlib.core.ruleset |
Turn optional rules on or off, in one model the kernel reads. |
osrlib.core.clock |
Count game time in rounds, and report each turn and day that passes. |
osrlib.core.alignment |
The three alignments that characters and monsters share. |
osrlib.core.validation |
The refusal a rules check returns instead of raising an exception. |
osrlib.core.frozen |
The read-only mapping in frozen content, like an ability's numbers or a level's edges. |
osrlib.core.abilities |
Look up the modifier or chance an ability score gives, and make ability checks. |
osrlib.core.classes |
Read a class's titles and level table, and award experience points (XP). |
osrlib.core.monsters |
Read monster templates, and spawn a monster with rolled hit points. |
osrlib.core.items |
Buy and equip items, and work out how much a character carries. |
osrlib.core.spells |
Memorize and cast spells, and turn undead. |
osrlib.core.tables |
Look up the printed tables, like the attack roll a THAC0 needs against an armour class. |
osrlib.core.character |
Roll a 1st-level character, in one call or one step at a time. |
osrlib.core.npc |
Generate a party of non-player characters (NPCs). |
osrlib.core.creature |
The attributes rules functions read, so they accept a character or a monster. |
osrlib.core.combat |
Roll initiative, attacks, damage, saving throws, and morale. |
osrlib.core.effects |
Run a timed effect, like a sleep spell, against the clock and end it on time. |
osrlib.core.treasure |
Roll treasure from a treasure type: coins, gems, jewellery, and magic items. |
osrlib.core.events |
The base class of every event, and the events the kernel functions return. |
The crawl framework
The crawl framework, under osrlib.crawl, is the game built on those rules: a party that
explores a mapped dungeon, driven by commands. You author the content, start a session, and pass
it one command per player action. The session runs the exploration, encounter, and battle
procedures for you and returns the events. The table lists the modules for authoring content
first, then the session and the modules it runs.
| Module | What it's for |
|---|---|
osrlib.crawl.dungeon |
Build dungeon levels from cells, edges, doors, areas, and traps. |
osrlib.crawl.adventure |
Combine dungeons and a town into an adventure a session can play, and validate it. |
osrlib.crawl.party |
Put characters in marching order, and move them as one group. |
osrlib.crawl.gates |
Write the conditions the party must meet before it can go through a door or a transition. |
osrlib.crawl.triggers |
Write what happens when an event you describe occurs in play. |
osrlib.crawl.quests |
Write quests: their objectives and the events that complete them. |
osrlib.crawl.narrative |
Write the text shown with a gate, trigger, or quest, and the guidance for a narrator. |
osrlib.crawl.stocking |
Roll a room's monsters and treasure from the B/X tables. |
osrlib.crawl.content_pack |
Move room contents from one adventure to another, without the map. |
osrlib.crawl.session |
Start a game from a party, an adventure, and a seed, and run it one command at a time. |
osrlib.crawl.commands |
Every command you can execute, and the session modes each one is legal in. |
osrlib.crawl.events |
Every event a command can return, and the parser that reads a stored one. |
osrlib.crawl.views |
What the players may see of a session, or the fuller view for the referee (game master). |
osrlib.crawl.interpreter |
Register this listener on a session to run the adventure's triggers and quests. |
osrlib.crawl.exploration |
How the session runs movement, doors, searching, light, rest, and wandering checks. |
osrlib.crawl.encounter |
How the session runs surprise, distance, reaction, evasion, and pursuit. |
osrlib.crawl.battle |
How the session runs a battle, one round at a time. |
Shared services
The shared services are at the top level, and both layers use them: the compiled rules content, the exceptions, the message formatter, and the save and version documents.
| Module | What it's for |
|---|---|
osrlib.data |
Load the compiled rules content and look up an entry by id, like "fighter" or "goblin". |
osrlib.errors |
The exceptions osrlib raises, and the failure each one means. |
osrlib.messages |
Turn an event into a line of default English text. |
osrlib.persistence |
Save a session to a document, and restore it by loading or replaying. |
osrlib.versioning |
The two version numbers in every saved document, and the wrapper that contains them. |
Quickstart
The quickstart goes through the whole loop: characters, party, adventure, session, commands, events, save, and load. For a step-by-step explanation of this example, see the quickstart at https://mmacy.github.io/osrlib-python/getting-started/quickstart/.
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