osrlib.crawl.adventure
The adventure container: dungeons, the base town, and scenario metadata.
An adventure is frozen game content — the session runs it, never mutates it. The base town anchors the XP rule's "survive and return to safety" and safe day-level rest. It is a marker offering safe rest and equipment purchase through the kernel, not a simulated town. Content prose lives in these models — events carry ids and front ends resolve prose against the adventure.
validate_adventure is the fail-fast
content gate: dangling references (transition targets, monster template ids,
item ids, area cells out of bounds) raise
ContentValidationError before a session
ever runs the content.
Adventure
Bases: BaseModel
An adventure: one or more dungeons plus the base town and metadata.
monsters are the adventure's bundled custom
MonsterTemplates: they join the
shipped catalog for this adventure's sessions everywhere the engine resolves
template ids (keyed encounters, SpawnMonsters, inline wandering tables,
listen checks). Bundled ids must not collide with the shipped catalog or each
other — a collision is a validation error, never an override. The empty tuple
is the universal default: an adventure that bundles nothing plays exactly as
before.
dungeon
dungeon(dungeon_id: str) -> DungeonSpec
Return the dungeon with dungeon_id.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dungeon_id
|
str
|
The dungeon id. |
required |
Returns:
| Type | Description |
|---|---|
DungeonSpec
|
The dungeon spec. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no dungeon has that id. |
TownSpec
Bases: BaseModel
The base town: safe rest, equipment purchase, and travel costs.
services is prose for front ends. travel_turns maps dungeon ids to the
town-to-entrance travel cost in exploration turns — content-authored, consumed
by EnterDungeon and TravelToTown.
validate_adventure
validate_adventure(adventure: Adventure, monsters: MonsterCatalog, equipment: EquipmentCatalog) -> None
Validate an adventure's cross-references — the fail-fast content gate.
Checks: bundled monster ids colliding with the shipped catalog or each other;
then, per level: area cells and features in bounds, feature ids unique, cache
item ids resolving against the equipment catalog, cache magic item ids
resolving against the shipped magic-item catalog
(load_magic_items — adventures bundle no
magic items, so validation loads it itself), keyed-encounter template ids
(and any fixed spawn alignment) and inline wandering-table monster ids
resolving against the effective catalog, transition destinations resolving to
real cells, town travel entries naming real dungeons, and an entrance existing
somewhere in every dungeon.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adventure
|
Adventure
|
The adventure to validate. |
required |
monsters
|
MonsterCatalog
|
The base monster catalog — validation unions it internally with the adventure's bundled templates, and every monster reference resolves against that union. |
required |
equipment
|
EquipmentCatalog
|
The equipment catalog cache contents resolve against. |
required |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
Listing every dangling reference found. |