Skip to content

osrlib.crawl.adventure

The adventure: the root document a session plays.

An Adventure contains everything you need to run a game except the party and the seed for the random numbers. You build the levels in osrlib.crawl.dungeon, put them in dungeons, write a TownSpec for the base town, and combine them here. Then you pass the adventure and a Party to GameSession.new with a seed, and it starts the game.

The members, in the order you use them:

  • TownSpec: the base town, where a session starts.
  • PartySpec: the levels and number of characters the adventure is written for. osrlib doesn't read it.
  • Adventure: the town, the dungeons, and the monsters, items, spells, triggers, and quests the adventure adds.
  • validate_adventure: takes an adventure and the built-in catalogs, and raises ContentValidationError with a list of every problem it finds.

An adventure is frozen. The session reads it and never changes it. Everything that changes in play goes into the session's DungeonState instead, so what you wrote stays apart from what happened, and a save contains both. Names and descriptions live in these models, not in events. An event contains ids, so to show a player the text, you look each id up in the adventure.

Besides its dungeons, an adventure can add content and behavior. monsters, items, and spells bundle templates that join the built-in catalogs in the sessions that play this adventure. triggers (TriggerSpec) define what happens when something happens in play, and quests (QuestSpec) define what the party is trying to do. Gates (GateSpec) go on the doors and transitions of the levels.

validate_adventure checks that the document is consistent before anyone plays it. It follows the ids in the tree to what they refer to, and raises one error that lists every problem it finds. GameSession.new calls it for you, so a session doesn't start on content that fails it. Call it yourself while you write the adventure and you find the problems sooner.

The guide Building an adventure walks through a complete program you can run.

Adventure

Bases: BaseModel

An adventure: one or more dungeons, the base town, and everything they need.

This is the root of the content tree and the document a session plays. Build the levels first, put them in DungeonSpecs, write a TownSpec, and construct the adventure from them. Then call GameSession.new with a Party and the adventure. It validates the adventure, gives each party member an entity id, combines the built-in catalogs with the templates the adventure bundles, sets up the state of each quest, and returns a session with the party in town. The adventure is frozen, and it stays as you wrote it for the life of the session.

Every model in the tree is a pydantic model with keyword arguments, so you can write an adventure as Python calls, generate it from your own file format, or round-trip it through JSON with pydantic's model_dump_json and model_validate_json. osrlib has no function that reads an adventure from a file.

Attributes:

Name Type Description
name str

The adventure's title.

description str

Text describing the adventure.

hooks tuple[str, ...]

Reasons a party might take the adventure on.

party PartySpec | None

The party the adventure is written for, if it gives one.

town TownSpec

The base town.

dungeons tuple[DungeonSpec, ...]

The dungeons, at least one.

monsters tuple[MonsterTemplate, ...]

Monster templates the adventure adds.

items tuple[ItemTemplate, ...]

Item templates the adventure adds.

spells tuple[SpellTemplate, ...]

Spell templates the adventure adds.

triggers tuple[TriggerSpec, ...]

What happens when something happens in play.

quests tuple[QuestSpec, ...]

What the party is trying to do.

Raises:

Type Description
ValueError

If two dungeons have the same id.

Examples:

from osrlib.crawl.adventure import Adventure, TownSpec, validate_adventure
from osrlib.crawl.dungeon import DungeonSpec, Edge, EdgeKind, LevelSpec
from osrlib.data import load_equipment, load_monsters

# Two cells joined west to east, entered at the west end.
corridor = 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=(corridor,))
adventure = Adventure(
    name="A First Delve",
    town=TownSpec(name="Threshold", travel_turns={"crypt": 1}),
    dungeons=(crypt,),
)
validate_adventure(adventure, load_monsters(), load_equipment())

print(adventure.dungeon("crypt").level(1).entrance)
# (0, 0)

name instance-attribute

name: str

The adventure's title, to show the player.

description class-attribute instance-attribute

description: str = ''

Text describing the adventure, to show the player.

hooks class-attribute instance-attribute

hooks: tuple[str, ...] = ()

The reasons a party might take the adventure on, as free-form strings, like a rumour in the tavern or a patron's offer. osrlib never reads them. They let the adventure document include its pitch.

party class-attribute instance-attribute

party: PartySpec | None = None

The levels and number of characters the adventure is written for, or None when it doesn't give one. osrlib never reads it. See PartySpec.

town instance-attribute

town: TownSpec

The base town. There is exactly one, and the session starts there. See TownSpec.

dungeons class-attribute instance-attribute

dungeons: tuple[DungeonSpec, ...] = Field(min_length=1)

The dungeons, at least one, each with a unique id. One level of each dungeon needs an entrance, because that is where the party arrives from town.

monsters class-attribute instance-attribute

monsters: tuple[MonsterTemplate, ...] = ()

