Skip to content

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:

session.register_listener(Interpreter(session))

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}":

  1. MarkTriggerFired, with the narrative's fired text. It comes first, so a trigger that fires only once can't fire again on the events of its consequences.
  2. The consequences, in the order the trigger lists them. The interpreter replaces the selectors @party, @first, and @carrier with the ids of the living members they select, so the log records real character ids and a replay matches.
  3. AddJournalEntry with the narrative's journal text, 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:

  1. 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.
  2. 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 RevealObjective when its reveal_when matches. For an incomplete objective, it executes CompleteObjective when its when matches. An objective that's completed before it's revealed doesn't need a reveal, because completing an objective reveals it.
  3. As soon as an objective completes, the quest's completion rule (all or any) is checked against the objectives' state. When the rule holds, the interpreter executes CompleteQuest, 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 in victory before 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 SpawnNpcParty while an encounter is already open.
  • A grant to a character who isn't in the party.
  • A RemoveCoins toll that the first living member can't pay.
  • A command whose selector selects nobody, like @carrier when 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

key = 'osrlib.interpreter'

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

handle(events: Sequence[Event], state: dict) -> tuple[list[Event], dict]

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 listener_state, always an empty dict.

required

Returns:

Type Description
tuple[list[Event], dict]

No events and the state dict it was given, unchanged. Everything the interpreter does is a command it executed, and it stores nothing between commands.