osrlib.crawl.dungeon
The dungeon: the grid you author, and the record of what play changes in it.
This module defines both halves of a dungeon. DungeonSpec and
everything inside it (levels, edges, areas, features, traps, transitions) is authored content:
frozen models you build, put in an Adventure, and never
change. DungeonState is the overlay: the mutable record a
running session keeps beside the content, of which cells the party has walked, which doors stand
open, which traps have gone off, what lies on the floor, and where the party is. A save contains the
overlay. The overlay refers to content by id strings, not by object, so it serializes as flat data.
You build the levels here and combine them into an adventure in
osrlib.crawl.adventure. You never construct a DungeonState yourself:
GameSession.new creates one, and you read it through the
session's views. The guide
Building an adventure
walks through a complete program you can run.
Every model here uses one grid. A level is a grid of 10-foot cells, each addressed (x, y). x
increases to the east and y increases to the south, from (0, 0) in the northwest corner. Every
edge between two cells is a wall unless you say otherwise. A level's edges map has one entry for
each edge that isn't a wall, keyed by edge_key, so an edge has
exactly one key whichever of its two cells you name it from. An edge with no entry is a wall, and so
is every edge on the level's boundary.
The members, in the order you use them:
- Addressing the grid:
Position,Direction,step, andedge_key. - What stands on an edge:
EdgeKind,Edge, andDoorSpec. - A keyed room and its content:
AreaSpec, with aKeyedEncounterofKeyedMonsterlines, anAreaTreasureSpec,FeatureSpecs with theirValuableSpecs, and aTrapSpecwith itsTrapEffect. - A level and its dungeon:
TransitionSpec,WanderingSpec,LevelSpec, andDungeonSpec. - The overlay, which you read during play:
DungeonStateand what it contains,PartyLocation,DoorState,DropPile,DroppedItem, andGeneratedCache, withcell_refandedge_reffor its keys.TreasureBundlecontains the treasure that monsters carry during an encounter.
Typical usage:
from osrlib.crawl.dungeon import Direction, DungeonSpec, Edge, EdgeKind, LevelSpec, edge_key
# A two-cell corridor running west to east, entered at the west end.
corridor = LevelSpec(
number=1,
width=2,
height=1,
entrance=(0, 0),
edges={edge_key((0, 0), Direction.EAST): Edge(kind=EdgeKind.OPEN)},
)
crypt = DungeonSpec(id="crypt", name="The Old Crypt", levels=(corridor,))
print(edge_key((0, 0), Direction.EAST))
# 1,0:west
print(crypt.level(1).edge((0, 0), Direction.NORTH).kind)
# wall
Position
module-attribute
A cell address on a level's grid: (x, y).
x increases to the east and y increases to the south, from (0, 0) in the level's northwest
corner. A cell is 10 feet on a side. Write a position as a plain tuple, like (3, 0). A position
means something only on a particular level. A position off a level's grid is out of bounds, not
malformed: call LevelSpec.in_bounds to check one.
validate_adventure reports an authored position that
is off its level's grid.
AreaSpec
Bases: BaseModel
A keyed room or cave: a named group of cells with content bound to it.
Areas are how you key a dungeon, the way a printed adventure numbers its rooms. Each area covers
some cells of a LevelSpec, and a cell outside every area is
corridor. When the party moves into a cell of the area, the session rolls the area's treasure,
rolls for a trap that springs on entering, and spawns the encounter, in that order. Showing the
area's description is up to you.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
str
|
The area's id, unique across its level. |
name |
str
|
The room's name. |
description |
str
|
Text describing the room. |
cells |
tuple[Position, ...]
|
The cells the area covers. |
encounter |
KeyedEncounter | None
|
The monsters waiting here. |
features |
tuple[FeatureSpec, ...]
|
The keyed things in the room. |
trap |
TrapSpec | None
|
A room trap over the whole area. |
treasure |
AreaTreasureSpec | None
|
Unguarded treasure the session rolls. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
from osrlib.crawl.dungeon import AreaSpec, KeyedEncounter, KeyedMonster
guard_post = AreaSpec(
id="guard_post",
name="Guard post",
description="Two goblins crouch over a game of knucklebones.",
cells=((3, 0),),
encounter=KeyedEncounter(monsters=(KeyedMonster(template_id="goblin", count_fixed=2),)),
)
print(guard_post.cells)
# ((3, 0),)
id
instance-attribute
id: str
The area's id, unique within the level. Events contain it, triggers match on it, and the overlay stores the state of the area's encounter, treasure, and trap under it.
name
class-attribute
instance-attribute
name: str = ''
The room's name, to show the player, like "Guard post" or "The abbot's cell".
description
class-attribute
instance-attribute
description: str = ''
Text to show when the party walks in. Events contain the area's id, not its text, so look the text up here.
cells
class-attribute
instance-attribute
The cells the area covers, at least one. They don't have to touch each other, though a room's
cells usually do. Every cell has to be on the level's grid. The first cell is where the session
puts the encounter's lair hoard. A cell that two areas list belongs to the one listed first in
the level's areas. Each area needs at least one cell that no earlier area lists, or the party
can never enter it, and validate_adventure reports
an area without one.
encounter
class-attribute
instance-attribute
encounter: KeyedEncounter | None = None
The monsters waiting in the room, or None for a room without any. See
KeyedEncounter.
features
class-attribute
instance-attribute
features: tuple[FeatureSpec, ...] = ()
The keyed things in the room: treasure caches, construction tricks, and custom features. A
feature here can leave its cell unset, and then the party can reach it from any cell of the
area.
trap
class-attribute
instance-attribute
trap: TrapSpec | None = None
A trap over the whole area, or None. It has to be a room trap. It can spring when the party
moves into a cell of the area, or, with trigger="open", when the party opens a door on the
edge of one of the area's cells.
treasure
class-attribute
instance-attribute
treasure: AreaTreasureSpec | None = None
Treasure the session rolls the first time the party enters, for a room with treasure and no
monster guarding it, or None. For a room whose treasure belongs to its monsters, use the
encounter's hoard flag instead.
AreaTreasureSpec
Bases: BaseModel
Treasure the session rolls for an area, with no monster guarding it.
Put one on an AreaSpec when you want the room to contain treasure
but don't want to choose it. The session rolls it the first time the party enters the area, and
puts the result on the cell where the party entered, as a
GeneratedCache. The party takes it with
TakeTreasure. If the roll comes up empty, the session
puts nothing down. Rolled treasure is never trapped. To trap treasure, write a
FeatureSpec with a trap.
When the treasure belongs to the monsters in the room, use the hoard flag of the area's
KeyedEncounter instead. The session then rolls the
monsters' lair treasure.
Attributes:
| Name | Type | Description |
|---|---|---|
letters |
tuple[str, ...]
|
The treasure type letters to roll. |
unguarded |
bool
|
Whether to roll on the unguarded-treasure table for the level instead. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If both |
Examples:
from osrlib.crawl.dungeon import AreaTreasureSpec
print(AreaTreasureSpec(letters=("C",)).unguarded)
# False
letters
class-attribute
instance-attribute
One or more B/X treasure type letters, like ("C",). The session rolls each letter's table
and puts the results in one cache. The letters are A to V. See
the treasure type index,
or read the letter of each entry in the treasure_types of
load_treasure_tables().
validate_adventure reports any other letter. Set
this or unguarded, not both.
unguarded
class-attribute
instance-attribute
unguarded: bool = False
Whether to roll on the OSE SRD's table for unguarded treasure instead of listing letters. The
table has a row for each band of dungeon levels, and the session uses the row for the number of
the level the area is on, so the treasure is bigger on deeper levels. Set this or letters, not
both.
Direction
Bases: StrEnum
The four grid directions the party faces and moves in.
You use these for the way MoveParty steps, the side of a
cell OpenDoor works on, and the way a transition turns the
party on arrival. There is no up or down. A
TransitionSpec moves the party between levels.
The values are lowercase strings, like "north", and they appear in commands, events, and saves.
SOUTH
class-attribute
instance-attribute
Increasing y: toward the bottom of the map.
vector
property
The (dx, dy) change in position for one step in this direction, like (0, -1) for north.
Add it to a position to get the neighbouring cell, or call
step, which does the addition for you.
opposite
property
opposite: Direction
The reverse direction, like SOUTH for NORTH.
A cell's edge in one direction is its neighbour's edge in the opposite direction. Use it to
name a door from the cell on its other side, or to set up the return passage of a
TransitionSpec.
DoorSpec
Bases: BaseModel
A door on an edge, as you wrote it.
Put one in the door field of an Edge whose kind is door.
Every field is the door's state at the start of the game, and play never changes it. What the
party does to the door goes into a DoorState in the overlay
instead, so read the overlay to find out whether a door is open now.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
Literal['normal', 'secret']
|
Whether the party can see the door from the start, or has to find it. |
stuck |
bool
|
Whether the party has to force the door open. |
locked |
bool
|
Whether the party has to unlock the door before it opens. |
starts_open |
bool
|
Whether the door stands open at the start of the game. |
requires |
GateSpec | None
|
A condition the party has to meet to open the door. |
Examples:
from osrlib.crawl.dungeon import DoorSpec, Edge, EdgeKind
vault = Edge(kind=EdgeKind.DOOR, door=DoorSpec(locked=True))
print(vault.door.locked, vault.door.kind)
# True normal
kind
class-attribute
instance-attribute
kind: Literal['normal', 'secret'] = 'normal'
"normal" for a door the party can see, or "secret" for one it has to find. A secret door is
hidden until the party finds it with a Search for secret
doors, which sets discovered in the door's DoorState. Until then the party
can't open it, listen at it, or walk through it, and the player view shows the edge as a wall.
stuck
class-attribute
instance-attribute
stuck: bool = False
locked
class-attribute
instance-attribute
locked: bool = False
Whether the door is locked. The session refuses both OpenDoor
and ForceDoor on a locked door until it is unlocked, by a
thief's PickLock or by a referee's
SetDoorState. A door that is both locked and stuck has to
be unlocked and then forced.
starts_open
class-attribute
instance-attribute
starts_open: bool = False
Whether the door stands open at the start of the game. Doors that the party opens swing shut
behind it as it walks on, but a door that starts open doesn't, because the party didn't open it.
The party can still close it with CloseDoor.
requires
class-attribute
instance-attribute
requires: GateSpec | None = None
A gate on opening the door, or None for a door that opens without one. A gate
(GateSpec) is a condition, like carrying a key, that the
session checks each time the party tries to open or force the door. The session checks it last,
after every other reason to refuse the command. It is separate from locked: to open a locked door with a gate,
the party has to unlock it and meet the gate's condition. PickLock deals only
with the lock, and SetDoorState changes the door without
checking the gate. The gate guards opening the door, not passing through it, so the party walks
through a door that stands open without a check. Once the door is closed again, the gate applies
to the next opening.
DoorState
Bases: BaseModel
What has happened to one door in play: open, wedged, discovered, unlocked.
This is the part of a door that changes. The DoorSpec is how
you wrote the door, and it never changes. A DoorState records what the party and the referee
have done to it since. Get one from DungeonState.door
with the door's edge_ref.
Attributes:
| Name | Type | Description |
|---|---|---|
open |
bool
|
Whether the door stands open. |
wedged |
bool
|
Whether a spike holds it. |
discovered |
bool
|
Whether the party has found a secret door. |
unlocked |
bool
|
Whether a locked door has been unlocked. |
opened_by_party |
bool
|
Whether the party opened it. |
open
class-attribute
instance-attribute
open: bool = False
Whether the door stands open now. The party walks through an open door without opening it. A
door whose spec sets starts_open is open until something closes it.
wedged
class-attribute
instance-attribute
wedged: bool = False
Whether an iron spike holds the door, from WedgeDoor. A
wedged door doesn't swing shut behind the party, and the party can't close it.
discovered
class-attribute
instance-attribute
discovered: bool = False
Whether the party has found a secret door. Until a Search
for secret doors sets it, a secret door is a wall to the party. It has no effect on a normal
door.
unlocked
class-attribute
instance-attribute
unlocked: bool = False
Whether a locked door has been unlocked, by a thief's
PickLock or by a referee's
SetDoorState. Closing the door doesn't lock it again. Only a
SetDoorState can.
DropPile
Bases: BaseModel
What lies on one cell's floor, waiting to be picked up.
Loose goods end up in piles: gear the party drops with
DropItems, what slain monsters leave at the end of an
encounter, and the part of a cache the party couldn't carry. The party picks up a whole pile with
TakeTreasure and the feature id "pile", which is why no
feature you write can use that id. Goods the party drops to distract monsters that chase it are
the exception: they are gone, not dropped in a pile.
The session keeps piles in DungeonState.piles, keyed
by cell_ref. A pile forms only on a cell where the party has
stood, so the party knows about every pile.
Attributes:
| Name | Type | Description |
|---|---|---|
items |
list[DroppedItem]
|
The ordinary items in the pile. |
coins |
Coins
|
The coins in the pile. |
valuables |
list[ValuableInstance]
|
The gems and jewellery in the pile. |
magic_items |
list[MagicItemInstance]
|
The magic items in the pile. |
items
class-attribute
instance-attribute
items: list[DroppedItem] = []
The ordinary items lying here, one stack for each template id.
coins
class-attribute
instance-attribute
The coins lying here, by denomination.
valuables
class-attribute
instance-attribute
valuables: list[ValuableInstance] = []
The gems and jewellery lying here, each with the id it had before it was dropped.
magic_items
class-attribute
instance-attribute
magic_items: list[MagicItemInstance] = []
The magic items lying here, each with the charges or quantity it had before it was dropped.
DroppedItem
DungeonSpec
Bases: BaseModel
A dungeon: one or more levels joined by transitions.
An Adventure contains its dungeons, and
EnterDungeon takes the party into one by its id. Build the
levels first, put them in a dungeon, then put the dungeon in an adventure with its town. An
adventure can have several dungeons, and a
TransitionSpec can lead to another dungeon's id, so a
stair can lead out of one dungeon and into the next.
A dungeon has no field for its way in. One of its levels needs an entrance, and
validate_adventure checks that one does.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
str
|
The dungeon's id. |
name |
str
|
The dungeon's name. |
levels |
tuple[LevelSpec, ...]
|
Its levels, at least one. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If two levels have the same |
Examples:
from osrlib.crawl.dungeon import DungeonSpec, Edge, EdgeKind, LevelSpec
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,))
print(crypt.level(1).width)
# 2
id
instance-attribute
id: str
The dungeon's id, unique within the adventure. You use it in
EnterDungeon, the town's travel_turns, and transitions
between dungeons, and every reference in the overlay includes it.
name
class-attribute
instance-attribute
name: str = ''
The dungeon's name, to show the player, like "The Old Crypt".
levels
class-attribute
instance-attribute
The dungeon's levels, at least one, each with a unique number. Look a level up by its number
with level, not by its position in the tuple. Only
EnterDungeon depends on the order: it puts the party on the
entrance of the first level in this tuple that has one, facing north.
level
Return the level with number.
Use it to look up the level that a number from a command, an event, or a transition refers to.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
number
|
int
|
The level's number. |
required |
Returns:
| Type | Description |
|---|---|
LevelSpec
|
The level. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no level has that number. The message includes the dungeon and the number. |
DungeonState
Bases: BaseModel
Everything that play has changed in the dungeons: the overlay the session keeps beside the content.
The adventure you wrote never changes. The running session records what happens to it here, and
a save contains it. GameSession.new creates one, and the
command handlers change it. Read it through
GameSession.view instead of reading the session's
copy, so each audience sees only what it is allowed to see. The referee view's dungeon_state
is a copy of it.
The overlay refers to content by strings, not by object, so it serializes as flat data and never repeats the adventure. It uses four formats of key:
"{dungeon}:{level}"keysexploredandseen, like"crypt:1".edge_refkeys doors, like"crypt:1:1,0:west"."{dungeon}:{level}:{id}"is an area reference or a feature reference, to an area or a feature you wrote, like"crypt:1:shrine".cell_refkeys drop piles, like"cell:crypt:1:2,3".
explored and seen are both maps of cells, and they mean different things. explored contains
the cells the party has walked into, and the session uses it for movement cost. seen contains the
cells the party's light has shown it, and only the player view reads it, so a map can still show
a room the party looked into and walked past.
The attempt records are here because they are game state that a save has to include: who has listened at a door, who has searched a cell for a kind of thing, and which thief failed a lock, at what level.
Attributes:
| Name | Type | Description |
|---|---|---|
location |
PartyLocation
|
Where the party is. |
explored |
dict[str, list[Position]]
|
Cells the party has walked into. |
seen |
dict[str, list[Position]]
|
Cells the party's light has shown it. |
doors |
dict[str, DoorState]
|
What has happened to each door. |
sprung_traps |
list[str]
|
Traps that have gone off. |
removed_traps |
list[str]
|
Treasure traps a thief has taken out. |
found_traps |
list[str]
|
Traps the party has found. |
found_tricks |
list[str]
|
Construction tricks the party has found. |
emptied_caches |
list[str]
|
Authored caches the party has emptied. |
piles |
dict[str, DropPile]
|
What is lying on the floor, by cell. |
generated_caches |
dict[str, GeneratedCache]
|
Treasure the session rolled, by cache id. |
generated_treasure_areas |
list[str]
|
Areas whose treasure the session has already rolled. |
generated_lair_hoards |
list[str]
|
Areas whose keyed encounter's hoard the session has already rolled. |
resolved_encounters |
list[str]
|
Areas whose keyed encounter has been cleared. |
listen_attempts |
dict[str, list[str]]
|
Who has listened at each door. |
search_attempts |
dict[str, list[str]]
|
Who has searched each cell for what. |
inspect_attempts |
dict[str, list[str]]
|
Who has inspected each cache for traps. |
removal_attempts |
dict[str, list[str]]
|
Who has tried to remove each trap. |
lock_failures |
dict[str, dict[str, int]]
|
Which thief failed each lock, and at what level. |
location
class-attribute
instance-attribute
location: PartyLocation = PartyLocation(kind='town')
Where the party is: in town, or on a dungeon cell. A new session starts in town.
explored
class-attribute
instance-attribute
The cells the party has walked into, as lists of positions keyed "{dungeon}:{level}". The
session uses it for movement cost: a step into an explored cell takes a third of the time of a
step into a new one. The player view also shows only the drop piles on explored cells.
seen
class-attribute
instance-attribute
The cells the party's light has shown it, as lists of positions keyed "{dungeon}:{level}".
It is what the party remembers of the map. Only the player view reads it, and it never affects
movement cost. mark_seen adds new cells in
sorted (x, y) order, so the same game always saves the same bytes.
doors
class-attribute
instance-attribute
sprung_traps
class-attribute
instance-attribute
The traps that have sprung, as area or feature references. A sprung trap never springs again.
removed_traps
class-attribute
instance-attribute
The treasure traps a thief has taken out with
RemoveTreasureTrap, as feature references. A removed
trap never springs. Room traps never appear here, because there is no way to disarm one.
found_traps
class-attribute
instance-attribute
The traps the party has found, as area or feature references: room traps from a
Search, and treasure traps from a thief's
InspectTreasure. A room trap here no longer springs. A
treasure trap here can still spring when the party opens the cache, and it has to be here before
RemoveTreasureTrap can take it out.
found_tricks
class-attribute
instance-attribute
The construction tricks the party has found with a
Search for construction, as feature references.
emptied_caches
class-attribute
instance-attribute
The caches you wrote that the party has emptied, as feature references. The party gets nothing
more from an emptied cache. A cache the session rolled isn't listed here. The session removes it
from generated_caches instead.
piles
class-attribute
instance-attribute
generated_caches
class-attribute
instance-attribute
generated_caches: dict[str, GeneratedCache] = {}
Treasure the session rolled, keyed by cache id, like "cache-0001". A
HoardGeneratedEvent reports the id,
TakeTreasure with that id takes the cache, and taking it
removes the entry. See GeneratedCache.
generated_treasure_areas
class-attribute
instance-attribute
The areas whose AreaTreasureSpec the session has
already rolled, as area references, so the session doesn't roll a room's treasure again when the
party enters it a second time.
generated_lair_hoards
class-attribute
instance-attribute
The areas whose KeyedEncounter hoard the session has
already rolled, as area references.
The session rolls a lair's hoard the first time the party meets its monsters. If the party leaves and comes back, the monsters spawn again, but the session doesn't roll the hoard again. The party finds the cache from the first visit, or nothing if it took that cache.
resolved_encounters
class-attribute
instance-attribute
The areas whose keyed encounter ended with every monster slain or routed, as area references. When the party enters one of these areas again, no monsters spawn.
listen_attempts
class-attribute
instance-attribute
Which characters have listened at each door, as lists of character ids keyed by
edge_ref. Each character gets one try at each door, so a bad
roll stands.
search_attempts
class-attribute
instance-attribute
Which characters have searched each cell for each kind of thing, as lists of character ids
keyed "{cell_ref}:{kind}". The kind is the kind of the
Search, like "cell:crypt:1:2,3:secret_doors". Each character
gets one try for each kind on each cell.
inspect_attempts
class-attribute
instance-attribute
Which characters have inspected each cache for traps, as lists of character ids keyed by feature reference. Each character gets one try at each cache.
removal_attempts
class-attribute
instance-attribute
Which characters have tried to remove each treasure trap, as lists of character ids keyed by
feature reference. Each character gets one try at each trap. A failed try springs the trap, unless
Ruleset.failed_trap_removal_springs is off.
lock_failures
class-attribute
instance-attribute
Which thieves failed to pick each lock, keyed by edge_ref.
Each value maps a character id to the thief's level at the time. A thief who failed a lock can
try it again after gaining a level, so the session records the level.
is_explored
Return whether the party has walked into a cell.
The session reads it for movement cost: a step into an explored cell takes a third of the time of a step into a new one. Call it to shade a map, or to work out what a move will cost.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dungeon_id
|
str
|
The dungeon's id. |
required |
level_number
|
int
|
The level's number. |
required |
position
|
Position
|
The cell. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True when the party has walked into the cell. False for a cell the party has only seen by its light. |
Examples:
mark_explored
Mark a cell as walked into.
The session calls it each time the party arrives on a cell, so you rarely call it yourself.
A cell you mark on a running session isn't in the command log, so
replay_game doesn't reproduce it. Marking a cell twice
changes nothing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dungeon_id
|
str
|
The dungeon's id. |
required |
level_number
|
int
|
The level's number. |
required |
position
|
Position
|
The cell. |
required |
mark_seen
Mark cells as seen, meaning the party's light has shown them.
The session calls it after every accepted command, so you rarely call it yourself. Only the
player view reads seen cells, so its map can still show a room the party's light reached
after the party has walked on. Seen cells don't affect movement cost, which comes from
is_explored. They don't make drop piles
visible either: the player view shows piles only on cells the party has walked into, which is
where piles form.
Marking a cell twice changes nothing. This method adds new cells in sorted (x, y) order,
whatever order you pass them in, so the same game always saves the same bytes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dungeon_id
|
str
|
The dungeon's id. |
required |
level_number
|
int
|
The level's number. |
required |
positions
|
Iterable[Position]
|
The cells to add. Cells already marked are skipped. |
required |
door
Return one door's current state, which you can read or change.
The session adds a door's entry to doors only when something in play changes the door. Use
this method to get a door's state whether or not that has happened yet. Reading the state never
changes doors.
- When the door has an entry, the method returns that entry. Writing to it writes to
doors. - When the door has no entry, the method returns a new state and doesn't store it. The first
time you set one of its fields, the state becomes the door's entry in
doors. If the door has gained an entry in the meantime, the write goes to that entry instead.
A new state starts from the door as you wrote it in its
DoorSpec, the same way as the entry the session's own
commands store. For a door whose starts_open is set, open reads True, and every other
field reads False. So setting one field changes only that field. For example,
door(ref).discovered = True on a door that starts open stores an entry that is open and
discovered, and the party can still walk through.
The method finds the DoorSpec in the adventure of the session that holds this state as its
GameSession.dungeon_state, whether you made
the session with GameSession.new or
load_game. A DungeonState you make yourself has no adventure,
and neither has a reference that names no door in the adventure. For those, a new state reads
False in every field.
To show doors the way the party sees them, read the player view from
GameSession.view.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
str
|
The door's |
required |
Returns:
| Type | Description |
|---|---|
DoorState
|
The door's entry in |
Examples:
from osrlib.crawl.dungeon import Direction, DungeonState, edge_ref
state = DungeonState()
# Both sides of one door give the same reference, and so the same state. The east
# side of cell (0, 0) is the west side of cell (1, 0). edge_ref always names an edge
# by its north or west side, so both calls return "crypt:1:1,0:west".
east_side = edge_ref("crypt", 1, (0, 0), Direction.EAST)
west_side = edge_ref("crypt", 1, (1, 0), Direction.WEST)
state.door(east_side).open = True
print(state.door(west_side).open, list(state.doors))
# True ['crypt:1:1,0:west']
Edge
Bases: BaseModel
One entry in a level's edges map: what stands on the edge between two cells.
Put these in LevelSpec.edges, keyed by
edge_key. You need entries only for edges that aren't walls,
because an edge with no entry is a wall. Read an edge back with
LevelSpec.edge, which returns a wall for an edge with no
entry and for the level's boundary.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
EdgeKind
|
What stands on the edge. |
door |
DoorSpec | None
|
The door, when |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
EdgeKind
Bases: StrEnum
What stands on an edge between two cells: nothing, a wall, or a door.
It is the kind of an Edge, and it sets whether the party can
cross the edge.
OPEN
class-attribute
instance-attribute
Nothing stands here, and the party can walk across.
WALL
class-attribute
instance-attribute
A wall, which the party can't cross. LevelSpec.edge
also returns a wall for an edge with no entry in the level's edges map, so you write this kind
only to state a wall explicitly.
DOOR
class-attribute
instance-attribute
A door, which the edge's DoorSpec describes. An edge of this
kind must have a door, and an edge of any other kind must not.
FeatureSpec
Bases: BaseModel
A keyed thing in a room: a treasure cache, a construction trick, or custom content.
Put features on an AreaSpec, or on a
LevelSpec for one outside any room. A feature is something in
the dungeon that the party can find and act on. Stairs aren't features: they are
TransitionSpecs.
osrlib runs one kind of feature for you, the treasure_cache. The party empties it with
TakeTreasure and the feature's id, and the contents go to
the party. The session creates the magic items you list only when the party empties the cache.
It rolls their details then, like charges, quantities, or whether a sword is intelligent, on the
treasure stream, with instantiate_magic_item. A
construction_trick is one of the OSE SRD's odd architectural features, like a room that rotates
or a passage that is an illusion. The party finds one with a
Search for construction, and you describe what it does.
osrlib does nothing with a custom feature.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
str
|
The feature's id, unique across its level. |
kind |
Literal['treasure_cache', 'construction_trick', 'custom']
|
Which sort of feature it is. |
description |
str
|
Text describing the feature. |
cell |
Position | None
|
The cell it is on, or |
item_ids |
tuple[str, ...]
|
Ordinary items in a cache. |
magic_item_ids |
tuple[str, ...]
|
Magic items in a cache. |
coins |
Coins
|
Coins in a cache. |
valuables |
tuple[ValuableSpec, ...]
|
Named gems and jewellery in a cache. |
trap |
TrapSpec | None
|
A treasure trap guarding the cache. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
from osrlib.core.items import Coins
from osrlib.crawl.dungeon import FeatureSpec
chest = FeatureSpec(
id="altar_chest",
kind="treasure_cache",
description="A banded chest under the altar.",
cell=(3, 0),
item_ids=("rope_50", "holy_water"),
coins=Coins(gp=120),
)
print(chest.coins.gp, chest.item_ids)
# 120 ('rope_50', 'holy_water')
id
instance-attribute
id: str
The feature's id. It has to be unique across the level, counting the features on the level
and on all its areas together. You pass it to TakeTreasure
and the other feature commands. The id "pile" is reserved for the drop pile on a cell, and
validate_adventure reports a feature that uses
it.
kind
instance-attribute
kind: Literal['treasure_cache', 'construction_trick', 'custom']
What kind of feature this is. osrlib runs "treasure_cache" for the party. You decide what
"construction_trick" and "custom" do.
description
class-attribute
instance-attribute
description: str = ''
Text to show when the party finds the feature. Events contain the feature's id, not its text, so look the text up here.
cell
class-attribute
instance-attribute
cell: Position | None = None
The cell the feature is on. A feature listed on a level needs one. A feature listed on an area
can leave it None, and then the party can reach it from any cell of the area. When you set it
on an area's feature, it has to be one of the area's cells, and
validate_adventure reports one that isn't.
item_ids
class-attribute
instance-attribute
Ordinary items in the cache, by template id, one item for each id. Use an id from
load_equipment(), listed in
the equipment id index,
or the id of an item in the adventure's items.
magic_item_ids
class-attribute
instance-attribute
Magic items in the cache, by template id. Use an id from
load_magic_items(), listed in
the magic item id index.
You can't bundle magic items in an adventure, so only built-in ids work here.
coins
class-attribute
instance-attribute
Coins in the cache, by denomination.
valuables
class-attribute
instance-attribute
valuables: tuple[ValuableSpec, ...] = ()
Named gems and jewellery in the cache. See
ValuableSpec.
trap
class-attribute
instance-attribute
trap: TrapSpec | None = None
A trap guarding the cache, or None. It has to be a treasure trap, which can spring when the
party opens the cache. A thief finds it with
InspectTreasure and takes it out with
RemoveTreasureTrap. Each character gets one try at
each. A failed removal springs the trap, unless
Ruleset.failed_trap_removal_springs is off.
GeneratedCache
Bases: BaseModel
Treasure the session rolled and put down in the dungeon, recorded in the overlay.
A cache you write is a FeatureSpec, and it never changes.
This is the other kind: treasure the session rolled for a keyed encounter's lair hoard or for an
AreaTreasureSpec. The session puts it in
DungeonState.generated_caches under a new
id like "cache-0001", and reports the id in a
HoardGeneratedEvent. When the party takes it with
TakeTreasure and that id, the session removes the cache.
Whatever the party can't carry goes into a DropPile on the
same cell.
The session never traps treasure it rolls, so the only trapped treasure is treasure you write.
That choice is one of the entries in
the adaptations register, the page that
lists where osrlib picks one reading of an unclear rule or sets a default behind a
Ruleset option.
Attributes:
| Name | Type | Description |
|---|---|---|
cell_ref |
str
|
The cell the cache is on. |
treasure_types |
tuple[str, ...]
|
The tables the treasure was rolled on. |
coins |
Coins
|
The coins in it. |
valuables |
list[ValuableInstance]
|
The gems and jewellery in it. |
magic_items |
list[MagicItemInstance]
|
The magic items in it. |
cell_ref
instance-attribute
cell_ref: str
The cell the cache is on, as a cell_ref string. A lair
hoard is on the first cell in its area's cells. An area's rolled treasure is on the cell where
the party entered the area. The party has to stand on this cell to take the cache.
treasure_types
class-attribute
instance-attribute
The tables the treasure was rolled on, for display and for a referee who wants to see them.
For treasure type letters, it contains the letters, like ("C",). For unguarded treasure, it is
("unguarded",). For a lair hoard that is only a fixed number of gold pieces, it is empty.
coins
class-attribute
instance-attribute
The coins in the cache, by denomination.
valuables
class-attribute
instance-attribute
valuables: list[ValuableInstance] = []
The gems and jewellery in the cache, each with an id.
magic_items
class-attribute
instance-attribute
magic_items: list[MagicItemInstance] = []
The magic items in the cache, each an instance with its charges or quantity already rolled.
KeyedEncounter
Bases: BaseModel
The monsters waiting in a keyed area, and what you decide about them in advance.
Put one on an AreaSpec. The monsters spawn when the party
enters any cell of the area, and the session opens an encounter. The session rolls surprise,
distance, and reaction, though you can set the reaction here, and stop the monsters from being
surprised. When the encounter ends with every monster slain or routed, the area is clear, and no
monsters spawn when the party enters it again.
Attributes:
| Name | Type | Description |
|---|---|---|
monsters |
tuple[KeyedMonster, ...]
|
The monster lines, each a template and a count. |
alignment |
Alignment | None
|
A fixed alignment for monsters that can have more than one. |
aware |
bool
|
Whether the monsters expect the party. |
stance |
ReactionResult | None
|
A fixed reaction, instead of a reaction roll. |
hoard |
bool
|
Whether the monsters have their lair treasure. |
Examples:
from osrlib.core.tables import ReactionResult
from osrlib.crawl.dungeon import KeyedEncounter, KeyedMonster
ambush = KeyedEncounter(
monsters=(KeyedMonster(template_id="goblin", count_fixed=6),),
aware=True,
stance=ReactionResult.ATTACKS,
)
print(ambush.aware, ambush.hoard)
# True True
monsters
class-attribute
instance-attribute
monsters: tuple[KeyedMonster, ...] = Field(min_length=1)
The monster lines in the encounter, at least one. See
KeyedMonster.
alignment
class-attribute
instance-attribute
alignment: Alignment | None = None
The alignment every spawned monster takes, for a template that allows more than one. With
None, the default, the session rolls it as usual. It has to be an alignment that each line's template allows, and
validate_adventure reports one that isn't.
aware
class-attribute
instance-attribute
aware: bool = False
Whether the monsters expect the party. Aware monsters can't be surprised, so set it for a lookout, or for an ambush that has heard the party coming.
stance
class-attribute
instance-attribute
stance: ReactionResult | None = None
The monsters' reaction, used instead of a reaction roll. Set it for monsters that always
attack on sight, or that are always friendly. Leave it None, the default, to roll the reaction
as usual.
hoard
class-attribute
instance-attribute
hoard: bool = True
Whether the monsters have their lair treasure. With the default, True, the session rolls the
treasure types in each monster's treasure the first time the monsters spawn. It puts the result
on the first cell of the area as a GeneratedCache. If the
party leaves and comes back before the area is clear, the monsters spawn again, but the session
doesn't roll the hoard again. Set it False for a monster room with no treasure. Stocking a
dungeon by the B/X rules often produces such a room, because only some monster rooms get treasure
on the stocking roll.
KeyedMonster
Bases: BaseModel
One line of a keyed encounter: which monster, and how many.
A KeyedEncounter has a tuple of these, so a room with
four orcs and their ogre bodyguard has two lines. Give each line either a fixed count or count
dice, not both.
Attributes:
| Name | Type | Description |
|---|---|---|
template_id |
str
|
Which monster. |
count_dice |
str | None
|
How many, rolled when they spawn. |
count_fixed |
int | None
|
How many, as a fixed number. |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If |
ValueError
|
If both |
Examples:
from osrlib.crawl.dungeon import KeyedEncounter, KeyedMonster
guards = KeyedEncounter(monsters=(KeyedMonster(template_id="goblin", count_fixed=4),))
print(guards.monsters[0].template_id, guards.monsters[0].count_fixed)
# goblin 4
template_id
instance-attribute
template_id: str
The monster's template id. Use an id from load_monsters(),
listed in the monster id index,
or the id of a monster in the adventure's monsters.
count_dice
class-attribute
instance-attribute
count_dice: str | None = None
How many appear, as a dice expression like "2d4". The session rolls it on the
WANDERING_STREAM when the monsters spawn, and a roll
below 1 counts as 1. Set this or count_fixed, not both. The model checks the expression when
you construct it, so a malformed one fails then, not during play.
count_fixed
class-attribute
instance-attribute
count_fixed: int | None = None
How many appear, as a fixed number. Set this or count_dice, not both. A printed adventure
usually gives a fixed number, and so does stock_area when
it rolls a room for you.
LevelSpec
Bases: BaseModel
One dungeon level: a grid of 10-foot cells with its edges, rooms, and stairs.
You give a level a size, declare the edges that aren't walls, key some of its cells as areas, and add features and
transitions. Then you put one or more levels in a DungeonSpec, and the dungeon
in an Adventure.
Its methods return what the session looks up about a level: whether a cell is on the grid, what stands on one side of it, which area it belongs to, and whether a transition stands on it. Call them to draw a map, or to check a level while you write it.
Attributes:
| Name | Type | Description |
|---|---|---|
number |
int
|
The level's number. Level 1 is the top level, and deeper levels have higher numbers. |
width |
int
|
The grid's width in cells. |
height |
int
|
The grid's height in cells. |
edges |
Annotated[Mapping[str, Edge], FrozenMap]
|
Every edge that isn't a wall. |
areas |
tuple[AreaSpec, ...]
|
The keyed rooms. |
features |
tuple[FeatureSpec, ...]
|
Features on the level, outside any room. |
transitions |
tuple[TransitionSpec, ...]
|
The stairs, trapdoors, chutes, and passages. |
wandering |
WanderingSpec
|
The wandering-monster check. |
entrance |
Position | None
|
Where the party arrives from town. |
guidance |
str
|
Instructions for a narrator that uses a language model. |
Examples:
from osrlib.crawl.dungeon import Direction, Edge, EdgeKind, LevelSpec
# 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)},
)
print(corridor.edge((0, 0), Direction.EAST).kind)
# open
print(corridor.edge((0, 0), Direction.NORTH).kind)
# wall
number
class-attribute
instance-attribute
The level's number, 1 or more, where level 1 is the top. The session uses it to select the
built-in wandering-monster table and the row of the unguarded-treasure table. The numbers have to
be unique within a dungeon, and a TransitionSpec refers
to the level it leads to by its number.
width
class-attribute
instance-attribute
How many cells wide the grid is, west to east. x runs from 0 to width - 1.
height
class-attribute
instance-attribute
How many cells tall the grid is, north to south. y runs from 0 to height - 1.
edges
class-attribute
instance-attribute
Every edge on the grid that isn't a wall, as an Edge. Write
each key with edge_key, like "1,0:west", and only for an
edge between two cells on the grid. validate_adventure
reports a key that isn't the edge_key of a side of a cell on the grid, like "0,0:east" in place
of "1,0:west". An edge with no entry is a wall, and so is the level's boundary, so an empty
map is a level of solid rock. Read an edge with
edge instead of indexing the map, because it works out
the key and returns a wall for an edge with no entry.
You pass a dict, and the level stores a read-only FrozenMap of
it, because every session started from the adventure reads the same level. To change an edge,
build a new level from a changed copy of the map:
LevelSpec.model_validate({**level.model_dump(), "edges": edges}), where edges is
dict(level.edges) with your changes.
areas
class-attribute
instance-attribute
The level's keyed rooms and caves. Cells outside every area are corridor. Area ids have to be unique within the level, and every cell an area lists has to be on the grid.
features
class-attribute
instance-attribute
features: tuple[FeatureSpec, ...] = ()
Features outside any room, like a cache in a corridor or a trick in a dead end. Each one needs
a cell, because there is no area to bind it to. Their ids have to be unique together with the
ids of the areas' features.
transitions
class-attribute
instance-attribute
transitions: tuple[TransitionSpec, ...] = ()
The stairs, trapdoors, chutes, and passages on this level, each on one cell. A transition belongs to the level, not to an area, even when it stands inside a room.
wandering
class-attribute
instance-attribute
wandering: WanderingSpec = WanderingSpec()
The level's wandering-monster check. The default is the B/X rule: a 1-in-6 chance every two turns, on the built-in table for this level's number.
entrance
class-attribute
instance-attribute
entrance: Position | None = None
The cell the party arrives at from town, or None for a level with no way in from outside.
EnterDungeon puts the party here facing north, whatever
is around the cell. The session refuses TravelToTown
unless the party stands on its level's entrance. One level of every dungeon needs an entrance, and
validate_adventure reports a dungeon without
one.
guidance
class-attribute
instance-attribute
guidance: str = ''
Instructions for a narrator that uses a language model, while the party is on this level: the mood of the place, what to say about it, and what never to say.
osrlib never reads it, no event includes it, and no rule depends on it. To use it, read it from the adventure document. The player view doesn't include it, so treat it like an area's description, and don't show it to a player as written.
in_bounds
Return whether a cell is on this level's grid.
Everything off the grid is solid rock: the party can't walk there, and an authored position
off the grid is an error that validate_adventure
reports.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
position
|
Position
|
The cell to test. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True when |
Examples:
edge
Return what stands on one side of a cell.
Use it instead of indexing edges yourself. It works out the key, so a cell's east side and
its neighbour's west side give the same answer, and it returns a wall for an edge with no
entry. Call it to find out whether the party can walk that way and whether a door stands
there. To read the door's state in play, pass the same cell and direction to
edge_ref.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
position
|
Position
|
The cell. |
required |
direction
|
Direction
|
Which of the cell's four edges. |
required |
Returns:
| Type | Description |
|---|---|
Edge
|
The edge from |
area_at
Return the keyed area that covers a cell, or None for corridor.
The session calls it on every step to find out whether the party has walked into an area. Call it to name the room the party is in, or to show which room a cell belongs to on a map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
position
|
Position
|
The cell. |
required |
Returns:
| Type | Description |
|---|---|
AreaSpec | None
|
The area the cell belongs to, or |
Examples:
transition_at
transition_at(position: Position) -> TransitionSpec | None
Return the stairs, trapdoor, or chute on a cell, or None.
The session refuses UseStairs on a cell where this
returns None.
That is what makes a chute one way: no transition stands on the arrival cell. Call it to draw
stairs on a map, or to offer UseStairs only where it works. It never returns a passage,
because the party walks through a passage with
MoveParty. Call
passage_at to find one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
position
|
Position
|
The cell. |
required |
Returns:
| Type | Description |
|---|---|
TransitionSpec | None
|
The first transition in |
Examples:
from osrlib.crawl.dungeon import Direction, LevelSpec, TransitionSpec
stairs = TransitionSpec(
kind="stairs_down",
position=(0, 0),
to_dungeon_id="crypt",
to_level_number=2,
to_position=(0, 0),
to_facing=Direction.SOUTH,
)
top = LevelSpec(number=1, width=1, height=1, entrance=(0, 0), transitions=(stairs,))
found = top.transition_at((0, 0))
print(found.kind, found.to_level_number)
# stairs_down 2
passage_at
passage_at(position: Position, side: Direction) -> TransitionSpec | None
Return the passage on one side of a cell, or None.
A MoveParty across a passage's side moves the party to
the passage's destination instead of stopping at the wall. Call it to find out whether a move
from a cell crosses a passage, or to draw a passage on a map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
position
|
Position
|
The cell. |
required |
side
|
Direction
|
Which of the cell's four sides. |
required |
Returns:
| Type | Description |
|---|---|
TransitionSpec | None
|
The first passage in |
PartyLocation
Bases: BaseModel
Where the party is: in the base town, or on a dungeon cell facing a direction.
The session keeps one in DungeonState.location
and replaces it as the party moves. Read it to draw the map and to know whether the party is in
town or in a dungeon. Don't change it yourself: to move the party by the referee's decision,
execute PlaceParty, which takes one of these.
A town location has none of the dungeon fields, and a dungeon location has all four.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
Literal['town', 'dungeon']
|
Whether the party is in town or in a dungeon. |
dungeon_id |
str | None
|
The dungeon the party is in. |
level_number |
int | None
|
The level the party is on. |
position |
Position | None
|
The cell the party stands on. |
facing |
Direction | None
|
The direction the party faces. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
from osrlib.crawl.dungeon import Direction, PartyLocation
here = PartyLocation(kind="dungeon", dungeon_id="crypt", level_number=1, position=(0, 0), facing=Direction.EAST)
print(here.position, here.facing)
# (0, 0) east
kind
instance-attribute
kind: Literal['town', 'dungeon']
"town" when the party is in the base town, or "dungeon" when it stands on a dungeon cell.
A new session starts in town.
dungeon_id
class-attribute
instance-attribute
dungeon_id: str | None = None
The id of the dungeon the party is in, and None in town.
level_number
class-attribute
instance-attribute
level_number: int | None = None
The number of the level the party is on, and None in town.
position
class-attribute
instance-attribute
position: Position | None = None
The cell the party stands on, and None in town.
TransitionSpec
Bases: BaseModel
A way from one cell to another: stairs, a trapdoor, a chute, or a passage.
Transitions belong to a level, in
LevelSpec.transitions, not to an area. They join
the levels of a dungeon, and they join two dungeons when one points at the other's id. Each
transition stands on a cell and moves the party to to_position, facing to_facing.
validate_adventure checks that the cell it stands on
and the cell it leads to are both on their levels' grids.
The party takes stairs, a trapdoor, or a chute with
UseStairs. The party walks through a passage instead. A
passage stands on one side of its cell, and a MoveParty
from that cell in that direction moves the party to the passage's destination. That side of the
cell is a wall in the level's edges. The cell one step across the wall is the passage's far
cell, which has walls on every side and belongs to no area. Use a passage where a map shows two
cells side by side that the adventure can't put side by side, like the floors of two levels that
meet, or two halves of one map that you lay out apart.
A transition leads one way only, and osrlib doesn't add the way back. Stairs the party can climb
back up are two transitions, one on each level, each pointing at the other. Leave out the second
one and you have a chute: the session refuses UseStairs
at the bottom, because no transition stands on the arrival cell. A passage's way back is a second
passage. It stands on the first passage's destination cell, on the side opposite the first
passage's to_facing. Its destination is the first passage's cell, and its to_facing is
opposite the first passage's side.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
Literal['stairs_up', 'stairs_down', 'trapdoor', 'chute', 'passage']
|
Which kind of connection this is. |
position |
Position
|
The cell it stands on. |
side |
Direction | None
|
The side of that cell a passage stands on, for a passage only. |
to_dungeon_id |
str
|
The dungeon the party arrives in. |
to_level_number |
int
|
The level the party arrives on. |
to_position |
Position
|
The cell the party arrives at. |
to_facing |
Direction
|
The direction the party faces on arrival. |
requires |
GateSpec | None
|
A condition the party has to meet to take it. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
Stairs between two levels, one transition on each level:
from osrlib.crawl.adventure import Adventure, TownSpec, validate_adventure
from osrlib.crawl.dungeon import Direction, DungeonSpec, LevelSpec, TransitionSpec
from osrlib.data import load_equipment, load_monsters
down = TransitionSpec(
kind="stairs_down",
position=(0, 0),
to_dungeon_id="crypt",
to_level_number=2,
to_position=(1, 1),
to_facing=Direction.SOUTH,
)
up = TransitionSpec(
kind="stairs_up",
position=(1, 1),
to_dungeon_id="crypt",
to_level_number=1,
to_position=(0, 0),
to_facing=Direction.NORTH,
)
top = LevelSpec(number=1, width=1, height=1, entrance=(0, 0), transitions=(down,))
bottom = LevelSpec(number=2, width=2, height=2, transitions=(up,))
crypt = DungeonSpec(id="crypt", levels=(top, bottom))
adventure = Adventure(name="A First Delve", town=TownSpec(name="Threshold"), dungeons=(crypt,))
validate_adventure(adventure, load_monsters(), load_equipment())
print(crypt.level(2).transition_at((1, 1)).to_level_number)
# 1
kind
instance-attribute
kind: Literal['stairs_up', 'stairs_down', 'trapdoor', 'chute', 'passage']
What the party sees and uses: "stairs_up", "stairs_down", "trapdoor", "chute", or
"passage". The first four kinds all work the same way: the party takes them with
UseStairs, the destination fields set where it goes, and the
session reports the kind on the arrival event, so you can describe it. The party crosses a
"passage" by walking across its side instead.
position
instance-attribute
position: Position
The cell on this level where the transition stands. The party has to stand here to use it
with UseStairs or to cross it as a passage.
side
class-attribute
instance-attribute
side: Direction | None = None
The side of position that a passage stands on, and None for every other kind. A
MoveParty from position in this direction crosses the
passage. A passage without a side raises ValueError when you construct it, and so does a
transition of any other kind with one.
to_dungeon_id
instance-attribute
to_dungeon_id: str
The id of the dungeon the party arrives in. It is usually the dungeon this level is in. Set it to another dungeon of the adventure to join the two.
to_level_number
class-attribute
instance-attribute
The number of the level the party arrives on, 1 or more.
to_position
instance-attribute
to_position: Position
The cell the party arrives at, on the destination level's grid.
to_facing
instance-attribute
to_facing: Direction
The direction the party faces on arrival. Draw the party's view facing this way.
requires
class-attribute
instance-attribute
requires: GateSpec | None = None
A gate on taking the transition, or None for one with no gate.
UseStairs, or MoveParty
for a passage, checks the gate after the command's other checks and before the party moves. A
gate that takes an item takes it then, as the party crosses. When the party changes level or
dungeon, the gate's success text goes on the arrival's
LocationEnteredEvent. For a transition to another
cell of the same level, it goes on the PartyMovedEvent
for the landing cell.
A transition in a TrapEffect can't have a gate, because a
trap moves the party by force and the party attempts nothing. TrapEffect raises ValueError
for one that does.
TrapEffect
Bases: BaseModel
What a trap does when it springs.
Put one in the effect of a TrapSpec, which sets when the
trap springs and whom it hits. The fields combine: a dart trap deals damage, a pit deals falling
damage and can add a condition, and a gas trap calls for a saving throw and kills on a failure.
For a trap that your own code resolves, leave the other fields unset and describe the trap in
manual.
The session rolls a trap's damage, saves, and falls on its exploration stream. It makes no attack roll for a trap, so the damage always applies unless a save reduces it.
A passed save always spares the victim from kills and from condition, whatever the save's
on_save is, because B/X has no half death or half blindness. on_save affects only
the damage: "negates" spares the victim from all of it, and "half" halves it.
Attributes:
| Name | Type | Description |
|---|---|---|
damage_dice |
str | None
|
The damage the trap deals. |
volley_dice |
str | None
|
The number of projectiles, for a trap that fires several. |
save |
SaveSpec | None
|
The saving throw the victim rolls. |
kills |
bool
|
Whether the trap kills a victim who fails the save. |
condition |
Condition | None
|
A condition a failed save inflicts. |
condition_duration_dice |
str | None
|
The condition's duration, rolled. |
condition_duration_amount |
int | None
|
The condition's duration, fixed. |
condition_duration_unit |
TimeUnit | None
|
The unit the duration counts in. |
fall_feet |
int | None
|
How far the victim falls. |
transition |
TransitionSpec | None
|
Where the trap moves the party. |
manual |
str | None
|
A description of a trap your own code resolves. |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If |
ValueError
|
If a duration field is set without a |
Examples:
from osrlib.core.combat import SaveCategory
from osrlib.core.spells import SaveSpec
from osrlib.crawl.dungeon import TrapEffect
# A dart trap: 1d6 darts, each for 1d4.
darts = TrapEffect(damage_dice="1d4", volley_dice="1d6", save=SaveSpec(category=SaveCategory.WANDS))
print(darts.kills)
# False
damage_dice
class-attribute
instance-attribute
damage_dice: str | None = None
The damage the trap deals, as a dice expression like "1d6", or None for a trap that deals
none. With volley_dice set, it is the damage of each projectile. The model checks the
expression when you construct it, so a malformed one fails then, not when the trap springs.
volley_dice
class-attribute
instance-attribute
volley_dice: str | None = None
How many projectiles the trap fires, as a dice expression, or None for a trap that fires one
or none. Use it for a dart trap: volley_dice="1d6" with damage_dice="1d4" fires 1d6 darts
and rolls 1d4 damage for each. There's no dice expression for "roll this many times that much",
so a volley uses two fields. Set it only with damage_dice.
save
class-attribute
instance-attribute
save: SaveSpec | None = None
The saving throw the victim rolls, or None for a trap that allows none. Its category is the
saving throw to roll, and its on_save sets what a passed save does to the damage:
"negates" spares the victim from all of it, and "half" halves both the damage_dice damage
and the falling damage, rounding down. A passed save always spares the victim from kills and
condition.
kills
class-attribute
instance-attribute
kills: bool = False
Whether the trap kills a victim who fails the save, like a poison gas trap. A victim who
passes the save survives, whatever on_save is. With no save, the trap kills every victim.
condition
class-attribute
instance-attribute
condition: Condition | None = None
A condition the trap gives a victim who fails the save, like blindness, or None. A victim who
passes the save doesn't get it. With no save, every victim gets it.
condition_duration_dice
class-attribute
instance-attribute
condition_duration_dice: str | None = None
The condition's duration as a dice expression, for a duration that varies. Set this or
condition_duration_amount, not both, together with condition_duration_unit and a condition.
The session rolls it on the effects stream when the condition takes hold.
condition_duration_amount
class-attribute
instance-attribute
condition_duration_amount: int | None = None
The condition's duration as a fixed number, for a duration that doesn't vary. Set this or
condition_duration_dice, not both, together with condition_duration_unit and a
condition.
condition_duration_unit
class-attribute
instance-attribute
condition_duration_unit: TimeUnit | None = None
The unit the duration counts in: rounds, turns, or days. Set it together with
condition_duration_dice or condition_duration_amount. Leave the three duration fields unset
for a condition that lasts until something removes it. The model raises ValueError when you
construct it with a unit and no length, or a length and no unit.
fall_feet
class-attribute
instance-attribute
fall_feet: int | None = None
How far the victim falls, in feet, or None for a trap with no fall, like a pit's depth. The
fall deals 1d6 damage for each full 10 feet, the OSE SRD's falling rule, as
falling_damage rolls it. That damage is separate from
damage_dice, and a "half" save halves it too.
transition
class-attribute
instance-attribute
transition: TransitionSpec | None = None
Where the trap moves the party, or None for a trap that moves no one. Use it for a chute
that slides the party to another cell or level. The party has one location, so the trap moves
the whole party or no one. With a save, it moves the party when at least one victim fails
the save, and leaves the party on the trapped cell when every victim passes. With no save,
it always moves the party. The transition can't have a requires gate, because the party
doesn't choose to take it. validate_adventure
checks it as it checks a level's transitions: it has to stand on the grid of the trap's level and
lead to a cell on the grid of a level that exists. It also reports a transition whose kind is
"passage".
manual
class-attribute
instance-attribute
manual: str | None = None
A description of a trap your own code resolves, or None. osrlib never reads it. Use it for a
trap whose effect is the referee's call rather than a die roll.
TrapSpec
Bases: BaseModel
A trap: when it springs, what it does, and whom it hits.
A trap can be in two places, and its kind sets which. A room trap goes on an
AreaSpec and covers the whole area. A treasure trap goes on a
FeatureSpec and guards that one cache. Each of the two
models accepts only one kind of trap.
A trap doesn't always spring. Each time the party does the thing that springs it, the session
rolls a d6, and the trap springs on a 1 or 2, the OSE SRD's 2-in-6 rule. A trap that has sprung
never springs again. The party can find a trap before it springs: a room trap with a
Search for room traps, and a treasure trap with a thief's
InspectTreasure. A room trap that the party has found
no longer springs, so the party walks around it. For a treasure trap that the party has found,
the session still rolls when the party opens the cache, until a thief takes it out with
RemoveTreasureTrap. There is no way to disarm a room
trap.
The traps you write are the only traps in the game. Treasure the session rolls is never trapped.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
Literal['room', 'treasure']
|
Whether this is a room trap or a treasure trap. |
trigger |
Literal['enter', 'open']
|
The action that springs it. |
effect |
TrapEffect
|
What it does when it springs. |
affects |
Literal['triggerer', 'party']
|
Whom it hits. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
from osrlib.core.combat import SaveCategory
from osrlib.core.spells import SaveSpec
from osrlib.crawl.dungeon import AreaSpec, FeatureSpec, TrapEffect, TrapSpec
# Poison gas fills the room when the party walks in: every member saves or dies.
gas = TrapSpec(
kind="room",
trigger="enter",
affects="party",
effect=TrapEffect(kills=True, save=SaveSpec(category=SaveCategory.DEATH)),
)
tomb = AreaSpec(id="tomb", cells=((2, 0),), trap=gas)
# A poisoned needle in the lock of a chest.
needle = TrapSpec(kind="treasure", trigger="open", effect=TrapEffect(damage_dice="1d4"))
chest = FeatureSpec(id="chest", kind="treasure_cache", trap=needle)
try:
AreaSpec(id="vault", cells=((3, 0),), trap=needle)
except ValueError as error:
print("non-room trap" in str(error))
# True
kind
instance-attribute
kind: Literal['room', 'treasure']
"room" for a trap over an area, or "treasure" for a trap on a cache.
AreaSpec accepts only room traps, and
FeatureSpec accepts only treasure traps.
trigger
instance-attribute
trigger: Literal['enter', 'open']
The action that springs the trap.
"enter": the party moves into a cell of the trapped area. The session rolls for the trap on every move into one of its cells, including moves within the area, until it springs or the party finds it."open"on a room trap: the party opens or forces a door on an edge of one of the area's cells, from either side, like a blade that drops when the door swings."open"on a treasure trap: the party opens the cache withTakeTreasure.
A treasure trap has to use "open", because there is nothing to walk into on a cache.
affects
class-attribute
instance-attribute
affects: Literal['triggerer', 'party'] = 'triggerer'
Whom the effect hits. "party" hits every living member, like poison gas filling a room.
"triggerer", the default, hits one character: the member named in the
ForceDoor or TakeTreasure
that sprang it, the thief whose RemoveTreasureTrap
failed, or otherwise the first living member in marching order.
TreasureBundle
Bases: BaseModel
Rolled treasure grouped as one lot: coins, valuables, and magic items.
When the session spawns monsters, it rolls the treasure they carry into bundles. You find them
on an EncounterGroup: member_treasure contains what
each monster carries, and group_treasure contains what the group shares. When the encounter ends,
the bundles of slain monsters drop onto the party's cell as a
DropPile. The descriptions of those two fields give the rules
for which bundles drop. The session also uses a bundle while it rolls a hoard, then moves the
contents into a GeneratedCache.
Unlike the authored models in this module, a bundle is mutable, because the session adds to it one entry at a time as it rolls treasure.
Attributes:
| Name | Type | Description |
|---|---|---|
coins |
Coins
|
The coins in the bundle. |
valuables |
list[ValuableInstance]
|
The gems and jewellery in the bundle. |
magic_items |
list[MagicItemInstance]
|
The magic items in the bundle. |
coins
class-attribute
instance-attribute
The coins, by denomination. A new bundle has none.
valuables
class-attribute
instance-attribute
valuables: list[ValuableInstance] = []
The gems and jewellery, each an instance with an id and a value.
magic_items
class-attribute
instance-attribute
magic_items: list[MagicItemInstance] = []
The magic items, each an instance with its charges or quantity already rolled.
empty
property
empty: bool
Whether the bundle has no coins, valuables, or magic items.
The session can roll nothing at all for a hoard. It checks this before it puts a cache down, so it never puts down an empty one.
ValuableSpec
Bases: BaseModel
A gem or piece of jewellery that you place in a cache by hand.
Use it when the treasure is a particular thing with a name, not one of the gems the session
rolls on the treasure tables. Put it in the valuables of a FeatureSpec.
When the party empties the cache with TakeTreasure, the
session turns it into a ValuableInstance with an id.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
Literal['gem', 'jewellery']
|
Whether it is a gem or jewellery. |
name |
str
|
The name the party sees. |
value_gp |
int
|
What it is worth, in gold pieces. |
weight_coins |
int
|
What it weighs, in coins. |
Examples:
from osrlib.crawl.dungeon import FeatureSpec, ValuableSpec
chest = FeatureSpec(
id="abbot_chest",
kind="treasure_cache",
valuables=(ValuableSpec(kind="jewellery", name="The abbot's seal ring", value_gp=900),),
)
print(chest.valuables[0].value_gp)
# 900
kind
instance-attribute
kind: Literal['gem', 'jewellery']
Whether the valuable is a gem or jewellery. No rule in osrlib depends on it. Use it for display, and for any rule you apply to one kind and not the other.
name
class-attribute
instance-attribute
name: str = ''
The name the party sees, like "The abbot's seal ring". Leave it empty for an unnamed
valuable, like the ones the session rolls on the treasure tables.
value_gp
class-attribute
instance-attribute
What the valuable is worth in gold pieces. It sells for this much in town, and it is worth this much experience to the party.
WanderingSpec
Bases: BaseModel
A level's wandering-monster check: how often the session rolls it, and on what table.
Every LevelSpec has one. The default is the B/X rule, so you
write your own only to change the chance or the monsters. The session runs the check as the
party spends turns on the level. You don't roll it yourself.
Attributes:
| Name | Type | Description |
|---|---|---|
chance_in_six |
int
|
The base chance of monsters, in six. |
interval_turns |
int
|
How many turns pass between checks. |
table |
EncounterTable | None
|
An encounter table of your own for this level. |
Examples:
from osrlib.crawl.dungeon import WanderingSpec
quiet = WanderingSpec(chance_in_six=0)
print(quiet.interval_turns)
# 2
chance_in_six
class-attribute
instance-attribute
The base chance, in six, that each check brings monsters. The default, 1, is the B/X rule. The
session adjusts it for each check, within 0 to 6. Noise since the last check adds 1, and light as
bright as daylight adds 1. A rest with hidden set, where
the party hides while it rests, subtracts 1. With 0, a level has wandering monsters only after
noise or under bright light. Set it higher for a busier level.
interval_turns
class-attribute
instance-attribute
How many exploration turns pass between checks. The default, 2, is the B/X rule.
table
class-attribute
instance-attribute
table: EncounterTable | None = None
An encounter table of your own for this level, or None to use the built-in table for the
level's number. Your table replaces the built-in one completely, so use it to give a level
different monsters. It has the same rows as the built-in tables from
load_encounter_tables, and
stock_area can roll on it too.
cell_ref
Return the string that identifies one cell in a whole adventure.
A key in a level's edges map locates a cell within one level. A cell reference also includes
the dungeon and the level, so it locates the cell anywhere in the adventure.
DungeonState.piles is keyed by it, and an
ActiveEffect.target_ref in this form puts an
effect on a dungeon cell instead of on a creature.
The format is "cell:{dungeon}:{level}:{x},{y}", like "cell:crypt:1:2,3".
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dungeon_id
|
str
|
The dungeon's id, as on its |
required |
level_number
|
int
|
The level's 1-based number. |
required |
position
|
Position
|
The cell. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The cell reference. |
Examples:
edge_key
Return the key for the edge on direction's side of position, for a level's edges map.
Use it to write every key of a LevelSpec.edges map, so
you don't have to work out which of the two cells to name an edge from. Every edge has exactly
one key: a cell and its north or west side. A cell's south edge is the north edge of the cell
below it, and its east edge is the west edge of the cell to its right. So
edge_key((0, 0), Direction.EAST) and edge_key((1, 0), Direction.WEST) return the same string.
The format is "{x},{y}:{side}", like "1,0:west". That is what a serialized adventure
shows, and what LevelSpec.edge looks up for you.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
position
|
Position
|
The cell. |
required |
direction
|
Direction
|
Which of the cell's four edges. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The edge's key. It isn't checked against any level, so a cell off the grid gets a key in the same format. |
Examples:
edge_ref
Return the string that identifies one edge in a whole adventure.
DungeonState.doors is keyed by it, so it is how you
look up a door's open, wedged, discovered, and unlocked flags from a cell and a direction. The
reference ends with the edge's edge_key, so you get the same
reference from either side of a door, and the door has one state. Pass the result to
DungeonState.door.
The format is "{dungeon}:{level}:{x},{y}:{side}", like "crypt:1:1,0:west".
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dungeon_id
|
str
|
The dungeon's id. |
required |
level_number
|
int
|
The level's 1-based number. |
required |
position
|
Position
|
The cell. |
required |
direction
|
Direction
|
Which of the cell's four edges. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The edge reference. |
Examples:
step
Return the cell one step from position in direction.
It only adds the direction's vector to the position. It doesn't check walls, levels, or the
party. Call LevelSpec.in_bounds to find out whether
the result is on the grid, and LevelSpec.edge to find
out whether the party could walk there. Use it to lay out a corridor cell by cell while you
write a level, or to find the cell the party would move into.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
position
|
Position
|
The starting cell. |
required |
direction
|
Direction
|
The direction to step. |
required |
Returns:
| Type | Description |
|---|---|
Position
|
The neighbouring cell. It can be off the level's grid. |
Examples: