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 raisesContentValidationErrorwith 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 |
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)
description
class-attribute
instance-attribute
description: str = ''
Text describing the adventure, to show the player.
hooks
class-attribute
instance-attribute
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
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 |
required |
Returns:
| Type | Description |
|---|---|
DungeonSpec
|
The dungeon. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no dungeon has that id. The message includes the id. |
quest
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 |
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 |
max_size |
int | None
|
The most characters, or |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
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
The lowest character level the adventure is written for, 1 or more.
max_level
class-attribute
instance-attribute
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
The fewest 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 |
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
description
class-attribute
instance-attribute
description: str = ''
Text to show the player while the party is in town.
services
class-attribute
instance-attribute
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
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
healing_prices: Annotated[Mapping[HealingService, Annotated[int, Field(ge=0)]], FrozenMap] = FrozenMap()
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
equipmentor 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
treasureis the letter of a treasure type inload_treasure_tables(). - Each dungeon id in the town's
travel_turnsis a dungeon of the adventure. - Each dungeon has at least one level whose
entranceis 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
edgesis theedge_keyof 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
treasureis 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, aFeatureSpec. - 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_itemgate 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 withtrigger="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
alignmentis 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_idsandmagic_item_idsresolve.
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 |
required |
equipment
|
EquipmentCatalog
|
The base equipment catalog, usually
|
required |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If any check fails. The message starts with
|
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'