MonsterTemplates the adventure adds to the built-in catalog. In the sessions that play this adventure, they work everywhere a monster template id does: keyed encounters, SpawnMonsters, wandering tables on a level, and listening at doors.

A bundled id can't be the same as a built-in id or another bundled id. validate_adventure reports a repeated id instead of letting one template replace the other, because the template id in a session's events has to refer to one monster. Each treasure type letter in a bundled template's treasure has to be a B/X treasure type, A to V, and validate_adventure reports one that isn't. The guide Authoring custom classes, spells, monsters, and items covers writing a monster template.

items class-attribute instance-attribute

items: tuple[ItemTemplate, ...] = ()

ItemTemplates the adventure adds to the built-in equipment catalog: weapons, armour, gear, and ammunition. In the sessions that play this adventure, they work everywhere an authored item id does: treasure caches, has_item gates, GrantItem, and picking up a drop pile. An item instance includes its template, so a bundled item can be given, equipped, and dropped like any other.

A bundled id can't be the same as an id in the equipment catalog, the magic-item catalog, or another bundled item, because one item id has to mean one thing in a session. The town shop doesn't sell bundled items. It sells only the built-in equipment.

spells class-attribute instance-attribute

spells: tuple[SpellTemplate, ...] = ()

SpellTemplates the adventure adds to the built-in spell catalog. In the sessions that play this adventure, they work everywhere a spell id does: PrepareSpells, LearnSpell, CastSpell, and a cast declaration in a battle. A caster can prepare and cast a bundled spell when the spell's spell_list is the list of the caster's class, as for a built-in spell. GameSession.effective_spells is the catalog the session looks them up in.

A bundled id can't be the same as a built-in spell id or another bundled id, because a spell id on a character and in a session's events has to refer to one spell. validate_adventure reports a repeated id instead of letting one template replace the other.

To give a new caster a bundled spell in their first spell book, pass a catalog with the same spells to create_character as spell_catalog. The spells on a scroll that treasure rolls, and the spells of an NPC adventurer, come from the built-in catalog only. The guide Authoring custom classes, spells, monsters, and items covers writing a spell and bundling it.

triggers class-attribute instance-attribute

triggers: tuple[TriggerSpec, ...] = ()

The adventure's TriggerSpecs: what happens when something happens in play. Triggers that match the same event fire in the order of this tuple.

Triggers do nothing by themselves. To play them, register an Interpreter on the session. An adventure with no triggers plays the same whether or not one is registered. See the guide Gates, triggers, and quests.

quests class-attribute instance-attribute

quests: tuple[QuestSpec, ...] = ()

The adventure's QuestSpecs: what the party is trying to do. When GameSession.new creates the session, it sets up the state of each quest in this order, and it goes through the quests in this order whenever it checks them.

The session keeps quest state apart from trigger state, so quest ids and trigger ids don't clash, and a quest can have the same id as a trigger.

dungeon

dungeon(dungeon_id: str) -> DungeonSpec

Return the dungeon with dungeon_id.

Use it to look up the dungeon that an id from a command, an event, or a PartyLocation refers to. Then call DungeonSpec.level to get a level.

Parameters:

Name Type Description Default
dungeon_id str

The dungeon's id.

required

Returns:

Type Description
DungeonSpec

The dungeon.

Raises:

Type Description
ValueError

If no dungeon has that id. The message includes the id.

quest

quest(quest_id: str) -> QuestSpec

Return the quest with quest_id.

Call it to show a quest's objectives and rewards next to the state the session keeps for it. The quest commands look up quest ids with this method, so the session refuses a quest command with an id that this method can't find.

Parameters:

Name Type Description Default
quest_id str

The quest's id.

required

Returns:

Type Description
QuestSpec

The quest.

Raises:

Type Description
ValueError

If no quest has that id. The message includes the id.

PartySpec

Bases: BaseModel

The party an adventure is written for: the character levels, and how many characters.

A published adventure states this on its cover or in its introduction, like "for 6 to 8 characters of levels 1 to 3". osrlib never reads it. It's there so you can pick a party that suits the adventure, in a front end, a converter, or a playtest.

Attributes:

Name Type Description
min_level int

The lowest character level the adventure is written for.

max_level int

The highest.

min_size int | None

The fewest characters, or None when the adventure gives no number.

max_size int | None

The most characters, or None when the adventure gives no number.

Raises:

Type Description
ValueError

If max_level is below min_level, or max_size is below min_size when both are given.

Examples:

from osrlib.crawl.adventure import PartySpec

party = PartySpec(min_level=1, max_level=3, min_size=6, max_size=8)
print(party.max_level)
# 3

min_level class-attribute instance-attribute

min_level: int = Field(ge=1)

The lowest character level the adventure is written for, 1 or more.

max_level class-attribute instance-attribute

