osrlib.crawl.triggers
Authored triggers, which run referee commands when something happens in play.
A trigger pairs an event pattern with referee commands. When an event matches the pattern, and
the trigger's optional conditions hold, the commands run. Referee commands are the commands that
change the game directly, like GrantItem or
SetFlag.
You write TriggerSpecs into the triggers tuple of an
Adventure. When one event matches several triggers, they
fire in the order of that tuple. Triggers do nothing until you register an
Interpreter on the session with
GameSession.register_listener. The
interpreter matches the events of every accepted command against the adventure's triggers, and
executes the commands of each trigger that fires. When a trigger fires, you get these events:
- A
TriggerFiredEventwith the trigger'sfiredtext. - The events its commands produce.
- A
NoteRecordedEventfor each command the session rejected. - A
JournalEntryAddedEventwhen the trigger hasjournaltext.
session.fired_triggers records which triggers have fired.
A gate (GateSpec) tests the state of the game when the party
attempts something. A trigger matches the events a command produced, so it fires when
something happens, not while something is true. The lever that opens the portcullis is a
trigger, and the locked door you open with the brass key is a gate.
A trigger has these parts:
- A pattern (
TriggerPattern) is the event to react to: the party entering an area, a level, a dungeon, or the town (AreaEnteredPattern,LevelEnteredPattern,DungeonEnteredPattern,TownEnteredPattern), a member acquiring an item (ItemAcquiredPattern), a monster defeated (MonsterDefeatedPattern), or a flag written (FlagSetPattern). The interpreter matches a pattern against the event, never against the current state. A command that the interpreter runs for a trigger can move the party, but each event still describes the moment it happened. - Conditions (
ConditionSpec) narrow the match. Each one has to hold, against the session's state at the moment of the match. A condition withconsumes=Truefails validation, because a trigger matches an event that has already happened, and there's no attempt to charge a toll for. - Consequences (
ConsequenceCommand) are the referee commands the interpreter runs when the trigger fires, in the order you write them. In a grant, a removal, or an award, writePARTY_SELECTORorFIRST_LIVING_SELECTORin place of a character id. ARemoveItemcan also takeCARRIER_SELECTOR, which stands for the member who carries the item. - A narrative block (
NarrativeBlock) contains the trigger's text.firedis a line for the referee, andjournalis a line for the players. Writejournalfor the text the players should see.
Use a quest (QuestSpec) instead when you need to track
progress toward a goal. A quest's clauses use these same patterns and conditions. For an
adventure document that uses all three, see
Gates, triggers, and quests.
CARRIER_SELECTOR
module-attribute
The character_id to write in an authored RemoveItem that takes the item
from whoever carries it.
Use it for a quest item that's used up when the quest completes, or an offering the party
leaves on an altar, when you can't know which member will carry it. Before the
Interpreter runs the command, it replaces the
selector with the id of the first living member in marching order who carries the
command's quantity of the item. When no living member does, the interpreter drops the
command and records why in a NoteRecordedEvent.
validate_adventure accepts this selector
only on a RemoveItem. A grant or an award doesn't depend on what a member carries, and a
RemoveCoins uses
FIRST_LIVING_SELECTOR or
PARTY_SELECTOR.
FIRST_LIVING_SELECTOR
module-attribute
The character_id to write in an authored grant, removal, or award that applies to one member.
Before the Interpreter runs the command, it replaces
the selector with the id of the first living member in marching order. That member receives
the whole grant or award, and the party can share it out with
GiveItems. A removal takes from that member alone, so the
first living member in marching order pays a toll written with this selector. When no member is
alive, the interpreter drops the command and records why in a
NoteRecordedEvent. Use
PARTY_SELECTOR when every living member should
receive the reward.
PARTY_SELECTOR
module-attribute
The character_id to write in an authored grant, removal, or award that applies to every living member.
Write it as the character_id of a
GrantItem,
GrantCoins,
RemoveItem,
RemoveCoins, or
AwardXP in a trigger's consequences or a quest's
rewards. An adventure document can't contain real character ids, because a session assigns
them when it starts. validate_adventure rejects
any other character_id in those commands. So each of them in a document uses this selector,
FIRST_LIVING_SELECTOR, or, in a RemoveItem,
CARRIER_SELECTOR.
Before the Interpreter runs the command, it replaces
the command with one copy for each living member, in marching order, each with that member's
id. The command log records those copies, so a replay doesn't depend on the selector. When no
member is alive, the command expands to nothing, and the interpreter records no note. When the
session refuses a copy, like a removal from a member who doesn't have the item, the interpreter
drops that copy with a note and still runs the others. Use FIRST_LIVING_SELECTOR when one
member should receive the whole reward.
TriggerPattern
module-attribute
TriggerPattern = Annotated[
AreaEnteredPattern
| LevelEnteredPattern
| DungeonEnteredPattern
| TownEnteredPattern
| ItemAcquiredPattern
| MonsterDefeatedPattern
| FlagSetPattern,
Field(discriminator="pattern_type"),
]
The pattern union, discriminated on pattern_type.
Annotate a field with this alias when you write your own model that contains an authored
pattern. Pydantic then picks the member from the pattern_type value in the document.
It's the type of TriggerSpec.when and of
TriggerClause.pattern, so a quest clause can
match the same events a trigger can. The pattern_type values are part of the document format, so a
later release can add a member but doesn't rename one within a schema version.
AreaEnteredPattern
Bases: BaseModel
A pattern that matches the party entering a keyed area.
It matches a LocationEnteredEvent for
an area. An area id is unique only within its level, so the pattern includes the dungeon,
the level, and the area. Use
LevelEnteredPattern to react to the party
arriving anywhere on a level.
Examples:
from osrlib.crawl.triggers import AreaEnteredPattern
shrine = AreaEnteredPattern(dungeon_id="barrow", level_number=2, area_id="shrine")
print(shrine.model_dump(mode="json")) # the form the pattern takes in an adventure document
# {'pattern_type': 'area_entered', 'dungeon_id': 'barrow', 'level_number': 2, 'area_id': 'shrine'}
pattern_type
class-attribute
instance-attribute
pattern_type: Literal['area_entered'] = 'area_entered'
The discriminator value, area_entered. It appears in the document, and you
never set it yourself.
dungeon_id
class-attribute
instance-attribute
The id of the dungeon the area belongs to.
level_number
class-attribute
instance-attribute
The 1-based number of the level the area belongs to.
DungeonEnteredPattern
Bases: BaseModel
A pattern that matches the party crossing into a dungeon, from town or another dungeon.
It matches a LocationEnteredEvent for a
dungeon. Use it to react to the party entering the dungeon, and
LevelEnteredPattern to react to the party
reaching a particular level.
Examples:
from osrlib.crawl.triggers import DungeonEnteredPattern
arrival = DungeonEnteredPattern(dungeon_id="barrow")
print(arrival.model_dump(mode="json"))
# {'pattern_type': 'dungeon_entered', 'dungeon_id': 'barrow'}
pattern_type
class-attribute
instance-attribute
pattern_type: Literal['dungeon_entered'] = 'dungeon_entered'
The discriminator value, dungeon_entered. It appears in the document, and you
never set it yourself.
FlagSetPattern
Bases: BaseModel
A pattern that matches a write to a session flag.
It matches the write, not the flag's state. When you execute
SetFlag, or the interpreter executes it for a trigger,
the session emits a FlagSetEvent, and a trigger with a
pattern for that flag fires. The pattern compares the value that was written, so writing a flag again with the
value it already has still matches. To test the value a flag has now, use a
FlagEqualsCondition instead.
Examples:
from osrlib.crawl.triggers import FlagSetPattern
pulled = FlagSetPattern(key="crypt.lever", value="pulled")
print(pulled.model_dump(mode="json"))
# {'pattern_type': 'flag_set', 'key': 'crypt.lever', 'value': 'pulled'}
pattern_type
class-attribute
instance-attribute
pattern_type: Literal['flag_set'] = 'flag_set'
The discriminator value, flag_set. It appears in the document, and you
never set it yourself.
key
class-attribute
instance-attribute
The name of the flag to watch.
value
class-attribute
instance-attribute
The written value to match, or None to match any write of the flag. A flag value is
a str, an int, or a bool, never None, so None can't be mistaken for a value.
The pattern compares values with
flag_values_equal, the same strict comparison
a FlagEqualsCondition uses, so a written
True doesn't match an authored 1.
ItemAcquiredPattern
Bases: BaseModel
A pattern that matches a party member acquiring an item with item_id.
It matches an ItemAcquiredEvent, so it
matches an item the party takes as treasure, buys in town, or gets from a referee's
GrantItem. An item one member hands to another
doesn't match, because GiveItems reports an
ItemsGivenEvent instead. It accepts the same ids as a
HasItemCondition: ids from the equipment
catalog, which is the built-in items plus the adventure's bundled items, or from the
magic-item catalog.
The event contains a mundane item's catalog id, or a magic item's instance id, which the session assigns. To match a magic item, the interpreter looks up that instance in the acquiring member's inventory and compares its catalog id.
Examples:
from osrlib.crawl.triggers import ItemAcquiredPattern
taken = ItemAcquiredPattern(item_id="brass_key")
print(taken.model_dump(mode="json"))
# {'pattern_type': 'item_acquired', 'item_id': 'brass_key'}
pattern_type
class-attribute
instance-attribute
pattern_type: Literal['item_acquired'] = 'item_acquired'
The discriminator value, item_acquired. It appears in the document, and you
never set it yourself.
LevelEnteredPattern
Bases: BaseModel
A pattern that matches the party arriving on a dungeon level.
It matches however the party got there, by a stair from another level or by entering the dungeon from town. When one move enters both a dungeon and a level, the engine reports only the dungeon entry, and this pattern matches that report too.
Examples:
from osrlib.crawl.triggers import LevelEnteredPattern
deeper = LevelEnteredPattern(dungeon_id="barrow", level_number=2)
print(deeper.model_dump(mode="json"))
# {'pattern_type': 'level_entered', 'dungeon_id': 'barrow', 'level_number': 2}
pattern_type
class-attribute
instance-attribute
pattern_type: Literal['level_entered'] = 'level_entered'
The discriminator value, level_entered. It appears in the document, and you
never set it yourself.
dungeon_id
class-attribute
instance-attribute
The id of the dungeon the level belongs to.
MonsterDefeatedPattern
Bases: BaseModel
A pattern that matches a monster of template_id being slain or routed.
Slain and routed both count as defeated, and the pattern matches either one. The engine
reports each defeat with a
MonsterDefeatedEvent when the encounter
closes, not when the monster falls. A trigger on a boss therefore fires after the
fighting stops, never in the middle of a round. No pattern matches the moment of a
kill.
Examples:
from osrlib.crawl.triggers import MonsterDefeatedPattern
beaten = MonsterDefeatedPattern(template_id="ogre")
print(beaten.model_dump(mode="json"))
# {'pattern_type': 'monster_defeated', 'template_id': 'ogre'}
pattern_type
class-attribute
instance-attribute
pattern_type: Literal['monster_defeated'] = 'monster_defeated'
The discriminator value, monster_defeated. It appears in the document, and you
never set it yourself.
TownEnteredPattern
Bases: BaseModel
A pattern that matches the party arriving in the adventure's town, however it got there.
An adventure has one town, so the pattern has no fields. It matches when the party
travels back to town and when a referee command places the party there. Pair it with a
HasItemCondition for an errand that is done only
when the party comes home carrying an item.
Examples:
from osrlib.crawl.triggers import TownEnteredPattern
home = TownEnteredPattern()
print(home.model_dump(mode="json"))
# {'pattern_type': 'town_entered'}
pattern_type
class-attribute
instance-attribute
pattern_type: Literal['town_entered'] = 'town_entered'
The discriminator value, town_entered. It appears in the document, and you
never set it yourself.
TriggerSpec
Bases: BaseModel
One authored trigger: what it reacts to, what has to hold, and what happens.
Put your triggers in the triggers 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 trigger, so without it the
trigger does nothing.
By default a trigger fires once per session. When it fires, the interpreter executes
MarkTriggerFired, which adds the trigger's
id to session.fired_triggers. That record is part of the session, so a trigger that
has fired stays fired after a save, a load, or a replay. Set repeatable=True for a
trigger that fires every time its pattern matches.
For a trigger in a session from start to finish, see the
Interpreter example.
Examples:
from osrlib.crawl.commands import SetDoorState
from osrlib.crawl.dungeon import Direction
from osrlib.crawl.narrative import NarrativeBlock
from osrlib.crawl.triggers import FlagSetPattern, TriggerSpec
portcullis = SetDoorState(dungeon_id="crypt", level_number=1, x=2, y=0, direction=Direction.SOUTH, open=True)
trigger = TriggerSpec(
id="portcullis-rises",
when=FlagSetPattern(key="crypt.lever", value="pulled"),
consequences=(portcullis,),
narrative=NarrativeBlock(
fired="The counterweight drops somewhere in the wall.",
journal="The east lever gives; below, a portcullis grinds upward.",
),
)
print(trigger.repeatable, trigger.consequences[0].command_type)
# False set_door_state
id
class-attribute
instance-attribute
The trigger's id, unique across the adventure. session.fired_triggers records it, and
every command the interpreter runs for the trigger has source set to trigger:{id}.
when
instance-attribute
when: TriggerPattern
The pattern of the event that fires the trigger, as one member of
TriggerPattern.
conditions
class-attribute
instance-attribute
conditions: tuple[ConditionSpec, ...] = ()
Extra tests, every one of which has to hold when an event matches when. 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.
repeatable
class-attribute
instance-attribute
repeatable: bool = False
Whether the trigger fires every time its pattern matches. With False, the default,
it fires once per session.
consequences
class-attribute
instance-attribute
consequences: tuple[ConsequenceCommand, ...] = ()
The referee commands the interpreter runs when the trigger fires, 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 command, the interpreter drops it, records a note, and runs the
rest. The tuple can be empty, for a trigger that only adds a journal entry. A command with
source set fails validation with a pydantic ValidationError, because the interpreter sets
source itself.
narrative
class-attribute
instance-attribute
narrative: NarrativeBlock | None = None
The trigger's authored text. osrlib reads two fields of the block. fired goes on the
TriggerFiredEvent, which only the referee
sees. journal becomes a journal entry that the players see.