osrlib.crawl.exploration
The rules behind the exploring and town commands, and the per-turn checks for fatigue, food, and wandering monsters.
A party gives these commands while it explores a dungeon, in exploring mode, or visits town, in
town mode: moving, doors, searching, traps, treasure, items, light, rest, spells, shopping, and
temple healing.
DropItems and UseItem also
work in encounter mode, so the party can drop or use gear while monsters stand in front of it.
The command handlers are private, so you don't call one yourself. Build one of the command models in
osrlib.crawl.commands, like MoveParty,
Search, or Rest, and pass it to
GameSession.execute. The session returns a
CommandResult. It contains either
Rejection models that give the reason the session refused the
command, or the event models of osrlib.crawl.events that record what happened. The
session checks a command before it runs any of it, so for a refused command it rolls no dice,
changes no state, and spends no game time.
The public functions here are the checks the session runs as time passes, rather than in answer to a command:
exploration_ratetakes the session and returns the party's movement rate in feet per turn.wandering_intervaltakes the session and returns how many turns pass between wandering-monster checks on the party's level.check_fatigueattaches the penalty for going too long without rest, and returns its events.consume_provisionsfeeds and waters the party for one day, and returns its events.wandering_checkrolls one wandering-monster check, and returns its events and whether an encounter opened.
GameSession.advance_turns and
GameSession.advance_rounds run the last three
on their schedules, so if you move time by executing commands, you don't call them. Call
exploration_rate and wandering_interval to show the party's numbers on a status display. Call
the other three yourself only when you advance GameSession.clock directly instead of through those
methods, because each one changes the session.
The constants cover what those checks attach and what the temple sells.
FATIGUE_KIND,
EXHAUSTED_KIND, and
DEPRIVATION_KIND are the effect kinds of the
penalties for going without rest, running from a long chase, and going without food or water.
EXHAUSTED_DEFINITION is the exhaustion effect
itself, and HEALING_SERVICES is the temple's
standard price list.
The session counts movement on its odometer,
GameSession.odometer_thirds, in thirds of a
foot. A step into a cell the party hasn't explored costs 30 units, and a step into an explored one
costs 10, which is the SRD's rule that the party crosses familiar ground three times as fast. When
the total reaches three times the party's exploration rate, the clock advances one turn and the
odometer goes back to zero. At the base rate of 120 feet a turn, a turn passes after 12 steps into
unexplored cells, or 36 into explored ones. An action that takes a turn, like a search, advances the
clock a whole turn and sets the odometer back to zero.
The session draws the rolls for a trap from
EXPLORATION_STREAM: the 2-in-6 spring check (a d6 roll
of 1 or 2 springs the trap), the saving throws, the damage, and the number of darts or other
missiles. It rolls the duration of a condition a trap attaches on
EFFECTS_STREAM instead, like every other effect's duration.
Typical usage:
from osrlib.core.abilities import AbilityScore
from osrlib.core.alignment import Alignment
from osrlib.core.character import Character
from osrlib.crawl.adventure import Adventure, TownSpec
from osrlib.crawl.commands import EnterDungeon, MoveParty
from osrlib.crawl.dungeon import Direction, DungeonSpec, Edge, EdgeKind, LevelSpec
from osrlib.crawl.exploration import exploration_rate
from osrlib.crawl.party import Party
from osrlib.crawl.session import GameSession
hero = Character(
name="Hild",
class_id="fighter",
race="human",
level=1,
xp=0,
scores={ability: 12 for ability in AbilityScore},
alignment=Alignment.LAWFUL,
max_hp=8,
current_hp=8,
)
level = LevelSpec(number=1, width=2, height=1, entrance=(0, 0), edges={"1,0:west": Edge(kind=EdgeKind.OPEN)})
adventure = Adventure(
name="A First Delve",
town=TownSpec(name="Threshold"),
dungeons=(DungeonSpec(id="crypt", name="The Old Crypt", levels=(level,)),),
)
session = GameSession.new(Party(members=[hero]), adventure, seed=7)
session.execute(EnterDungeon(dungeon_id="crypt"))
moved = session.execute(MoveParty(direction=Direction.EAST))
assert [event.code for event in moved.events] == ["exploration.party.moved"]
blocked = session.execute(MoveParty(direction=Direction.EAST)) # the level is two cells wide
assert not blocked.accepted
assert blocked.rejections[0].code == "exploration.move.blocked"
print(exploration_rate(session))
# 120
DEPRIVATION_KIND
module-attribute
The effect kind of the penalty for going without food or water.
Query it the same way as FATIGUE_KIND. Nothing attaches
under this kind unless
Ruleset.deprivation_penalties is on, because
the penalties for going hungry or thirsty are optional.
consume_provisions keeps the day counts it depends
on either way, in session.deprivation. The effect applies −1 to attack rolls. It attaches on the
first day a member goes without food or water, and is released on the first day they have both.
EXHAUSTED_DEFINITION
module-attribute
EXHAUSTED_DEFINITION = EffectDefinition(
kind=EXHAUSTED_KIND,
condition=Condition.EXHAUSTED,
stacking="ignore",
modifiers=(
ModifierSpec(kind="attack_bonus", value=-2),
ModifierSpec(kind="damage_bonus", value=-2),
ModifierSpec(kind="attack_penalty_of_attackers", value=2),
),
)
The exhaustion effect: −2 to attack rolls, −2 to damage rolls, and 2 points worse armour class.
The session attaches it to every living member who isn't already exhausted when a chase lasts
PURSUIT_ROUND_CAP rounds and the party gets away, and
three turns of Rest release it. Attach this same definition with
EffectsLedger.attach when your own code exhausts a
member. A second definition of your own would leave a member under two penalties at once. To ask
whether a member is exhausted, query EXHAUSTED_KIND
rather than this object.
The definition grants Condition.EXHAUSTED and stacks as ignore,
so attaching it to a member who is already exhausted does nothing. It has no duration, so it stays
until something releases it: in play, rest does, and time alone doesn't. The worse armour class is
an attack_penalty_of_attackers modifier of +2, so attackers of an exhausted creature get +2 to
hit, which is the same as descending armour class 2 points worse.
EXHAUSTED_KIND
module-attribute
The effect kind of the penalty for running from a long chase.
Query it the same way as FATIGUE_KIND. A party that keeps
running until a chase lasts PURSUIT_ROUND_CAP rounds
gets away and is exhausted, and three turns of Rest clear it.
EXHAUSTED_DEFINITION is the effect attached
under this kind.
FATIGUE_KIND
module-attribute
The effect kind of the penalty for going too long without rest.
Pass it with a member's id to
EffectsLedger.active_on to ask whether that member
is fatigued: session.ledger.active_on(member.id, FATIGUE_KIND) returns the active effects, and an
empty list means the member is rested. Use that query for a status display.
check_fatigue makes the same query before it attaches
anything. The effect applies −1 to attack rolls and −1 to damage rolls and has no duration. In play,
a Rest releases it once the party has rested one full turn, even if a
wandering monster interrupts the rest later.
HEALING_SERVICES
module-attribute
HEALING_SERVICES: Mapping[HealingService, tuple[str, int]] = MappingProxyType(
{
"cure_light_wounds": ("cure_light_wounds", 25),
"cure_serious_wounds": ("cure_serious_wounds", 100),
"cure_disease": ("cure_disease", 150),
"neutralize_poison": ("neutralize_poison", 150),
"remove_curse": ("remove_curse_c", 200),
"raise_dead": ("raise_dead", 1500),
}
)
The temple's healing services: each service name mapped to its spell id and its standard price in gold pieces.
The keys are the HealingService values that
PurchaseHealing accepts in its service field. The
spell id is the spell the temple casts, which is why remove curse maps to remove_curse_c, the
cleric's version of that spell rather than the magic-user's.
A town charges the standard price for a service unless the adventure sets a different price for
that service in TownSpec.healing_prices. To show a
town's price list, or to check the party's gold against a price before you send the command, read
PlayerView.town_healing_prices, which gives
what the party's town charges for every service.
The SRD's town rules don't list temple services, so osrlib chose these names and prices and records the choice in the adaptations register. Every service is always available. Whether a town is big enough to have a temple, or a cleric is in today, is up to you.
The mapping is read-only, so assigning or deleting an entry raises TypeError.
check_fatigue
Attach the fatigue penalty once the party has gone too long without a rest.
The SRD's dungeon rule is that a party rests one turn in every six, and a party that presses on
takes −1 to attack rolls and −1 to damage rolls until it does. This is the check for that rule.
It reads the session's turns_since_rest counter. When the counter has reached the threshold, it
attaches the fatigue effect to every living member who isn't fatigued already.
GameSession.advance_turns calls this for
every turn that passes while the session is in exploring mode, except a turn spent resting, so
if you move time by executing commands, you don't call it. Call it yourself when you
move the clock some other way. To ask whether the party is already fatigued, query
FATIGUE_KIND against session.ledger instead of
calling this. A Rest releases the effect and sets the counter back
to zero once the party has rested one full turn, even if a wandering monster interrupts the rest
later.
The threshold is six unrested turns, or three when the deprivation_penalties ruleset flag is
on and some living member has gone a full day without food or water.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
GameSession
|
The running session. |
required |
Returns:
| Type | Description |
|---|---|
list[Event]
|
The attachment events, closed by a |
Examples:
from osrlib.core.abilities import AbilityScore
from osrlib.core.alignment import Alignment
from osrlib.core.character import Character
from osrlib.crawl.adventure import Adventure, TownSpec
from osrlib.crawl.commands import EnterDungeon
from osrlib.crawl.dungeon import DungeonSpec, LevelSpec, WanderingSpec
from osrlib.crawl.exploration import FATIGUE_KIND, check_fatigue
from osrlib.crawl.party import Party
from osrlib.crawl.session import GameSession
hero = Character(
name="Hild",
class_id="fighter",
race="human",
level=1,
xp=0,
scores={ability: 12 for ability in AbilityScore},
alignment=Alignment.LAWFUL,
max_hp=8,
current_hp=8,
)
# chance_in_six=0 keeps a wandering monster from interrupting the six turns.
level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0), wandering=WanderingSpec(chance_in_six=0))
adventure = Adventure(
name="A First Delve",
town=TownSpec(name="Threshold"),
dungeons=(DungeonSpec(id="crypt", name="The Old Crypt", levels=(level,)),),
)
session = GameSession.new(Party(members=[hero]), adventure, seed=7)
session.execute(EnterDungeon(dungeon_id="crypt"))
# advance_turns runs the check itself, so the fatigue event is already in its events.
events, interrupted = session.advance_turns(6)
assert not interrupted
assert "exploration.fatigue.gained" in [event.code for event in events]
assert session.ledger.active_on(hero.id, FATIGUE_KIND)
print(check_fatigue(session))
# []
consume_provisions
Feed and water every living member for one day, and report who went short.
One call covers one day. Each living member eats a standard ration, or an iron ration when they have no standard one, since fresh food spoils first. Each drinks from a waterskin they carry. The waterskin isn't used up, so carrying one covers every day. In town nobody goes short: a member still eats their rations, and a member with none is fed anyway.
GameSession.advance_rounds calls this each
time the clock crosses into a new day, and every command that passes time goes through it, so
if you move time by executing commands, you don't call this. Call it yourself when you
move the clock some other way.
session.deprivation maps each member's id to a
DeprivationState that counts the days in a row the
member has gone without food and without water. A day with food sets the food count back to
zero, and a day without adds one, and the same goes for water. This function keeps the counts
however the ruleset is set, so you can show a hunger indicator without turning the penalties on.
When Ruleset.deprivation_penalties is on,
the member also takes penalties from the counts: −1 to attack rolls and fatigue twice as fast
from one day, half movement from two, and 1d4 damage a day from three. Food and water don't add
up: the worse of the two counts sets the penalty. The SRD gives examples rather than a schedule,
so osrlib chose this one and records it in the
adaptations register.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
GameSession
|
The running session. |
required |
Returns:
| Type | Description |
|---|---|
list[Event]
|
One |
Examples:
from osrlib.core.abilities import AbilityScore
from osrlib.core.alignment import Alignment
from osrlib.core.character import Character
from osrlib.crawl.adventure import Adventure, TownSpec
from osrlib.crawl.commands import EnterDungeon
from osrlib.crawl.dungeon import DungeonSpec, LevelSpec
from osrlib.crawl.exploration import consume_provisions
from osrlib.crawl.party import Party
from osrlib.crawl.session import GameSession
hero = Character(
name="Hild",
class_id="fighter",
race="human",
level=1,
xp=0,
scores={ability: 12 for ability in AbilityScore},
alignment=Alignment.LAWFUL,
max_hp=8,
current_hp=8,
)
level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0))
adventure = Adventure(
name="A First Delve",
town=TownSpec(name="Threshold"),
dungeons=(DungeonSpec(id="crypt", name="The Old Crypt", levels=(level,)),),
)
session = GameSession.new(Party(members=[hero]), adventure, seed=7)
session.execute(EnterDungeon(dungeon_id="crypt"))
events = consume_provisions(session) # Hild carries no rations and no waterskin
print([(event.code, event.kind) for event in events])
# [('exploration.provisions.short', 'food'), ('exploration.provisions.short', 'water')]
assert session.deprivation[hero.id].worst == 1
exploration_rate
exploration_rate(session) -> int
Return the party's exploration rate in feet per turn.
A party moves at the pace of its slowest living member, so that member's movement rate is the
party's. Read it to show how far the party moves in a turn, or to find out whether the party can
move at all. A rate of 0 means that a living member is carrying too much to move, or that no
member is living. In the first case the session refuses a
MoveParty with exploration.move.cannot_move and the
reason overloaded, until the member lightens the load with
DropItems or GiveItems.
In the second case the session is already in game_over.
For one character's movement rate rather than the party's, call
Character.movement_rate, which this function
calls for each member.
You don't spend the rate yourself. The session counts each step against it on an odometer and advances the clock a turn when the odometer fills. The rate changes as the party's load does, so read it again after anything that changes what the party carries.
Under the deprivation_penalties ruleset flag, a member two or more days into the worse of
their food and water tracks moves at half rate, which slows the whole party.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
GameSession
|
The running session. |
required |
Returns:
| Type | Description |
|---|---|
int
|
The slowest living member's movement rate in feet per turn, or 0 when no member is living. |
Examples:
from osrlib.core.abilities import AbilityScore
from osrlib.core.alignment import Alignment
from osrlib.core.character import Character
from osrlib.crawl.adventure import Adventure, TownSpec
from osrlib.crawl.commands import EnterDungeon
from osrlib.crawl.dungeon import DungeonSpec, LevelSpec
from osrlib.crawl.exploration import exploration_rate
from osrlib.crawl.party import Party
from osrlib.crawl.session import GameSession
hero = Character(
name="Hild",
class_id="fighter",
race="human",
level=1,
xp=0,
scores={ability: 12 for ability in AbilityScore},
alignment=Alignment.LAWFUL,
max_hp=8,
current_hp=8,
)
level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0))
adventure = Adventure(
name="A First Delve",
town=TownSpec(name="Threshold"),
dungeons=(DungeonSpec(id="crypt", name="The Old Crypt", levels=(level,)),),
)
session = GameSession.new(Party(members=[hero]), adventure, seed=7)
session.execute(EnterDungeon(dungeon_id="crypt"))
print(exploration_rate(session))
# 120
wandering_check
Roll one wandering-monster check, and when monsters come, spawn them and open the encounter.
GameSession.advance_turns calls this every
wandering_interval turns while the session is in
exploring mode, so if you move time by executing commands, you don't call it. Call it
yourself to run the checks from a clock of your own, or to make an extra check the rules don't
schedule.
Every check clears the session's noise flag, because the noise has now counted for a check.
When monsters come, the check also changes these:
- It spawns the monsters into the session and opens an encounter.
- It puts the session in
encountermode, or inbattlemode when the monsters attack at once. The session then refuses the exploring commands and accepts the encounter commands. - When
advance_turnsmade the call, it passes no more time.
The chance in six starts from the level's chance and changes like this:
- +1 for noise since the last check.
- +1 for light as bright as daylight.
- −1 while the party hides. Resting alone doesn't count. The OSE SRD lowers the chance only
for a party that rests quietly in an out-of-the-way place, which it calls hiding. To have
the party hide, send a
Restwithhiddenset.
The chance is limited to the range 0 to 6. When it's 0, the check makes no random roll and reports that no monsters came.
The check, the roll on the encounter table, and the number of monsters use
WANDERING_STREAM, one of the session's named
random number streams. The monsters and the encounter that follows use their own streams.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
GameSession
|
The running session. |
required |
resting
|
bool
|
True while the party rests quietly in an out-of-the-way place, which the OSE SRD calls hiding. It applies the −1 to the chance. A plain rest passes False. |
False
|
Returns:
| Type | Description |
|---|---|
tuple[list[Event], bool]
|
The check's events, and True when an encounter opened. The events start with one
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the party isn't in a dungeon, because no wandering-monster checks run in
town or on the road. The call changes nothing before it raises. To check first, test
that |
Examples:
from osrlib.core.abilities import AbilityScore
from osrlib.core.alignment import Alignment
from osrlib.core.character import Character
from osrlib.crawl.adventure import Adventure, TownSpec
from osrlib.crawl.commands import EnterDungeon
from osrlib.crawl.dungeon import DungeonSpec, LevelSpec
from osrlib.crawl.exploration import wandering_check
from osrlib.crawl.party import Party
from osrlib.crawl.session import GameSession
hero = Character(
name="Hild",
class_id="fighter",
race="human",
level=1,
xp=0,
scores={ability: 12 for ability in AbilityScore},
alignment=Alignment.LAWFUL,
max_hp=8,
current_hp=8,
)
level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0))
adventure = Adventure(
name="A First Delve",
town=TownSpec(name="Threshold"),
dungeons=(DungeonSpec(id="crypt", name="The Old Crypt", levels=(level,)),),
)
session = GameSession.new(Party(members=[hero]), adventure, seed=7)
session.execute(EnterDungeon(dungeon_id="crypt"))
events, encountered = wandering_check(session)
check = events[0]
print((check.chance, check.roll, encountered)) # 1 in 6, rolled a 4, nothing came
# (1, 4, False)
wandering_interval
wandering_interval(session) -> int
Return how many turns pass between wandering-monster checks on the level the party is on.
Each dungeon level has an interval, set in its
WanderingSpec. The default is two turns, as in the SRD.
The session counts turns against this number. When the count reaches it, the session runs
wandering_check and starts counting again. Read it
to show how often the checks come, or to run checks on the same schedule from a clock of your
own.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
GameSession
|
The running session. |
required |
Returns:
| Type | Description |
|---|---|
int
|
The interval in turns for the level the party is on. Outside a dungeon it's 1000000000, a number the turn counter never reaches, because no wandering-monster checks run in town or on the road. |
Examples:
from osrlib.core.abilities import AbilityScore
from osrlib.core.alignment import Alignment
from osrlib.core.character import Character
from osrlib.crawl.adventure import Adventure, TownSpec
from osrlib.crawl.commands import EnterDungeon
from osrlib.crawl.dungeon import DungeonSpec, LevelSpec
from osrlib.crawl.exploration import wandering_interval
from osrlib.crawl.party import Party
from osrlib.crawl.session import GameSession
hero = Character(
name="Hild",
class_id="fighter",
race="human",
level=1,
xp=0,
scores={ability: 12 for ability in AbilityScore},
alignment=Alignment.LAWFUL,
max_hp=8,
current_hp=8,
)
level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0))
adventure = Adventure(
name="A First Delve",
town=TownSpec(name="Threshold"),
dungeons=(DungeonSpec(id="crypt", name="The Old Crypt", levels=(level,)),),
)
session = GameSession.new(Party(members=[hero]), adventure, seed=7)
print(wandering_interval(session)) # the session starts in town
# 1000000000
session.execute(EnterDungeon(dungeon_id="crypt"))
print(wandering_interval(session))
# 2