osrlib.crawl.interpreter
The listener that plays an adventure's triggers and quests.
Interpreter turns the triggers and quests written
in an adventure document into things that happen in play. A trigger makes something happen
when the party does something, like setting a flag when it enters a dungeon. A quest is a
task with objectives that the party completes in play.
The interpreter reads the triggers and quests of the
Adventure the session is playing. It's an ordinary
listener, which you register with
GameSession.register_listener. It
checks the events of every accepted command against the adventure's
TriggerSpecs and
QuestSpecs. It acts by
executing ordinary referee commands, each one with its source set to the trigger or quest
it acted for. What it does appears in the command's events as
TriggerFiredEvent,
JournalEntryAddedEvent,
QuestActivatedEvent,
ObjectiveRevealedEvent,
ObjectiveCompletedEvent,
QuestCompletedEvent,
AdventureCompletedEvent, and
NoteRecordedEvent, plus the events that the
consequences and rewards emit.
Acting only through commands keeps the game replayable. The interpreter returns no events and
stores nothing between commands, so a replay, which runs with no listeners at all, rebuilds the
same game by executing the same command log again. Every effect a trigger or a quest has is a
command in that log, and each of those commands has a source field that refers to the trigger
or quest that issued it, like "trigger:the-door-shuts".
Write your own listener instead when you want something that triggers and quests can't express. The guide Listeners and flags covers the listener contract, and Gates, triggers, and quests covers what this one plays.
Interpreter
Interpreter(session: GameSession)
Plays an adventure's triggers and quests by executing referee commands.
Register one, once, on a session that has already been built:
Register it again on a session restored from a save, because listeners are code and a save
contains only data. There's no state to restore: the interpreter's entry in listener_state is
empty and stays empty for the life of the session.
For each accepted command, the interpreter goes through the command's events in the order they happened. For each event, it checks the adventure's triggers in the order the adventure lists them, and then its quests in the same way.
A trigger matches an event when all of these are true:
- Its pattern fits the event.
- It hasn't fired yet, or it's
repeatable. - Every one of its conditions holds against the session's state at that moment.
A trigger that matches fires at once, before the next trigger is checked. So a later trigger's conditions are checked against what an earlier firing has already changed.
A firing executes these commands, each with source="trigger:{id}":
MarkTriggerFired, with the narrative'sfiredtext. It comes first, so a trigger that fires only once can't fire again on the events of its consequences.- The consequences, in the order the trigger lists them. The interpreter replaces the
selectors
@party,@first, and@carrierwith the ids of the living members they select, so the log records real character ids and a replay matches. AddJournalEntrywith the narrative'sjournaltext, when it has one. It comes last, so the entry records the clock time after the consequences.
A quest clause (TriggerClause) matches an event the
same way a trigger does, with the same patterns and conditions. For a quest, the interpreter
executes these commands, each with source="quest:{id}", and checks the quest in this order:
- For an inactive quest whose activation clause matches, the interpreter executes
ActivateQuest, and the check goes on to the objectives of the quest it just activated. The same event that starts a quest can complete an objective in it. - The objectives of an active quest are checked in the order the quest lists them. For a
hidden objective that hasn't been revealed or completed, the interpreter executes
RevealObjectivewhen itsreveal_whenmatches. For an incomplete objective, it executesCompleteObjectivewhen itswhenmatches. An objective that's completed before it's revealed doesn't need a reveal, because completing an objective reveals it. - As soon as an objective completes, the quest's completion rule (
allorany) is checked against the objectives' state. When the rule holds, the interpreter executesCompleteQuest, followed by the rewards in the order the quest lists them, with selectors replaced as they are for a trigger's consequences. When the quest concludes the adventure, the session is already invictorybefore the first reward, so a reward that is illegal there, like spawning monsters, is dropped with a note.
Each check runs against the state the earlier commands left. A flag an earlier firing set can satisfy a later clause's condition for the same event, and a quest completed earlier in the check stays completed for everything after it.
The interpreter doesn't check a completed quest again, so an objective that's still incomplete when its quest completes stays incomplete.
The interpreter doesn't follow up on quest commands you execute yourself. It checks
the completion rule only after a completion it issued, and no pattern matches the quest
events, so if you complete the last objective yourself, complete the quest yourself too. For
the same reason, a CompleteQuest command you
execute grants no rewards. Only the interpreter issues rewards, and a replay executes the
reward commands themselves.
When a command fails, the interpreter drops it, goes on with the others, and records why
in a RecordNote. The note gives the trigger or
quest, the dropped command's position and type, and the rejection code. These are some
commands it drops:
- A
SpawnNpcPartywhile an encounter is already open. - A grant to a character who isn't in the party.
- A
RemoveCoinstoll that the first living member can't pay. - A command whose selector selects nobody, like
@carrierwhen no living member carries the item. Its note gives that reason instead of a rejection code.
If the party dies partway through and the session ends, the remaining commands are
accepted or dropped by the ordinary rules of the game_over mode.
A chain of reactions has a limit. The events of the command you execute are at depth 0, and the events of each command the interpreter executes are one level deeper than the event that caused it. For an event at depth five or deeper, the interpreter issues nothing. It records a note for each command it would have issued instead, and changes no state, so a trigger that fires only once can still fire on a later event.
It returns no events, because the commands it executed already logged everything it
caused, and it stores nothing between commands. Read what a trigger or a quest did from
the command log, the journal, session.fired_triggers, and session.quests, all of
which a replay rebuilds.
Examples:
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 EnterDungeon, SetFlag
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.session import GameSession
from osrlib.crawl.triggers import DungeonEnteredPattern, TriggerSpec
rules = Ruleset()
rng = RngStreams(master_seed=7).get(CHARACTER_CREATION_STREAM)
hero = create_character(
name="Hild",
class_id="fighter",
alignment=Alignment.LAWFUL,
ruleset=rules,
stream=rng,
)
level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0))
crypt = DungeonSpec(id="crypt", name="The Old Crypt", levels=(level,))
door_shuts = TriggerSpec(
id="the-door-shuts",
when=DungeonEnteredPattern(dungeon_id="crypt"),
consequences=(SetFlag(key="crypt.entered", value=True),),
narrative=NarrativeBlock(
fired="The door shuts behind the party.",
journal="The crypt door shut behind us.",
),
)
adventure = Adventure(
name="A First Delve",
town=TownSpec(name="Threshold"),
dungeons=(crypt,),
triggers=(door_shuts,),
)
session = GameSession.new(Party(members=[hero.character]), adventure, seed=7)
session.register_listener(Interpreter(session))
session.execute(EnterDungeon(dungeon_id="crypt"))
print(session.fired_triggers)
# ['the-door-shuts']
print(session.flags)
# {'crypt.entered': True}
print([entry.text for entry in session.journal])
# ['The crypt door shut behind us.']
Bind the interpreter to the session it watches and issues commands through.
Construct it after the session exists, pass it straight to
GameSession.register_listener,
and do the same again after loading a save. Each interpreter works with one session.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
GameSession
|
The session to play. The constructor reads its adventure's triggers and quests once, because an adventure doesn't change. |
required |
key
class-attribute
instance-attribute
The key of this listener's entry in the session's listener_state.
Registering the interpreter creates the entry, and it's an empty dict for the life of the
session, because the interpreter stores nothing between commands.
handle
Check one command's events against the triggers and quests, and act on the matches.
The session calls this after every accepted command, and you don't call it yourself. Every listener has this method, so its arguments show what the session passes a listener of your own.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
events
|
Sequence[Event]
|
The command's events in the order they happened, followed by the events that listeners registered before this one returned. |
required |
state
|
dict
|
The interpreter's entry in |
required |
Returns:
| Type | Description |
|---|---|
tuple[list[Event], dict]
|
No events and the |