max_level: int = Field(ge=1)

The highest character level the adventure is written for. Equal to min_level for an adventure written for one level.

min_size class-attribute instance-attribute

min_size: int | None = Field(default=None, ge=1)

The fewest characters the adventure is written for, or None when it gives no number.

max_size class-attribute instance-attribute

max_size: int | None = Field(default=None, ge=1)

The most characters the adventure is written for, or None when it gives no number.

TownSpec

Bases: BaseModel

The base town: where the party is safe, buys gear, and comes back to.

Every adventure has exactly one town, and a session starts there. The town is not a map: it has no grid, no rooms, and nothing to explore. It is where the rules that need a safe place apply. In town the party can rest, buy equipment, sell treasure, and pay a temple for healing. Under the default ruleset, the party earns the experience for a delve only once it is back in town.

Attributes:

Name Type Description
name str

The town's name.

description str

Text describing the town.

services tuple[str, ...]

The services the town offers, to list for the player.

travel_turns Annotated[Mapping[str, Annotated[int, Field(ge=0)]], FrozenMap]

The travel time from town to each dungeon.

healing_prices Annotated[Mapping[HealingService, Annotated[int, Field(ge=0)]], FrozenMap]

The town's temple prices, for the services it doesn't charge the standard price for.

Raises:

Type Description
ValueError

If a travel time in travel_turns is negative, or healing_prices has a negative price or a name that isn't a temple service.

Examples:

from osrlib.crawl.adventure import TownSpec

threshold = TownSpec(
    name="Threshold",
    services=("temple", "smith"),
    travel_turns={"crypt": 1},
    healing_prices={"raise_dead": 1000},
)
print(threshold.travel_turns["crypt"], threshold.healing_prices["raise_dead"])
# 1 1000

name instance-attribute

name: str

The town's name, to show the player, like "Threshold".

description class-attribute instance-attribute

description: str = ''

Text to show the player while the party is in town.

services class-attribute instance-attribute

services: tuple[str, ...] = ()

The services the town offers, as free-form strings like ("temple", "smith"). osrlib doesn't read them: the shop and temple commands work in any town. The session passes them to the player view as PlayerView.town_services, so you can list them on a town screen.

travel_turns class-attribute instance-attribute

travel_turns: Annotated[Mapping[str, Annotated[int, Field(ge=0)]], FrozenMap] = FrozenMap()

How long the trip from town to each dungeon's entrance takes, in exploration turns, keyed by dungeon id. EnterDungeon and TravelToTown each advance the clock by this many turns, so on the way to a distant dungeon and back, light sources burn down and the session uses up the party's rations at each day boundary. A trip to a dungeon with no entry here, or with 0, takes no time. Each value is 0 or more, and the model raises ValueError when you construct it with a negative one. Every key has to be the id of a dungeon in this adventure, and validate_adventure reports one that isn't.

You pass a dict, and the town stores a read-only FrozenMap of it, as it does for healing_prices, because every session started from the adventure reads the same town.

healing_prices class-attribute instance-attribute

What this town's temple charges for a service, in gold pieces, keyed by the service's name, like {"raise_dead": 1000}. PurchaseHealing charges this price, and a service you don't list costs the standard price from HEALING_SERVICES. Each price is 0 or more, and a price of 0 makes the service free. The model raises ValueError when you construct it with a negative price or with a key that isn't a HealingService.

The prices are part of the adventure, so a save contains them and a replayed purchase charges what it charged the first time. The session passes what the town charges for every service to the player view as PlayerView.town_healing_prices.

validate_adventure

validate_adventure(adventure: Adventure, monsters: MonsterCatalog, equipment: EquipmentCatalog) -> None

Check that every id in an adventure refers to something that exists, and that the session can play it.

Call it while you write an adventure. It follows the references in the tree and raises once, with a list of everything wrong, so you can fix the whole document in one pass. It changes nothing, and it returns None when the adventure passes. GameSession.new calls it too, so a session never starts on content that fails these checks.

For the whole adventure, it checks that:

  • Bundled monster ids are unique and aren't in monsters.
  • Bundled item ids are unique and aren't in equipment or the built-in magic-item catalog.
  • Bundled spell ids are unique and aren't in the built-in spell catalog. For a bundled monster, item, or spell, the message says whether its id repeats within the bundle or is already a built-in id.
  • Each treasure type letter in a bundled monster's treasure is the letter of a treasure type in load_treasure_tables().
  • Each dungeon id in the town's travel_turns is a dungeon of the adventure.
  • Each dungeon has at least one level whose entrance is set.

