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.

name instance-attribute

name: str

description class-attribute instance-attribute

description: str = ''

hooks class-attribute instance-attribute

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

town instance-attribute

town: TownSpec

dungeons class-attribute instance-attribute

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

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.

name instance-attribute

name: str

description class-attribute instance-attribute

description: str = ''

services class-attribute instance-attribute

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

travel_turns class-attribute instance-attribute

travel_turns: dict[str, int] = {}

validate_adventure

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

Validate an adventure's cross-references — the fail-fast content gate.

Checks, per level: area cells and features in bounds, feature ids unique, cache item ids resolving against the equipment catalog, keyed-encounter template ids (and any fixed spawn alignment) resolving against the monster 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 monster catalog keyed encounters resolve against.	required
equipment	EquipmentCatalog	The equipment catalog cache contents resolve against.	required

Raises:

Type	Description
ContentValidationError	Listing every dangling reference found.