osrlib.crawl.quests
Authored quests, their objectives, and the clauses that start and finish them.
A quest is a task the session tracks for the party: what starts it, what it asks for, what it pays, and whether finishing it ends the adventure.
You write QuestSpecs into the quests tuple of an
Adventure, each with one or more
ObjectiveSpecs. When a session starts, it creates one
QuestState for each quest and stores them in
session.quests, keyed by quest id and in the order of the tuple. Each quest's objective
states are in the order of QuestSpec.objectives.
Quests don't advance until you register an
Interpreter on the session. The interpreter advances
quest state with the quest commands
ActivateQuest,
RevealObjective,
CompleteObjective, and
CompleteQuest. Those commands emit player-visible
events: QuestActivatedEvent,
ObjectiveRevealedEvent,
ObjectiveCompletedEvent,
QuestCompletedEvent, and, for a quest that ends
the adventure, AdventureCompletedEvent. To
show the active quests and their revealed objectives, read
PlayerView.quests.
The interpreter matches a quest's clauses the same way it matches a trigger. A quest's activation,
an objective's completion, and a hidden objective's reveal are each a
TriggerClause. A clause pairs a
TriggerPattern, the event to react to,
with ConditionSpecs that have to hold when the event
matches. A TriggerSpec uses the same patterns and
conditions. A quest's rewards are the same
ConsequenceCommands a trigger runs, with the same
party selectors: PARTY_SELECTOR,
FIRST_LIVING_SELECTOR, and, on a
RemoveItem only,
CARRIER_SELECTOR.
A quest's clauses only match events. A clause condition with consumes=True fails validation for the
same reason a trigger's does: the event the clause matches has already happened, so there's no
attempt to charge a toll for.
Write a trigger instead when you only need the adventure to react to an event, and there's no progress to track. To follow a quest from start to finish in an adventure document, see Gates, triggers, and quests.
ObjectiveSpec
Bases: BaseModel
One objective: what it is called, how it completes, whether it starts hidden, and its text.
Put your objectives in the objectives tuple of a
QuestSpec, in the order the quest log should show
them. The session tracks each objective in play as an
ObjectiveState, and you get the revealed ones
as ObjectiveViews.
An objective's state changes in one direction only. A hidden objective becomes revealed, an incomplete one becomes complete, and neither change is undone. There's no way to write an objective that repeats.
A hidden objective with no reveal_when is normal. It appears in the quest log when it
completes, because completing an objective reveals it. reveal_when on an objective
that starts visible fails validation with a pydantic ValidationError, because the
interpreter would never read it.
Examples:
from osrlib.crawl.narrative import NarrativeBlock
from osrlib.crawl.quests import ObjectiveSpec, TriggerClause
from osrlib.crawl.triggers import ItemAcquiredPattern
recover = ObjectiveSpec(
id="recover-flask",
name="Recover the flask",
when=TriggerClause(pattern=ItemAcquiredPattern(item_id="holy_water")),
narrative=NarrativeBlock(progress="The flask is yours, and the shrine is quiet again."),
)
print(recover.hidden, recover.reveal_when) # visible from the start, so it has no reveal clause
# False None
id
class-attribute
instance-attribute
The objective's id. It has to be unique within its quest, and another quest can use
the same id. The objective's state and view use it as their key, and it's shown in
place of name when name is empty.
name
class-attribute
instance-attribute
name: str = ''
The objective's display name, the words a quest log shows beside its checkbox. When it's empty, the view, the quest events, and the default message text use the id instead.
when
instance-attribute
when: TriggerClause
The clause that completes the objective. Completing an objective also reveals it, so a hidden objective needs no reveal clause to appear once it's done.
hidden
class-attribute
instance-attribute
hidden: bool = False
Whether the objective starts hidden from the party. A hidden objective has no view until it's revealed.
reveal_when
class-attribute
instance-attribute
reveal_when: TriggerClause | None = None
The clause that reveals a hidden objective before it completes. On an objective that
starts visible, it fails validation with a pydantic ValidationError.
narrative
class-attribute
instance-attribute
narrative: NarrativeBlock | None = None
The objective's text. osrlib reads two fields of the block: offer, the line shown
and added to the journal when the objective is revealed, and progress, the line shown
and added to the journal when it completes.
QuestSpec
Bases: BaseModel
One authored quest: when it starts, what it asks for, and what it pays.
Put your quests in the quests tuple of an
Adventure, and register an
Interpreter on the session to run them. The
interpreter is the only part of osrlib that reads a quest, so without it the quest
doesn't advance. The session tracks each quest in play as a
QuestState in session.quests, and you get each
active quest as a QuestView.
The interpreter runs the rewards after the quest completes, in the order you write
them, and only when the interpreter completed the quest. A quest you complete
with CompleteQuest pays no rewards.
Examples:
A quest that starts when the party enters the crypt and ends when a member picks up a flask of holy water:
from osrlib.core.alignment import Alignment
from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character
from osrlib.core.rng import RngStreams
from osrlib.core.ruleset import Ruleset
from osrlib.crawl.adventure import Adventure, TownSpec
from osrlib.crawl.commands import AwardXP, EnterDungeon, GrantItem
from osrlib.crawl.dungeon import DungeonSpec, LevelSpec
from osrlib.crawl.interpreter import Interpreter
from osrlib.crawl.narrative import NarrativeBlock
from osrlib.crawl.party import Party
from osrlib.crawl.quests import ObjectiveSpec, QuestSpec, TriggerClause
from osrlib.crawl.session import GameSession
from osrlib.crawl.triggers import PARTY_SELECTOR, DungeonEnteredPattern, ItemAcquiredPattern
recover = ObjectiveSpec(
id="recover-flask",
name="Recover the flask",
when=TriggerClause(pattern=ItemAcquiredPattern(item_id="holy_water")),
)
errand = QuestSpec(
id="the-flask",
name="The Stolen Flask",
activation=TriggerClause(pattern=DungeonEnteredPattern(dungeon_id="crypt")),
objectives=(recover,),
rewards=(AwardXP(character_id=PARTY_SELECTOR, amount=200),),
narrative=NarrativeBlock(
offer="Sister Halda wants her flask of holy water back, and she is not asking twice.",
completion="The flask returns to its niche. The temple bells answer.",
),
)
level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0))
crypt = DungeonSpec(id="crypt", name="The Old Crypt", levels=(level,))
town = TownSpec(name="Threshold")
adventure = Adventure(name="A First Delve", town=town, dungeons=(crypt,), quests=(errand,))
rules = Ruleset()
stream = RngStreams(master_seed=7).get(CHARACTER_CREATION_STREAM)
hero = create_character(
name="Hild", class_id="fighter", alignment=Alignment.LAWFUL, ruleset=rules, stream=stream
).character
session = GameSession.new(Party(members=[hero]), adventure, seed=7)
session.register_listener(Interpreter(session))
session.execute(EnterDungeon(dungeon_id="crypt"))
print(session.quests["the-flask"].status)
# active
# Stands in for the party finding the flask in play.
result = session.execute(GrantItem(character_id=hero.id, item_id="holy_water"))
for event in result.events:
print(event.code)
# exploration.item.acquired
# session.quest.objective_completed
# session.quest.completed
# session.xp.awarded
id
class-attribute
instance-attribute
The quest's id, unique across the adventure. session.quests uses it as the key, and
every command the interpreter runs for the quest has source set to quest:{id}.
name
class-attribute
instance-attribute
The quest's display name. The quest events and the quest's view include it, so you can show it without the adventure document.
activation
class-attribute
instance-attribute
activation: TriggerClause | None = None
The clause that starts the quest. With None, the quest is active from the start of
the session. No command starts it, so the session emits no
QuestActivatedEvent for it, but its
QuestView still includes the offer text. With a clause,
the quest starts when an event matches the clause.
objectives
class-attribute
instance-attribute
objectives: tuple[ObjectiveSpec, ...] = Field(min_length=1)
What the quest asks for, in the order a quest log should show the objectives. At least
one is required, because a quest with no objectives under the "all" rule would be
complete from the start.
rewards
class-attribute
instance-attribute
rewards: tuple[ConsequenceCommand, ...] = ()
The referee commands the interpreter runs after the quest completes, in the order you
write them. The interpreter replaces
PARTY_SELECTOR,
FIRST_LIVING_SELECTOR, and
CARRIER_SELECTOR with the members they select.
When the session rejects one reward, the interpreter drops it, records a note, and runs the
rest. A reward with source set fails validation with a pydantic ValidationError, because
the interpreter sets source itself.
completion
class-attribute
instance-attribute
completion: Literal['all', 'any'] = 'all'
The rule for completing the quest. With "all", the quest completes when every
objective is complete. With "any", it completes when the first objective completes.
Once the quest is complete, its other objectives never change. Under "any", an
objective that wasn't complete stays incomplete, even when the same event matched its
clause.
concludes_adventure
class-attribute
instance-attribute
concludes_adventure: bool = False
Whether completing this quest ends the adventure. The session moves to victory
mode and emits an
AdventureCompletedEvent before the
interpreter runs the first reward. A reward that victory mode doesn't allow, like
SpawnMonsters or
PlaceParty, is rejected, and the interpreter drops
it and records a note. Grants and experience awards still apply.
narrative
class-attribute
instance-attribute
narrative: NarrativeBlock | None = None
The quest's text. osrlib reads two fields of the block: offer, the line shown and
added to the journal when the quest starts, and completion, the line shown and added
to the journal when it completes. Each objective's text is in its
ObjectiveSpec.narrative.
TriggerClause
Bases: BaseModel
A pattern to match, and the conditions that must hold when an event matches it.
A quest has clauses in three places, and they work the same way in all three: the
activation of a QuestSpec, and the when and
reveal_when of an ObjectiveSpec. The
Interpreter matches a clause the same way it
matches a TriggerSpec, so an event that matches a
trigger's pattern and conditions also matches a clause with that pattern and those
conditions.
Examples:
from osrlib.crawl.gates import HasItemCondition
from osrlib.crawl.quests import TriggerClause
from osrlib.crawl.triggers import TownEnteredPattern
# Matches only when the party reaches town with the holy water on someone.
walked_home_carrying_it = TriggerClause(
pattern=TownEnteredPattern(),
conditions=(HasItemCondition(item_id="holy_water"),),
)
print(walked_home_carrying_it.model_dump(mode="json")["conditions"])
# [{'condition_type': 'has_item', 'item_id': 'holy_water', 'consumes': False}]
pattern
instance-attribute
pattern: TriggerPattern
The event the clause matches, as one member of
TriggerPattern. The field is named pattern,
not when, so an objective's completion pattern is objective.when.pattern.
conditions
class-attribute
instance-attribute
conditions: tuple[ConditionSpec, ...] = ()
Extra tests, every one of which has to hold when an event matches pattern. There's
no way to write "or". The interpreter evaluates each condition against the session at
that moment with condition_holds. A condition
with consumes=True fails validation with a pydantic ValidationError.