For each level, it checks the parts you lay out on the level's grid:

  • The entrance is on the grid.
  • Each key in edges is the edge_key of a side of a cell on the grid. The session reads an edge only under that key.
  • Area ids are unique, and every area cell is on the grid. An area is a keyed room or cave, an AreaSpec.
  • Each area has at least one cell of its own. A cell that two areas list belongs to the one listed first, so an area whose cells all belong to earlier areas can never be entered.
  • Each treasure type letter in an area's treasure is the letter of a treasure type.
  • Feature ids are unique across the level, and none is "pile", which is reserved for drop piles. A feature is something in the dungeon that the party can find and act on, like a treasure cache, a FeatureSpec.
  • No area has the same id as a feature. The session records found, sprung, and removed traps by area id and feature id in the same way, so it would confuse the two.
  • Every feature cell is on the grid, and every feature listed on the level itself, not on an area, has a cell.
  • The cell of a feature listed on an area, when it has one, is one of the area's cells, and belongs to that area rather than to an area listed before it.

It checks the ways in and out, where a transition is stairs, a trapdoor, a chute, or a passage (a TransitionSpec), and a gate is a condition on a door or a transition (a GateSpec):

  • Each transition stands on the grid and leads to a cell on the grid of a level that exists.
  • Each passage stands on a wall. Its far cell is the cell one step across that wall. The far cell is on the grid, outside every area, and walled on its other three sides.
  • No passage leads to the cell it stands on, or to any passage's far cell.
  • No two passages share a cell and side.
  • The item id of each has_item gate on a door or a transition resolves.

It checks traps:

  • An area whose room trap has trigger="open" has a door on at least one edge of its cells. A door that starts open counts. A trap with trigger="enter" needs no door.
  • No area trap and no feature trap moves the party through a passage.
  • The transition in an area trap or a feature trap gets the same checks as a level's transitions: it stands on the grid and leads to a cell on the grid of a level that exists.

It checks what the party meets and finds:

  • Each monster id in a keyed encounter resolves, and an encounter's fixed alignment is one the monster's template allows.
  • The monster ids in the level's wandering.table, when it has one, resolve.
  • The ids in each feature's item_ids and magic_item_ids resolve.

For each trigger, it checks that the id is unique, and that the area, level, dungeon, item, or monster its pattern refers to exists. For each of the trigger's consequences, it checks that:

  • A granted or removed item is in the equipment catalog or the magic item catalog.
  • A spawned monster resolves.
  • A door-state change refers to an edge where a door stands.
  • A party placement is on the grid.

For each quest, it checks that the id is unique. It runs the same checks over each of the quest's clauses (its activation, each objective's completion, and each hidden objective's reveal) and over each reward.

A consequence or reward that gives a character something, or takes something away, has to address the party with a selector, not a character id. A selector is a placeholder that the interpreter replaces with real character ids during play. GameSession.new gives out character ids, so a character id written in an adventure can't refer to a character. Every such command accepts "@party" and "@first". A RemoveItem also accepts "@carrier".

It doesn't check flag keys. Any key can be set during play, so an unset key isn't an error in the document.

You don't pass a magic-item catalog. You can't bundle magic items in an adventure, so the function loads the built-in one with load_magic_items. You don't pass a spell catalog either. The function checks the bundled spells against the built-in catalog from load_spells, and nothing else in an adventure refers to a spell id.

It checks quest ids and trigger ids separately, so a quest can have the same id as a trigger.

Parameters:

Name Type Description Default
adventure Adventure

The adventure to check.

required
monsters MonsterCatalog

The base monster catalog, usually load_monsters(). The function combines it with the adventure's bundled monsters, and resolves every monster id against the result. Pass the base catalog, not one you have already combined with the bundle, or every bundled monster is reported as a repeated id.

required
equipment EquipmentCatalog

The base equipment catalog, usually load_equipment(). The function combines it with the adventure's bundled items in the same way.

required

Raises:

Type Description
ContentValidationError

If any check fails. The message starts with adventure validation failed:, then lists each problem on a separate line with where it is, like the dungeon, the level, and the object. Fix the adventure and call again. The same adventure always fails with the same message.

Examples:

from osrlib.crawl.adventure import Adventure, TownSpec, validate_adventure
from osrlib.crawl.dungeon import AreaSpec, DungeonSpec, KeyedEncounter, KeyedMonster, LevelSpec
from osrlib.data import load_equipment, load_monsters
from osrlib.errors import ContentValidationError

hall = AreaSpec(
    id="hall",
    cells=((0, 0),),
    encounter=KeyedEncounter(monsters=(KeyedMonster(template_id="grue", count_fixed=1),)),
)
level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0), areas=(hall,))
broken = Adventure(
    name="A First Delve",
    town=TownSpec(name="Threshold"),
    dungeons=(DungeonSpec(id="crypt", levels=(level,)),),
)
try:
    validate_adventure(broken, load_monsters(), load_equipment())
except ContentValidationError as error:
    print(error)
# adventure validation failed:
# crypt level 1: area 'hall' references unknown monster 'grue'