Skip to content

osrlib.crawl.events

The crawl event catalog: typed records of everything a session does.

Every command you run through GameSession.execute comes back with a CommandResult whose events tuple contains instances of the classes here and of the kernel classes in osrlib.core.events. Read them in order. Each event's visibility specifies whether the players may see it or only the referee may, so leave out the referee-only ones when you show them to a player. Turn each one into a line with format_message or with a renderer of your own that switches on the event's code. The session also appends the same objects to GameSession.event_log, and save_game writes that log into a save.

Every event has a code, an event_type, and a visibility:

  • The code identifies what happened, like exploration.door.opened: two or more snake_case parts separated by dots, where the first is the part of the rules the event comes from. A renderer picks its message by the code.
  • The event type identifies the class in serialized form, so a stored event rebuilds into the right class.
  • The visibility is who may see the event. player is for what the players learn. referee is for the rolls and bookkeeping the referee keeps hidden from them, like a detection die or a wandering-monster check.

A class that can report more than one outcome lists all its codes in allowed_codes, and each instance has one of them.

An event never contains English prose written by the engine. It contains facts and a code, so you can translate the line, and a narrator can write a different line from the same facts. The exception is a narrative field, which contains text the adventure's author wrote.

CRAWL_EVENT_CLASSES lists the classes in this module, and ALL_EVENT_CLASSES puts the kernel classes in front of them. AnyEvent is the union of every event class, for type hints and JSON Schema. parse_any_event turns a serialized record back into an event.

Typical usage:

from osrlib.core.alignment import Alignment
from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character
from osrlib.core.events import Visibility
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, MoveParty
from osrlib.crawl.dungeon import Direction, DungeonSpec, Edge, EdgeKind, LevelSpec
from osrlib.crawl.party import Party
from osrlib.crawl.session import GameSession
from osrlib.messages import format_message

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
corridor = LevelSpec(number=1, width=2, height=1, entrance=(0, 0), edges={"1,0:west": Edge(kind=EdgeKind.OPEN)})
crypt = DungeonSpec(id="crypt", name="The Old Crypt", levels=(corridor,))
adventure = Adventure(name="A First Delve", town=TownSpec(name="Threshold"), dungeons=(crypt,))
session = GameSession.new(Party(members=[hero]), adventure, seed=7)
session.execute(EnterDungeon(dungeon_id="crypt"))

result = session.execute(MoveParty(direction=Direction.EAST))
print([event.code for event in result.events])
# ['exploration.party.moved']
table = [format_message(event) for event in result.events if event.visibility is Visibility.PLAYER]
print(table)
# ['The party moves to (1, 0), facing east.']

ALL_EVENT_CLASSES module-attribute

ALL_EVENT_CLASSES: tuple[type[Event], ...] = (*KERNEL_EVENT_CLASSES, *CRAWL_EVENT_CLASSES)

Every event class the library can emit: the kernel classes first, then the ones in this module.

Walk it when you generate something from every event, like client types, a documentation table, or a schema bundle. Each class has its event type in model_fields["event_type"].default and its codes in allowed_codes.

AnyEvent module-attribute

AnyEvent = Annotated[Union[*ALL_EVENT_CLASSES,], Field(discriminator='event_type')]

Any event the library can emit, as a union pydantic discriminates on event_type.

Use it to type a value that can be an event of any class, and hand it to a TypeAdapter to get a tagged-union JSON Schema for a client in another language. To parse one record, call parse_any_event instead. It returns None for an event type or a code this version doesn't define, rather than raising on it.

from pydantic import TypeAdapter

from osrlib.crawl.events import AnyEvent

schema = TypeAdapter(AnyEvent).json_schema()
print(schema["discriminator"]["propertyName"])
# event_type

CRAWL_EVENT_CLASSES module-attribute

The event classes defined in this module, in the order they're declared.

Walk it to build a table of the crawl events, or to generate client types from their JSON Schemas. For every event class, including the kernel events from osrlib.core.events, use ALL_EVENT_CLASSES.

AdventureCompletedEvent

Bases: Event

The adventure is over and the party won.

Emitted by CompleteQuest when the quest that concludes the adventure completes, right after that quest's QuestCompletedEvent, with the same text. The session mode becomes victory, which is final: the session refuses play commands and never leaves that mode, so you can show a closing screen.

A session that has already ended doesn't end twice. When a party that has already fallen completes the quest, the quest completes with no AdventureCompletedEvent, and the session stays in game_over.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.adventure.completed'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['adventure_completed'] = 'adventure_completed'

The event type, adventure_completed, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.adventure.completed'

The message code, always session.adventure.completed.

visibility class-attribute instance-attribute

Player visibility: it's the party's ending.

quest_id instance-attribute

quest_id: str

The quest that concluded the adventure.

name class-attribute instance-attribute

name: str = ''

That quest's display name. The engine always fills it. It's empty only on an event loaded from a save written before the field existed.

narrative class-attribute instance-attribute

narrative: str | None = None

The quest's completion text, the same line as on its QuestCompletedEvent, or None.

AdventureXpAwardEvent

Bases: Event

The experience award for a trip to the dungeon: what the party earned and what each survivor gets.

Emitted by TravelToTown under the default ruleset, where experience is awarded for making it back. Each survivor's XpAwardedEvent follows it, each followed by a CharacterLeveledUpEvent when that member gains a level.

Treasure counts as the gain in the value of the party's coins, gems, and jewellery since it left town, so goods still lying in the dungeon are worth nothing yet. The session emits no event when nobody came back alive or when the delve earned nothing.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.xp.adventure_award'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['adventure_xp_award'] = 'adventure_xp_award'

The event type, adventure_xp_award, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.xp.adventure_award'

The message code, always session.xp.adventure_award.

visibility class-attribute instance-attribute

Player visibility: the party sees what it earned.

monster_xp instance-attribute

monster_xp: int

What the defeated creatures were worth, added up across the whole delve.

treasure_xp instance-attribute

treasure_xp: int

What the recovered treasure was worth, one experience point per gold piece of value gained since the party left town, and never less than zero.

share instance-attribute

share: int

What each survivor receives: the total divided by the number of survivors, rounded down. When it rounds down to zero, no XpAwardedEvent follows.

survivors instance-attribute

survivors: tuple[str, ...]

The members who made it back, in marching order. The dead count toward the treasure that came home but take no share.

BattleEndedEvent

Bases: Event

The battle is over: won, quit, or lost.

Emitted by ResolveBattleRound. A battle can also end in the command that opened it, before any ResolveBattleRound: every group's morale is too low to fight, or the monsters' free round leaves no party member standing.

A victory ends the encounter in the same result. After a retreat, monsters able to give chase start a chase, and the session goes back to encounter mode. Otherwise the encounter ends. A defeat means nobody is left standing, and a GameOverEvent follows in the same result.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'battle.ended.victory', 'battle.ended.fled', 'battle.ended.defeat'})

battle.ended.victory when no opposition is left fighting, battle.ended.fled when the party pulled out, and battle.ended.defeat when the party fell.

event_type class-attribute instance-attribute

event_type: Literal['battle_ended'] = 'battle_ended'

The event type, battle_ended, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party is in the fight and sees how it ends.

BattleRoundEvent

Bases: Event

A battle round began.

Emitted first by every ResolveBattleRound, before the declared spells and the initiative roll. In a transcript, group the rest of the round's events under it.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'battle.round.started'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['battle_round'] = 'battle_round'

The event type, battle_round, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'battle.round.started'

The message code, always battle.round.started.

visibility class-attribute instance-attribute

Player visibility: everyone knows which round it is.

round instance-attribute

round: int

Which round of this battle is starting, counting from one.

BattleStartedEvent

Bases: Event

The encounter became a battle.

Emitted when a fight opens: by EngageBattle when the party attacks, and by whichever command is running when the monsters attack. The monsters can attack the moment an encounter opens, when a parley goes wrong, when a hostile or uncertain stance turns to attack on a later round, when undead are presented with a holy symbol and not turned, or when a chase ends in capture.

The session mode becomes battle, where ResolveBattleRound is the only play command the session accepts. In battle, the session doesn't place monsters on cells. Each monster group has a distance from the party, and closing in or pulling back changes it.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'battle.started'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['battle_started'] = 'battle_started'

The event type, battle_started, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'battle.started'

The message code, always battle.started.

visibility class-attribute instance-attribute

Player visibility: the party is in it.

CharacterLeveledUpEvent

Bases: Event

A character crossed a threshold and gained a level.

Emitted right after that member's XpAwardedEvent, for whichever award crossed the threshold. A character gains at most one level per award.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.level.gained'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['leveled_up'] = 'leveled_up'

The event type, leveled_up, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.level.gained'

The message code, always session.level.gained.

visibility class-attribute instance-attribute

Player visibility: the new level goes on the character's sheet.

character_id instance-attribute

character_id: str

The member who gained the level.

level_before instance-attribute

level_before: int

The member's level before the award.

level_after instance-attribute

level_after: int

The member's level after the award, one higher.

hp_gained instance-attribute

hp_gained: int

How many hit points were added, the die and the constitution adjustment together, or the flat bonus past the class's last Hit Die.

hp_roll instance-attribute

hp_roll: int | None

The hit die that was rolled, or None past the class's last Hit Die, where levels bring a flat bonus and no die.

con_applied instance-attribute

con_applied: bool

Whether the constitution adjustment was applied, which happens only when a die was rolled.

title instance-attribute

title: str | None

The class's title for the new level, or None past the printed list of titles.

CurseRevealedEvent

Bases: Event

The curse on a cursed item is now known, and the item can't be taken off.

Emitted when the party learns of a cursed item's curse: when the item is used, or worn so that its curse takes hold, or when the referee identifies it with IdentifyItem. It comes right after the ItemIdentifiedEvent when the item wasn't identified yet. From then on the member can't drop, give away, or unequip the item until a remove curse lifts the curse.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'items.curse.revealed'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['curse_revealed'] = 'curse_revealed'

The event type, curse_revealed, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'items.curse.revealed'

The message code, always items.curse.revealed.

visibility class-attribute instance-attribute

Player visibility: the bearer learns about the curse when it takes hold.

character_id instance-attribute

character_id: str

The member who has the cursed item.

instance_id instance-attribute

instance_id: str

The session-scoped id of the cursed item.

template_id instance-attribute

template_id: str

What the item is, as its magic item catalog id.

DetectionRolledEvent

Bases: Event

A hidden die roll for a search, a listen, a thief skill, or a trap's chance to spring.

Emitted by Search, ListenAtDoor, PickLock, InspectTreasure, and RemoveTreasureTrap, ahead of any player-visible result, and whenever a trap gets its chance to spring.

The session rolls the die for a search or a listen whether or not there's anything to find, so a failed roll and an empty cell look the same to the players. That is why this event has referee visibility: showing it to players would tell them whether the roll failed. A referee front end, or an LLM running the game, reads it to know what happened.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.detection.rolled'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['detection_rolled'] = 'detection_rolled'

The event type, detection_rolled, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'exploration.detection.rolled'

The message code, always exploration.detection.rolled.

visibility class-attribute instance-attribute

Referee visibility: the roll is the part the referee keeps hidden from the players.

character_id class-attribute instance-attribute

character_id: str | None = None

The member who rolled, or None for a check that isn't a member's, like a trap's chance to go off.

kind instance-attribute

kind: str

What was being checked: "listening", one of the search kinds ("secret_doors", "room_traps", "construction"), "open_locks", "treasure_traps", or "trap_spring" for a trap's chance to fire.

chance instance-attribute

chance: int

The number the roll had to come in at or under. The listening, search, and trap-spring kinds are X-in-6 chances rolled on a d6. The thief skills open_locks and treasure_traps are percentages rolled on d100.

roll class-attribute instance-attribute

roll: int | None = None

What came up, or None when the chance was zero and no die was rolled, as for a character with no chance at all of noticing construction tricks.

passed instance-attribute

passed: bool

Whether the check succeeded. From the player's side, a failed check and a cell with nothing in it look the same.

DiceRolledEvent

Bases: Event

The referee rolled dice for something the rules don't cover.

Emitted by RollDice. The dice come from ADJUDICATION_STREAM, which the session uses for no other roll, so a referee rolling for weather or a rumour never changes the dice for a later attack or save.

It has referee visibility, because a referee's roll may be secret. Show it to the players yourself when you roll in the open.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'adjudication.dice_rolled'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['dice_rolled'] = 'dice_rolled'

The event type, dice_rolled, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'adjudication.dice_rolled'

The message code, always adjudication.dice_rolled.

visibility class-attribute instance-attribute

Referee visibility: the referee decides what to share.

expression instance-attribute

expression: str

What was rolled, as the dice expression that was asked for, like "2d6+1".

total instance-attribute

total: int

The result, dice and modifier together.

rolls instance-attribute

rolls: tuple[int, ...]

Each die's result, in roll order, so you can show the dice in a transcript rather than only the sum.

DoorEvent

Bases: Event

A door changed state. The event identifies the door by a cell and the side of the cell it's on.

Emitted by the door commands, OpenDoor, CloseDoor, ForceDoor, PickLock, and WedgeDoor. A door the party opened swings shut once the party walks away from it, unless it's wedged, so a command that moves the party, like MoveParty, UseStairs, or TravelToTown, can emit it too. A referee's SetDoorState emits it at referee visibility when it opens or closes a door, because the party didn't see that happen.

A door belongs to the edge between two cells, so you can refer to the same door from either side. Redraw the door from x, y, and direction rather than keeping your own record of which door is which.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset(
    {
        "exploration.door.opened",
        "exploration.door.closed",
        "exploration.door.forced",
        "exploration.door.stuck",
        "exploration.door.wedged",
        "exploration.door.swung_shut",
        "exploration.door.unlocked",
    }
)

exploration.door.opened and .closed for the plain cases, .forced for a door shouldered open and .stuck for the attempt that failed, .unlocked for a lock picked, .wedged for a door spiked in place, and .swung_shut for a door the party opened closing behind it.

event_type class-attribute instance-attribute

event_type: Literal['door'] = 'door'

The event type, door, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility, except on an event from the referee's SetDoorState, which is referee.

x instance-attribute

x: int

The column of the cell the door is named from. For a door command it's the party's cell, for SetDoorState it's the cell given in the command, and for a door swinging shut it's the cell on the door's south or east side.

y instance-attribute

y: int

The row of the cell the door is named from, chosen the same way as x.

direction instance-attribute

direction: str

Which side of that cell the door is on, as a lowercase Direction value.

character_id class-attribute instance-attribute

character_id: str | None = None

The member who forced the door, failed to force it, or picked its lock. None for the other codes, where the party acts as one or nobody acts.

narrative class-attribute instance-attribute

narrative: str | None = None

The success text the author wrote on the door's gate, when opening the door passed one, or None. The author wrote this text, not the engine, and format_message adds it after the line it builds from the code.

EncounterEndedEvent

Bases: Event

The encounter is over, however it went.

Emitted when the monsters are beaten or turned, or when the party gets away from them. The session goes back to exploring. The session then advances the clock to the start of the next turn, and to at least one full turn after the encounter opened, so time passes after this event even when the fight was short. The MonsterDefeatedEvents and the LootDroppedEvent come before it.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'encounter.ended'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['encounter_ended'] = 'encounter_ended'

The event type, encounter_ended, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'encounter.ended'

The message code, always encounter.ended. The ending is in outcome.

visibility class-attribute instance-attribute

Player visibility: the party knows the encounter is behind it.

outcome instance-attribute

outcome: str

How it ended:

  • "victory": the monsters were beaten.
  • "evaded": the party got away before or during a fight.
  • "escaped": the party got away at the end of a chase.
  • "turned": undead were driven off.
  • "parley": the party talked or paid its way past, through an EndEncounter.
  • "departed": the party walked away from monsters that let it go, through an EndEncounter.

EncounterGroupJoinedEvent

Bases: Event

A new monster group joined the open encounter or battle, with what the party can see of it.

Emitted by SpawnMonsters when an encounter or a battle is open, after the MonstersSpawnedEvent for the same monsters. The players learn of the new group from this event, as they learn of the first groups from EncounterStartedEvent. The session rolls no surprise or reaction for the group. The group acts from the next round.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'encounter.group.joined'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['encounter_group_joined'] = 'encounter_group_joined'

The event type, encounter_group_joined, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'encounter.group.joined'

The message code, always encounter.group.joined.

visibility class-attribute instance-attribute

Player visibility: the party sees the new monsters arrive.

group_id instance-attribute

group_id: str

The new group's id, the same as its EncounterGroupView.id in the player view. To attack the group, put this id in a battle declaration's target_group_id.

label instance-attribute

label: str

The group's label: what the party would call one of its members, like "goblin".

label_plural class-attribute instance-attribute

label_plural: str = Field(default='', validate_default=True)

The group's label_plural, like "goblins", for a line like "2 goblins". An event loaded from a save that has no plural gets label with the regular English ending.

count instance-attribute

count: int

How many creatures are in the group.

distance_feet instance-attribute

distance_feet: int

How far away the group is, in feet, when it joins.

EncounterStartedEvent

Bases: Event

The party met monsters, with what the party can see of them.

Emitted when an encounter opens, whichever way it opened: the party stepping into an area whose author placed monsters there, with MoveParty, or arriving in one with EnterDungeon or UseStairs, a wandering-monster check that hits, or a referee's SpawnMonsters or SpawnNpcParty. The session mode becomes encounter, where the party can talk, run, wait, or fight.

It contains only what the party can see: a name, a count, and a distance. The dice behind the meeting are on the SurpriseRolledEvents and the reaction roll's kernel event, both at referee visibility. The two surprise outcomes are here, because the party knows when it's caught off guard.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'encounter.started'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['encounter_started'] = 'encounter_started'

The event type, encounter_started, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'encounter.started'

The message code, always encounter.started.

visibility class-attribute instance-attribute

Player visibility: this is the moment the players are told what they have met.

monster_name instance-attribute

monster_name: str

The label of the first group in the encounter: what the party would call one of its members, like "goblin". A party of NPC adventurers appears as "adventurer", and its roster stays hidden from the players.

monster_name_plural class-attribute instance-attribute

monster_name_plural: str = Field(default='', validate_default=True)

The first group's label_plural, like "goblins", for a line like "3 goblins". An event loaded from a save that has no plural gets monster_name with the regular English ending.

count instance-attribute

count: int

How many creatures there are across every group in the encounter.

distance_feet instance-attribute

distance_feet: int

How far away they are, in feet, when the encounter opens. Battle starts from this distance and closes from there.

party_surprised class-attribute instance-attribute

party_surprised: bool = False

Whether the party was caught off guard, which can give the monsters a free first round.

monsters_surprised class-attribute instance-attribute

monsters_surprised: bool = False

Whether the monsters were caught off guard, which gives the party a free round if the fight starts.

EvasionEvent

Bases: Event

The party tried to get away, and either got away or is being chased.

Emitted by Evade. When the party gets clear at once, the encounter ends in the same result. Otherwise a chase begins, and its rounds arrive as PursuitEvents, the first in this same result.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'encounter.evasion.succeeded', 'encounter.evasion.pursuit'})

encounter.evasion.succeeded when the party is away clean, encounter.evasion.pursuit when something gives chase.

event_type class-attribute instance-attribute

event_type: Literal['evasion'] = 'evasion'

The event type, evasion, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party knows whether it's being followed.

ExhaustionEvent

Bases: Event

The party became exhausted from a long chase, or rested long enough to recover.

Running flat out for a long chase gives a party −2 to its attack and damage rolls and makes it 2 easier to hit, until it rests. encounter.exhaustion.gained comes from the Evade, Wait, or DropItems whose round ends a chase that lasted PURSUIT_ROUND_CAP rounds. encounter.exhaustion.recovered comes from the Rest that completes three turns of rest since the chase.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'encounter.exhaustion.gained', 'encounter.exhaustion.recovered'})

encounter.exhaustion.gained when the chase exhausts the party, encounter.exhaustion.recovered when enough rest clears it.

event_type class-attribute instance-attribute

event_type: Literal['exhaustion'] = 'exhaustion'

The event type, exhaustion, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the penalty is on the party's character sheets.

FatigueEvent

Bases: Event

The party gained the penalty for going without rest, or recovered from it.

The B/X rules require a party to rest one turn in every six while it's in a dungeon. A turn is 10 minutes of game time, or 60 rounds. A party that goes six turns without a rest takes −1 to attack and damage rolls until it rests. These two codes mark when the penalty starts and when it lifts.

exploration.fatigue.gained comes from any command that passes a turn while the session is in exploring mode, once the party has gone six turns without a rest. Under the deprivation_penalties ruleset flag, three turns are enough when a living member has gone a full day without food or water. See check_fatigue.

exploration.fatigue.recovered comes from a Rest once the party has rested one full turn. One full turn of rest is enough, even if a wandering monster interrupts the rest after that.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.fatigue.gained', 'exploration.fatigue.recovered'})

exploration.fatigue.gained when the party misses its rest, exploration.fatigue.recovered when a rest clears the penalty.

event_type class-attribute instance-attribute

event_type: Literal['fatigue'] = 'fatigue'

The event type, fatigue, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party feels it, and the penalty is on their sheets.

FlagSetEvent

Bases: Event

A session flag was written.

Emitted by the referee's SetFlag. Flags are where the session records state. An adventure's triggers and gates can depend on a flag through a FlagEqualsCondition, and you can store anything else you need there.

It has referee visibility, because flags record the game's state, not events in the story the players see.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.flag.set'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['flag_set'] = 'flag_set'

The event type, flag_set, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.flag.set'

The message code, always session.flag.set.

visibility class-attribute instance-attribute

Referee visibility: flags are bookkeeping that the players don't see.

key instance-attribute

key: str

Which flag was written.

value instance-attribute

value: str | int | bool

What it was set to. Writing an existing key replaces its value.

GameOverEvent

Bases: Event

No party member is left standing, and the session has ended.

A member stands while they are neither dead nor turned to stone. Emitted by the command during which the last standing member died or was petrified, whatever felled them: a lost battle, a trap, a fall down a chute, starvation, a poison that took effect while the referee moved the clock, or a basilisk's gaze. It comes after that command's other events, and the session mode becomes game_over.

The session refuses play commands from then on. Referee commands still work, and PlaceParty takes the session out of game_over. Placing the fallen party in town lets the temple raise the dead with PurchaseHealing. The temple has no cure for stone, so a statue needs stone to flesh from a magic-user, who can join the party in town with AddMember.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.game_over'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['game_over'] = 'game_over'

The event type, game_over, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.game_over'

The message code, always session.game_over.

visibility class-attribute instance-attribute

Player visibility: it's the party's ending.

reason instance-attribute

reason: str

Why the session ended, as a short phrase. Every ending has the same reason, that the party has fallen. What killed them is in the events just before it.

GroupMovedEvent

Bases: Event

A monster group's distance from the party line changed.

The party line is where the party stood when the encounter opened. Each group's distance is measured from it, and each party member stands at their own place on the same track, which MemberMovedEvent reports. When every member the monsters can see has fallen back behind the line, the line moves back to the foremost of them, and every group's distance grows by the same amount with no event, because nobody moved toward or away from anyone. BattleState.advance_feet describes it.

Emitted by ResolveBattleRound whenever a group's distance changes: monsters closing to strike, a broken group running away, and the whole party backing away from every group in a formation move. A member who closes on a group by themselves doesn't move the group, so that emits a MemberMovedEvent and no GroupMovedEvent.

The event reports the group's distance right after its move. When the party line moves back later in the round, the distance grows with no event, so use this event to narrate or animate the move, not to draw where the group stands. A member's distance to this group is the group's distance_feet minus the member's entry in EncounterView.advance_feet, and EncounterGroupView.member_distance_feet lists it for you in the player view after the round.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'battle.group.moved'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['group_moved'] = 'group_moved'

The event type, group_moved, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'battle.group.moved'

The message code, always battle.group.moved.

visibility class-attribute instance-attribute

Player visibility: the party watches them come on or draw off.

group_id instance-attribute

group_id: str

Which group moved, as its encounter group id.

distance_feet instance-attribute

distance_feet: int

How far that group now is from the party line, in feet, after the move. A group that closes in stops within MELEE_RANGE_FEET of the nearest member it can see, where the two fight hand to hand.

HealingPurchasedEvent

Bases: Event

The party paid for a temple service, and the temple cast it.

Emitted by PurchaseHealing in town, followed by the kernel events of the spell the temple casts. The fee can come from more than one member, so payers and payments_gp show which purses paid and how much each one paid.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'town.healing.purchased'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['healing_purchased'] = 'healing_purchased'

The event type, healing_purchased, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'town.healing.purchased'

The message code, always town.healing.purchased.

visibility class-attribute instance-attribute

Player visibility: the party bought it.

character_id instance-attribute

character_id: str

The member the service was cast on. Their purse is charged first, but the party covers whatever is left, so read payers for who actually paid.

service instance-attribute

service: str

Which service was bought, as its key in HEALING_SERVICES, like "cure_light_wounds".

cost_gp instance-attribute

cost_gp: int

What it cost, in gold pieces.

payers class-attribute instance-attribute

payers: tuple[str, ...] = ()

The ids of the members whose purses paid, in the order they were charged: the treated member first, then the rest of the party in marching order, dead members included. Each purse pays as much of the fee still owed as its coins' value covers, in whole gold pieces, until the fee is paid. A member whose purse paid nothing isn't listed. It's empty on an event loaded from a save written before the field existed.

payments_gp class-attribute instance-attribute

payments_gp: tuple[int, ...] = ()

What each purse in payers paid, in gold pieces and in the same order. The entries sum to cost_gp.

HoardGeneratedEvent

Bases: Event

The engine rolled treasure and put it in a cache, before the party has found it.

Emitted when the party first enters an area whose author declared treasure, on the cell it enters, and when monsters the author placed in an area appear with their lair hoard, on the area's first cell. The goods go into a cache on that cell, which the party empties with TakeTreasure, passing the cache's id as feature_id while standing on the cell.

It has referee visibility, and it lists everything: telling the players would be telling them what is in the room. A referee front end, or an LLM running the game, reads it to know what is there.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'treasure.hoard.generated'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['hoard_generated'] = 'hoard_generated'

The event type, hoard_generated, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'treasure.hoard.generated'

The message code, always treasure.hoard.generated.

visibility class-attribute instance-attribute

Referee visibility: the party learns what the cache contains when it takes the treasure.

cache_ref instance-attribute

cache_ref: str

The id of the cache the treasure went into, like "cache-0001". Pass it as feature_id to TakeTreasure from the cache's cell.

treasure_types class-attribute instance-attribute

treasure_types: tuple[str, ...] = ()

The treasure-type letters that were rolled, one entry per roll, so a hoard rolled from two letters lists both. Treasure rolled on the unguarded-treasure table has ("unguarded",).

coins_gp_value class-attribute instance-attribute

coins_gp_value: int = 0

The coins in the hoard, as their value in gold pieces.

valuable_ids class-attribute instance-attribute

valuable_ids: tuple[str, ...] = ()

The session-scoped instance ids of the gems and jewellery in the hoard.

magic_item_ids class-attribute instance-attribute

magic_item_ids: tuple[str, ...] = ()

The session-scoped instance ids of the magic items in the hoard.

ItemAcquiredEvent

Bases: Event

Items or coins arrived in a character's inventory.

Emitted by TakeTreasure once per carrier who took a share, by PurchaseEquipment in town, and by the referee's GrantItem and GrantCoins.

It reports what changed hands, not what the character now carries. Read the inventory itself from GameSession.view when you need the full sheet.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.item.acquired'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['item_acquired'] = 'item_acquired'

The event type, item_acquired, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'exploration.item.acquired'

The message code, always exploration.item.acquired.

visibility class-attribute instance-attribute

Player visibility: the party knows what it picked up.

character_id instance-attribute

character_id: str

The member whose pack the goods went into.

item_ids class-attribute instance-attribute

item_ids: tuple[str, ...] = ()

What was acquired: a catalog id for mundane gear, and a session-scoped instance id for a valuable or a magic item, so an unidentified item's true nature stays hidden.

coins_gp_value class-attribute instance-attribute

coins_gp_value: int = 0

The coins acquired, converted to their value in gold pieces, and zero when only items changed hands.

origin class-attribute instance-attribute

origin: str | None = None

Where the goods came from: "treasure" for a share of a haul taken with TakeTreasure, "purchase" for gear bought with PurchaseEquipment, and "grant" for a referee's GrantItem or GrantCoins. Every command that emits this event fills it, so it is None only on an event loaded from a save written before the field existed.

ItemConsumedEvent

Bases: Event

An item a member carried was used up, like a key a gate takes or an iron spike.

Emitted when the party passes a gate that requires an item and takes it, which can happen on OpenDoor, ForceDoor, UseStairs, and a MoveParty through a passage. A gate is a condition the adventure's author puts on a door or a transition. Also emitted by WedgeDoor for the iron spike it drives.

It reports that the item is gone. A potion drunk or a scroll read is an ItemUsedEvent instead.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.item.consumed'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['item_consumed'] = 'item_consumed'

The event type, item_consumed, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'exploration.item.consumed'

The message code, always exploration.item.consumed.

visibility class-attribute instance-attribute

Player visibility: the party sees what it spent.

character_id instance-attribute

character_id: str

The member whose pack the item came out of.

item_id instance-attribute

item_id: str

What was consumed: the catalog id for mundane gear, and the session-scoped instance id for a magic item, never its template id, so an unidentified item's identity never reaches a player-visible event.

ItemIdentifiedEvent

Bases: Event

A magic item was identified, and the party now knows what it is.

Emitted the first time an item is used in a way that reveals it, which can happen in UseItem, EquipItem, and ResolveBattleRound, and when the referee identifies it with IdentifyItem.

Before this, player-visible events contain only the item's instance_id. After it, you can show the party the name of the item whose catalog id is template_id.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'items.item.identified'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['item_identified'] = 'item_identified'

The event type, item_identified, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'items.item.identified'

The message code, always items.item.identified.

visibility class-attribute instance-attribute

Player visibility: this is the moment the party learns what it has.

instance_id instance-attribute

instance_id: str

The session-scoped id of the item, the same id the earlier events contained.

template_id instance-attribute

template_id: str

What it turned out to be, as its magic item catalog id.

ItemUsedEvent

Bases: Event

A magic item was used: a potion drunk, a scroll read, a device fired.

Emitted by UseItem outside battle and by ResolveBattleRound for an item used in a battle. Whatever the item does follows in the same result as kernel events. A member can give a potion to another member to drink, and target_id is then the drinker's id.

Using an item for the first time identifies it, so an ItemIdentifiedEvent, and a CurseRevealedEvent for a cursed item, come just before this one. Using a device that has no charges left emits no event: the session refuses the command with items.device.inert, and the party loses nothing. Charges never appear on any event, because only the referee knows how many uses an item has left.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset(
    {"items.potion.drunk", "items.potion.mixed", "items.scroll.read", "items.scroll.cursed", "items.device.activated"}
)

items.potion.drunk for a potion taken on its own, items.potion.mixed when it meets another still in effect, which ends both and paralyses the drinker for three turns, items.scroll.read for a scroll, items.scroll.cursed for a cursed scroll, which curses its reader, and items.device.activated for a rod, staff, or wand.

event_type class-attribute instance-attribute

event_type: Literal['item_used'] = 'item_used'

The event type, item_used, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party watched it happen.

character_id instance-attribute

character_id: str

The member who used the item. For a potion, that's the member who carried it, whoever drank it.

instance_id instance-attribute

instance_id: str

The session-scoped id of the item used, never its catalog id, so an event about an item the party hasn't identified doesn't reveal what the item is.

manual class-attribute instance-attribute

manual: tuple[str, ...] = ()

The item's printed text, for an item whose effect the engine doesn't resolve, like a treasure map, or the curse's text for a cursed scroll whose curse the engine doesn't apply. A use of the staff of power or wizardry that strikes no group has the staff's text too, because the use is one of the staff's other powers, like the cone of cold. Empty when the engine resolved the effect itself, as it does a staff's strike. Show these lines to the players and rule on them yourself.

target_id class-attribute instance-attribute

target_id: str | None = None

The member who drank the potion, on items.potion.drunk and items.potion.mixed, when the member in character_id gave it to another member to drink. The potion's effect, and the sickness of mixed potions, land on this member.

It's None when the member who used the potion drank it, and on every other code. Name the drinker in UseItem.target_id, or in the one id of a use_item declaration's targets.

ItemsDroppedEvent

Bases: Event

Items or coins were dropped, onto the party's cell or behind it as bait.

Emitted by DropItems, and by Evade when the party drops its coins or its food to slow the monsters chasing it.

What is dropped goes into the drop pile on the party's cell, which TakeTreasure with feature_id="pile" picks back up. The exception is a drop made while fleeing: the drop of an Evade, or a DropItems during a chase. Those goods are left on the trail and are gone.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.item.dropped'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['items_dropped'] = 'items_dropped'

The event type, items_dropped, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'exploration.item.dropped'

The message code, always exploration.item.dropped.

visibility class-attribute instance-attribute

Player visibility: the party knows what it let go of.

character_id instance-attribute

character_id: str

The member who dropped them.

item_ids class-attribute instance-attribute

item_ids: tuple[str, ...] = ()

What was dropped, in the same id form the acquisition used: catalog ids for mundane gear, instance ids for valuables and magic items.

coins_gp_value class-attribute instance-attribute

coins_gp_value: int = 0

The coins dropped, as their value in gold pieces.

ItemsGivenEvent

Bases: Event

Items or coins passed from one party member to another.

Emitted by GiveItems, and by ResolveBattleRound for a give_item declaration, which hands over one item in the party's magic phase. Update both members' inventories on screen when it arrives. Nothing enters or leaves the party, so the party's total is unchanged.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.item.given'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['items_given'] = 'items_given'

The event type, items_given, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'exploration.item.given'

The message code, always exploration.item.given.

visibility class-attribute instance-attribute

Player visibility: the party arranged the handover.

character_id instance-attribute

character_id: str

The member who handed the goods over.

recipient_id instance-attribute

recipient_id: str

The member who took them.

item_ids class-attribute instance-attribute

item_ids: tuple[str, ...] = ()

What was handed over, as catalog ids for mundane gear and instance ids for valuables and magic items.

coins_gp_value class-attribute instance-attribute

coins_gp_value: int = 0

The coins handed over, as their value in gold pieces.

ItemsLeftBehindEvent

Bases: Event

Treasure the party could not carry, left lying where it was found.

Emitted by TakeTreasure when the haul is heavier than the carriers' remaining capacity.

Nothing is destroyed. The remainder goes into the drop pile on the party's cell, and a party that has made room can get the rest with a TakeTreasure whose feature_id is "pile".

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.item.left_behind'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['items_left_behind'] = 'items_left_behind'

The event type, items_left_behind, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'exploration.item.left_behind'

The message code, always exploration.item.left_behind.

visibility class-attribute instance-attribute

Player visibility: the party can see the pile it's walking away from.

item_ids class-attribute instance-attribute

item_ids: tuple[str, ...] = ()

What stayed behind, as catalog ids for mundane gear and instance ids for valuables and magic items.

coins_gp_value class-attribute instance-attribute

coins_gp_value: int = 0

The coins left behind, as their value in gold pieces.

ItemsRemovedEvent

Bases: Event

A referee took items or coins away from a party member.

Emitted by RemoveItem and RemoveCoins. What was removed has left the game, so update the member's inventory on screen. The event doesn't say why. The command does: read the source of the RemoveItem or RemoveCoins, either the one you executed or its entry in GameSession.command_log. When a trigger or a quest issued the command, source is its id.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.items.removed'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['items_removed'] = 'items_removed'

The event type, items_removed, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.items.removed'

The message code, always session.items.removed.

visibility class-attribute instance-attribute

Player visibility: the party knows what it no longer has.

character_id instance-attribute

character_id: str

The member who lost the items or coins.

item_ids class-attribute instance-attribute

item_ids: tuple[str, ...] = ()

The ids of what was removed: a mundane item's catalog id once for each unit, and the instance id of a magic item or a valuable. Empty for a removal of coins.

coins_gp_value class-attribute instance-attribute

coins_gp_value: int = 0

The coins removed, as their value in gold pieces. 0 for a removal of items.

JournalEntryAddedEvent

Bases: Event

A line of text was added to the session journal.

Emitted by AddJournalEntry. The journal is the party's record of the adventure. Lines are added in order and never changed, and the journal is part of what GameSession.view shows a player.

Quest text also goes into the journal, but its quest event reports it, like QuestActivatedEvent, with no JournalEntryAddedEvent, so the players aren't shown the same line twice. Read the whole journal from the view, and read these events to know when a line arrived.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.journal.entry_added'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['journal_entry_added'] = 'journal_entry_added'

The event type, journal_entry_added, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.journal.entry_added'

The message code, always session.journal.entry_added.

visibility class-attribute instance-attribute

Player visibility: the journal is written for the players.

text instance-attribute

text: str

The line as it was written. It came from your code or from the adventure, not from the engine.

rounds instance-attribute

rounds: int

Where the clock stood when the line was added, in rounds since the session began. The stored journal entry has the same number.

LightEvent

Bases: Event

A light source was lit, went out, failed to catch, or burned away.

Emitted by LightSource, ExtinguishSource, and UseItem for an item that glows. The session also emits the expiry form whenever a light runs out as time passes, which can happen inside any command that passes time.

Without light, the session refuses several commands with exploration.action.requires_light. Searching and listening at a door also work for a character with infravision. Picking a lock, handling a treasure trap, and reading a scroll need light. Read whether the party has light from GameSession.party_light rather than working it out from these events.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset(
    {"exploration.light.lit", "exploration.light.extinguished", "exploration.light.failed", "exploration.light.expired"}
)

exploration.light.lit when a source catches, .extinguished when it's put out on purpose, .failed when a tinder box doesn't catch, and .expired when a burning source runs out on the clock.

event_type class-attribute instance-attribute

event_type: Literal['light'] = 'light'

The event type, light, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party sees the light change. When a light burns out, the EffectExpiredEvent for it has referee visibility, and the session adds this event after it so the players learn of it.

character_id class-attribute instance-attribute

character_id: str | None = None

The member carrying the source, or None when the light belongs to no one in the party.

source instance-attribute

source: str

What is burning: "torch", "lantern", "oil" for a lit pool, "sword" for a blade that glows, or the effect kind for a light cast as a spell.

ListenedEvent

Bases: Event

Someone listened at a door, and either heard something or heard nothing.

Emitted by ListenAtDoor, after the referee-visibility DetectionRolledEvent that reports the die.

exploration.listen.heard means the listener heard monsters in the area past the door. When the party later meets those monsters, it can't be surprised.

exploration.listen.silent gives the party no information about what is there. Undead make no noise, and the session rolls the die whether or not anything is on the other side. Show it as "nothing heard", not as a sign that the way is clear.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.listen.heard', 'exploration.listen.silent'})

exploration.listen.heard when noise came through, exploration.listen.silent when none did.

event_type class-attribute instance-attribute

event_type: Literal['listened'] = 'listened'

The event type, listened, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: what a character heard is theirs to know, while the die behind it is not.

character_id instance-attribute

character_id: str

The member who listened.

direction instance-attribute

direction: str

The side of the party's cell that was listened at, as a lowercase Direction value.

LocationEnteredEvent

Bases: Event

The party crossed into a new area, level, dungeon, or town.

An area is a room or other region of a level that the adventure's author keyed with content. The session emits the event whenever the party's location changes at one of those four scales:

  • EnterDungeon reports a dungeon entry.
  • UseStairs, a passage crossed with MoveParty, and a trap that moves the party report a level entry when they change the level, or a dungeon entry when they change the dungeon.
  • Each of those also reports an area entry when the cell the party arrives on is in an area, and so does a MoveParty step into a different area.
  • TravelToTown reports a town entry.
  • PlaceParty, when a referee puts the party somewhere, reports a dungeon entry or a town entry.

Which fields are filled depends on the scale, because an area id is unique only within its level. An area entry has the area, its level number, and its dungeon. A level or dungeon entry has the dungeon in location_id and the level number beside it. A town entry has neither. A level or dungeon entry also records how the party got there, in via and, for a transition it took, transition_ref, so you can tell from the event alone whether the party climbed or descended. Use the event to change the screen's header, and read the text the party can see from GameSession.view.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.location.entered'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['location_entered'] = 'location_entered'

The event type, location_entered, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'exploration.location.entered'

The message code, always exploration.location.entered. The scale is in location_kind.

visibility class-attribute instance-attribute

Player visibility: arriving somewhere is the first thing the players are told.

location_kind instance-attribute

location_kind: str

Which scale was crossed: "area", "level", "dungeon", or "town".

location_id instance-attribute

location_id: str

What was entered: the area id for an area entry, the dungeon id for a level or dungeon entry, and "town" for the town.

level_number class-attribute instance-attribute

level_number: int | None = None

The level the party is on, for area, level, and dungeon entries, and None for town.

dungeon_id class-attribute instance-attribute

dungeon_id: str | None = None

The dungeon the area belongs to, filled on area entries only. On level and dungeon entries, location_id is already the dungeon id.

narrative class-attribute instance-attribute

narrative: str | None = None

The success text the adventure's author wrote on the gate the party passed, or None when there was no gate or no text. A gate is a condition the author puts on a door or a transition, like a key the party must have. The author wrote this text, not the engine, and format_message adds it after the line it builds from the code. A transition to another cell of the same level enters no new level, so its gate's text is on the PartyMovedEvent for the landing cell instead.

via class-attribute instance-attribute

via: str | None = None

How the party got there, on level and dungeon entries: the kind of the transition it took ("stairs_down", "stairs_up", "trapdoor", or "chute"), "passage" for a passage it walked through with MoveParty, "trap" for a trap that moved the party, like a chute, "entrance" for EnterDungeon, and "placed" for PlaceParty. It is None on area and town entries, and on an event loaded from a save written before the field existed.

transition_ref class-attribute instance-attribute

transition_ref: str | None = None

The cell of the authored transition the party took, as cell_ref gives it, so you can find the TransitionSpec and the gate on it. Filled on a level or dungeon entry made through UseStairs or through a passage, None otherwise. For a passage crossing, it refers to the passage's cell. That cell can also have stairs, and passages on its other sides, so find the passage with LevelSpec.passage_at and the direction of the MoveParty that crossed it.

LootDroppedEvent

Bases: Event

What the slain left behind went into the drop pile on the party's cell as the encounter ended.

Emitted by whatever ends the encounter, through end_encounter: a won battle, an EndEncounter, an evasion, an escape from a chase, or a turning. It comes after the MonsterDefeatedEvents and before the EncounterEndedEvent.

The loot is the treasure each slain monster carried, the shared treasure of a group whose members were all slain, and everything a slain NPC adventurer had: gear, coins, valuables, and magic items. Routed monsters take their treasure with them. An encounter where nothing drops emits no LootDroppedEvent.

The goods join any pile already on the cell. Show the pile on screen when this event arrives. PlayerView.piles has everything in it, and TakeTreasure with feature_id="pile" picks it up.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'encounter.loot.dropped'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['loot_dropped'] = 'loot_dropped'

The event type, loot_dropped, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'encounter.loot.dropped'

The message code, always encounter.loot.dropped.

visibility class-attribute instance-attribute

Player visibility: the party sees what the fallen left on the floor.

item_ids class-attribute instance-attribute

item_ids: tuple[str, ...] = ()

What went into the pile, as a catalog id for each unit of mundane gear and an instance id for each valuable and each magic item. An unidentified magic item has its instance id, so its true nature stays hidden.

coins_gp_value class-attribute instance-attribute

coins_gp_value: int = 0

The coins that went into the pile, as their value in gold pieces.

MemberAddedEvent

Bases: Event

A new member joined the party during play.

Emitted by AddMember. The member is already in the party, at the back of the marching order, so add them to the party on screen. Their full sheet is in the views, under character_id. The event doesn't say why they joined. The command does: read the source of the AddMember, either the one you executed or its entry in GameSession.command_log.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.member.added'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['member_added'] = 'member_added'

The event type, member_added, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.member.added'

The message code, always session.member.added.

visibility class-attribute instance-attribute

Player visibility: the players see who joins them.

character_id instance-attribute

character_id: str

The id the session gave the new member, like "character-0005". Later commands and events refer to the member by this id.

name instance-attribute

name: str

The new member's name, so you can show the event without looking up the party.

class_id instance-attribute

class_id: str

The new member's class id, like "fighter".

level instance-attribute

level: int

The new member's experience level when they joined.

MemberMovedEvent

Bases: Event

A party member moved by themselves on the range track, closing on a group or falling back.

The range track is how a battle measures distance. Each group stands at a distance from the party line, the place where the party stood when the encounter opened. Each member stands at an advance, in feet, forward of that line toward the monsters. Every member starts the battle on the line, at an advance of zero.

Emitted by ResolveBattleRound in the party's movement step, once for each member whose advance changes:

  • A member who declares move="close", with a move action or with an attack, moves at their own encounter movement rate toward the group they named. They stop 5' from that group, and they never come closer than 5' to another group that's still in the fight.
  • A member who makes a fighting_withdrawal or a retreat that not every declarer makes moves back alone, at half their encounter rate or their full rate. Their advance goes down, and it can go below zero, behind the line.

When the moves leave every member the monsters can see behind the line, the line moves back to the foremost of them at the end of the movement step, as BattleState.advance_feet describes. The session emits no event for that, and no distance between a member and a group changes.

The events come in two runs, each in marching order: the members who fall back first, then the members who close. A member who closes while already within 5' of the group doesn't move, and the session emits nothing for them. A formation move, a defensive move that every declarer makes, moves the groups instead of the members, so it emits GroupMovedEvents and none of these.

The event reports the member's advance right after their move, before the party line moves back, so it isn't always where the member stands once the round is over. Use it to narrate or animate the move. To draw where each member stands, read EncounterView.advance_feet and EncounterGroupView.member_distance_feet from the player view after the round.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'battle.member.moved'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['member_moved'] = 'member_moved'

The event type, member_moved, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'battle.member.moved'

The message code, always battle.member.moved.

visibility class-attribute instance-attribute

Player visibility: the party sees its own members move.

character_id instance-attribute

character_id: str

The member who moved, by party member id.

move instance-attribute

move: str

The move the member made: "close", "fighting_withdrawal", or "retreat", as they declared it in BattleDeclaration.move.

advance_feet instance-attribute

advance_feet: int

The member's advance right after the move, in feet forward of the party line. Zero is the line, and a negative value is behind it. When the party line moves back at the end of the movement step, every member's advance grows by the same amount, and this value isn't updated. Read EncounterView.advance_feet after the round for where the member stands.

group_id instance-attribute

group_id: str

The group distance_feet is measured to. For a close, it's the group the member closed on. For a fighting_withdrawal or a retreat, it's the group nearest the member after the move, among the groups that haven't fled and still have a living member. When two are equally near, it's the one that comes first in EncounterView.groups.

distance_feet instance-attribute

distance_feet: int

The member's distance to the group in group_id after the move, in feet. It's that group's distance from the party line minus advance_feet. At 5' or less, the member and the group can reach each other in melee.

MemberRemovedEvent

Bases: Event

A member left the party during play.

Emitted by RemoveMember. The member is already gone from the party and from the views, so take them off the party on screen. When given_to is set, the ItemsGivenEvent just before this event lists what that member took. The event doesn't say why the member left. The command does: read the source of the RemoveMember, either the one you executed or its entry in GameSession.command_log.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.member.removed'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['member_removed'] = 'member_removed'

The event type, member_removed, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.member.removed'

The message code, always session.member.removed.

visibility class-attribute instance-attribute

Player visibility: the players see who leaves them.

character_id instance-attribute

character_id: str

The id the member had, like "character-0002". The session never gives it to another member, so earlier events that name it still mean this character.

name instance-attribute

name: str

The member's name, so you can show the event without the member at hand.

given_to class-attribute instance-attribute

given_to: str | None = None

The id of the member who took everything the leaving member carried, or None when it all left the game with them.

MemberWithdrewEvent

Bases: Event

A member who fell back alone traded places in the marching order with the member they named.

Emitted by ResolveBattleRound in the party's movement step, right after the withdrawing member's MemberMovedEvent.

A member who makes a fighting withdrawal or a retreat alone can name another member in replacement_id. The two then trade places in the marching order, and the session emits this event. The trade moves nobody on the range track. It decides who stands in front among members at the same distance from a group who got there in the same round, and it's the marching order the party keeps after the battle.

The trade happens only when the withdrawing member's move happens, and only while both members are alive. A member who can no longer move when the movement step comes doesn't fall back, so they don't trade places either, and the session emits neither event.

Redraw a battle screen's marching order from this event, or read it again from PlayerView.party.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'battle.member.withdrew', 'battle.member.retreated'})

battle.member.withdrew for a fighting withdrawal and battle.member.retreated for a retreat.

event_type class-attribute instance-attribute

event_type: Literal['member_withdrew'] = 'member_withdrew'

The event type, member_withdrew, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party sees its own marching order change.

character_id instance-attribute

character_id: str

The member who fell back, by party member id. They now have the replacement's place in the marching order.

replacement_id instance-attribute

replacement_id: str

The member they named, by party member id. They now have the withdrawing member's place in the marching order.

MonsterDefeatedEvent

Bases: Event

One monster was defeated, with the experience it's worth.

Emitted when the encounter ends, once for each creature that was slain, ran away, or was turned, before the EncounterEndedEvent. A creature the party got away from without defeating has no event.

The session adds up their xp for the experience award. Under the default ruleset the award arrives as an AdventureXpAwardEvent when the party travels back to town. When Ruleset.xp_award_timing is set to award experience immediately, each survivor's XpAwardedEvent arrives at the end of the encounter instead, before the EncounterEndedEvent.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'battle.monster.defeated'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['monster_defeated'] = 'monster_defeated'

The event type, monster_defeated, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'battle.monster.defeated'

The message code, always battle.monster.defeated.

visibility class-attribute instance-attribute

Player visibility: the party sees them fall or flee.

monster_id instance-attribute

monster_id: str

The session id of the creature that was defeated.

template_id instance-attribute

template_id: str

What it was: a monster catalog id, or "npc:<class id>" for a defeated NPC adventurer.

outcome instance-attribute

outcome: str

How it was defeated: "slain", or "routed" when it ran away or was turned.

xp instance-attribute

xp: int

What it's worth: the monster catalog's printed award, or the level-based award for an NPC adventurer.

MonsterFledEvent

Bases: Event

A monster group fled the battle.

Emitted by ResolveBattleRound when a group fails its morale check and flees. When a battle opens, it's also emitted for a group whose morale is so low that it never fights at all.

When a cleric turns only some of a group, the turned members leave the group and flee as a new group, and group_id is the new group's id.

A fleeing group moves away each round. It has left the battle once it's more than FLEE_EXIT_FEET from the party. Its members still count as defeated for the experience award.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'battle.side.fled'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['monster_fled'] = 'monster_fled'

The event type, monster_fled, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party sees them break.

group_id instance-attribute

group_id: str

Which group broke, as its encounter group id.

MonstersLeftBehindEvent

Bases: Event

A group that ran left its helpless members lying where they were.

Emitted by ResolveBattleRound when a broken group has members who can't move, like those asleep, paralysed, or held.

The runners stay in the original group and go on fleeing. The ones left behind become a new group at the distance where the side broke, so the party can finish them, take what they carry, or walk past.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'battle.group.left_behind'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['monsters_left_behind'] = 'monsters_left_behind'

The event type, monsters_left_behind, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'battle.group.left_behind'

The message code, always battle.group.left_behind.

visibility class-attribute instance-attribute

Player visibility: the party can see who was abandoned.

group_id instance-attribute

group_id: str

The new group the helpless members were put into.

source_group_id instance-attribute

source_group_id: str

The group that ran off without them.

count instance-attribute

count: int

How many were left behind.

MonstersSpawnedEvent

Bases: Event

Monsters were put into the session by the referee.

Emitted by SpawnMonsters, first in its result. When no encounter is open, the events of the encounter's opening follow. When one is open, the monsters join it as a new group.

It has referee visibility, and it contains ids rather than a description. The party learns which monsters arrived from EncounterStartedEvent when the encounter opens, or from EncounterGroupJoinedEvent when the monsters join an open one.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.monsters.spawned'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['monsters_spawned'] = 'monsters_spawned'

The event type, monsters_spawned, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.monsters.spawned'

The message code, always session.monsters.spawned.

visibility class-attribute instance-attribute

Referee visibility: this is bookkeeping, not a moment in the fiction.

template_id instance-attribute

template_id: str

What was spawned, as a monster catalog id.

monster_ids instance-attribute

monster_ids: tuple[str, ...]

The session ids of the new instances, in spawn order. Every later event about those creatures refers to them by these ids.

NoteRecordedEvent

Bases: Event

A referee note was recorded, and no game state changed.

Emitted by RecordNote. The Interpreter uses it to leave a machine-written note in the log when a consequence can't be applied, and referees use it for their margin notes.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.note.recorded'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['note_recorded'] = 'note_recorded'

The event type, note_recorded, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.note.recorded'

The message code, always session.note.recorded.

visibility class-attribute instance-attribute

Referee visibility: a note is for the person running the game.

text instance-attribute

text: str

The note as it was written.

NpcPartySpawnedEvent

Bases: Event

The engine generated an NPC adventuring party and added it to the session.

Emitted by the referee's SpawnNpcParty and by a wandering roll that comes up adventurers, before the encounter opens.

It has referee visibility and contains the whole roster. What the party sees is the EncounterStartedEvent, which labels them as adventurers and contains a count. The party learns their classes and levels by talking or by fighting.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'encounter.npc_party.spawned'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['npc_party_spawned'] = 'npc_party_spawned'

The event type, npc_party_spawned, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'encounter.npc_party.spawned'

The message code, always encounter.npc_party.spawned.

visibility class-attribute instance-attribute

Referee visibility: the players see only the label and the count on the encounter event.

party_kind instance-attribute

party_kind: str

Which table the party was rolled from: "basic" or "expert".

npc_ids instance-attribute

npc_ids: tuple[str, ...]

The session ids of its members, in roster order. The other three tuples line up with this one.

class_ids instance-attribute

class_ids: tuple[str, ...]

Each member's class, as a class catalog id.

levels instance-attribute

levels: tuple[int, ...]

Each member's level.

alignment instance-attribute

alignment: str

The party's alignment, as a lowercase Alignment value.

ObjectiveCompletedEvent

Bases: Event

One objective of a quest is done.

Emitted by CompleteObjective. Completing a hidden objective also reveals it, with no ObjectiveRevealedEvent, so the players may learn of an objective first from this event.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.quest.objective_completed'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['objective_completed'] = 'objective_completed'

The event type, objective_completed, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.quest.objective_completed'

The message code, always session.quest.objective_completed.

visibility class-attribute instance-attribute

Player visibility: the party sees its progress.

quest_id instance-attribute

quest_id: str

The quest the objective belongs to.

quest_name class-attribute instance-attribute

quest_name: str = ''

The quest's display name. The engine always fills it. It's empty only on an event loaded from a save written before the field existed.

objective_id instance-attribute

objective_id: str

Which objective was completed.

name class-attribute instance-attribute

name: str = ''

The objective's display label: the name its author wrote, or its id when the author wrote none.

narrative class-attribute instance-attribute

narrative: str | None = None

The progress text the author wrote, or None. The journal has the same line.

ObjectiveRevealedEvent

Bases: Event

A hidden objective was revealed, so the party can now be told what it's asked to do.

Emitted by RevealObjective. An objective the author didn't mark hidden is visible from the start and never gets this event.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.quest.objective_revealed'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['objective_revealed'] = 'objective_revealed'

The event type, objective_revealed, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.quest.objective_revealed'

The message code, always session.quest.objective_revealed.

visibility class-attribute instance-attribute

Player visibility: the party is being told what to do.

quest_id instance-attribute

quest_id: str

The quest the objective belongs to.

quest_name class-attribute instance-attribute

quest_name: str = ''

The quest's display name, so you don't need the adventure to look it up. The engine always fills it. It's empty only on an event loaded from a save written before the field existed.

objective_id instance-attribute

objective_id: str

Which objective, as the id the adventure gave it.

name class-attribute instance-attribute

name: str = ''

The objective's display label: the name its author wrote, or its id when the author wrote none. Like quest_name, it's empty only on an event loaded from a save written before the field existed.

narrative class-attribute instance-attribute

narrative: str | None = None

The offer text the author wrote for this objective, or None. The journal has the same line.

PartyMovedEvent

Bases: Event

The party moved a cell or turned in place, with its new cell and facing.

Emitted by MoveParty with the cell it stepped into, and by TurnParty with the unchanged cell and the new facing. Redraw a first-person view from this event.

Two moves that leave the party's cell work differently:

  • A MoveParty through a passage, a TransitionSpec that the party walks through, emits it with the cell the party arrives on. When the passage leads to another level, this event comes after that level's LocationEnteredEvent.
  • A UseStairs to another cell of the same level emits it only when the gate on the stairs has success text. The event is for the landing cell, and its narrative contains the text.

A step that a wall, a closed door, or the edge of the map blocks emits no event. The session refuses the command with the rejection code exploration.move.blocked, and nothing in the game changes.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.party.moved', 'exploration.party.turned'})

exploration.party.moved for a step into a new cell, exploration.party.turned for a turn on the spot.

event_type class-attribute instance-attribute

event_type: Literal['party_moved'] = 'party_moved'

The event type, party_moved, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party knows where it stands.

x instance-attribute

x: int

The column the party is in after the step or turn, counting from zero at the level's west edge.

y instance-attribute

y: int

The row the party is in after the step or turn, counting from zero at the level's north edge.

facing instance-attribute

facing: str

The direction the party now faces, as the lowercase value of a Direction ("north", "east", "south", "west"). After a step, the party faces the way it went, so this changes on a step as well as on a turn. After a step through a passage, the party faces the way the adventure's author set for the passage's far side.

narrative class-attribute instance-attribute

narrative: str | None = None

The success text the adventure's author wrote on the gate of a transition that took the party to another cell of the same level, or None.

For a transition to another level, the text is on the LocationEnteredEvent instead. format_message adds it after the line it builds from the code.

PartyReorderedEvent

Bases: Event

The party has a new marching order.

Emitted by ReorderParty. Marching order is the order the members walk in, front first, so redraw the party on screen in this order when the event arrives. A member who withdraws or retreats in a battle also changes the order, and that change arrives as a MemberWithdrewEvent instead.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.party.reordered'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['party_reordered'] = 'party_reordered'

The event type, party_reordered, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'exploration.party.reordered'

The message code, always exploration.party.reordered.

visibility class-attribute instance-attribute

Player visibility: the players chose the order.

order instance-attribute

order: tuple[str, ...]

Every member's id in the new marching order, front first, the same list the command gave.

ProvisionsEvent

Bases: Event

A day passed, and a character either ate and drank or went without.

Emitted once per living member per kind whenever a day boundary passes, which can happen inside any command that passes time, and most often inside a Rest.

Going short adds a day to a count the session keeps for that member (see consume_provisions). Whether the count brings a penalty depends on Ruleset.deprivation_penalties, which is off by default. The adaptations register, the page that lists where osrlib settles an ambiguous rule or supplies a default, describes the penalties. In town nobody runs short.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.provisions.consumed', 'exploration.provisions.short'})

exploration.provisions.consumed when the day's food or water was there, exploration.provisions.short when it was not.

event_type class-attribute instance-attribute

event_type: Literal['provisions'] = 'provisions'

The event type, provisions, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party knows whether it ate and drank.

character_id instance-attribute

character_id: str

The member whose rations or water this was.

kind instance-attribute

kind: str

Which supply the event is about: "food" or "water". Each member gets one of each per day.

PursuitEvent

Bases: Event

One round of a chase: the gap, a distraction taken, an escape, or a capture.

Emitted by Evade for the first round of the chase. Each further round comes from Wait, to keep running, or DropItems, to drop something behind the party as it runs.

A capture opens battle at once. An escape or a distraction ends the encounter. A chase that lasts PURSUIT_ROUND_CAP rounds ends in an escape and tires the party out, which arrives as ExhaustionEvent.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset(
    {"encounter.pursuit.round", "encounter.pursuit.distracted", "encounter.pursuit.escaped", "encounter.pursuit.caught"}
)

encounter.pursuit.round for a round where the chase goes on, .distracted when dropped treasure or food stops the pursuers, .escaped when the party gets clear, and .caught when the pursuers close to arm's length and battle opens.

event_type class-attribute instance-attribute

event_type: Literal['pursuit'] = 'pursuit'

The event type, pursuit, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party can see how close the chase is.

round instance-attribute

round: int

Which round of the chase this is, counting from one.

gap_feet instance-attribute

gap_feet: int

How far ahead the party is, in feet, at the end of this round. It never goes below zero, and at five feet or less the pursuers have caught up.

QuestActivatedEvent

Bases: Event

A quest became active.

Emitted by ActivateQuest. A quest whose activate_when is None is active from the start of the session, with no command and no event.

It has player visibility, because the party knows the job it has taken on. The trigger that activated the quest stays hidden, like the trigger and flag events.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.quest.activated'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['quest_activated'] = 'quest_activated'

The event type, quest_activated, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.quest.activated'

The message code, always session.quest.activated.

visibility class-attribute instance-attribute

Player visibility: the party is being given the job.

quest_id instance-attribute

quest_id: str

Which quest, as the id the adventure gave it.

name instance-attribute

name: str

The quest's display name, so you don't need the adventure to show it.

narrative class-attribute instance-attribute

narrative: str | None = None

The offer text the author wrote, or None when there's none. The session adds the same line to the journal with no separate journal event, so the players see it once.

QuestCompletedEvent

Bases: Event

A quest is finished.

Emitted by CompleteQuest. Whether the quest is done is the referee's ruling: the engine checks that the quest is active, not that every objective was completed.

A quest's rewards arrive after this event, as the events of the commands that pay them. When the quest concludes the adventure, an AdventureCompletedEvent follows in the same result.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.quest.completed'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['quest_completed'] = 'quest_completed'

The event type, quest_completed, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.quest.completed'

The message code, always session.quest.completed.

visibility class-attribute instance-attribute

Player visibility: the party learns the quest is done.

quest_id instance-attribute

quest_id: str

Which quest was completed.

name instance-attribute

name: str

The quest's display name.

narrative class-attribute instance-attribute

narrative: str | None = None

The completion text the author wrote, or None. The journal has the same line.

RestedEvent

Bases: Event

A rest finished, or was interrupted before it could.

Emitted by Rest. The code says how the rest went: exploration.rest.rested for a rest that ran to its end, and exploration.rest.interrupted for one a wandering monster cut short.

A completed rest clears the penalty for going without rest, and counts toward recovering from exhaustion after a chase. A rest of a full day, 144 turns, also heals the party. An interrupted rest heals nobody. If the party rested at least one full turn (10 minutes of game time, or 60 rounds) before the monsters came, the rest still clears that penalty, and each full turn counts toward recovery.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.rest.rested', 'exploration.rest.interrupted'})

exploration.rest.rested when the rest ran to its end, exploration.rest.interrupted when a wandering encounter cut it short.

event_type class-attribute instance-attribute

event_type: Literal['rested'] = 'rested'

The event type, rested, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party knows whether it got its rest.

kind instance-attribute

kind: str

How long the party tried to rest: "turn" for the one-turn breather the dungeon rule calls for, "night", or "day".

SearchCompletedEvent

Bases: Event

A search of the party's cell finished, with whatever it turned up.

Emitted by Search, after the referee-visibility DetectionRolledEvent that reports the die. InspectTreasure emits it with exploration.search.nothing when the thief finds no trap. When the thief finds a trap, the session emits a TrapEvent instead.

An empty result means the searcher found nothing, which doesn't mean nothing is there. Each character gets one attempt per cell per kind of search, so another character may still find it.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.search.found', 'exploration.search.nothing'})

exploration.search.found when found is non-empty, exploration.search.nothing otherwise.

event_type class-attribute instance-attribute

event_type: Literal['search_completed'] = 'search_completed'

The event type, search_completed, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: what the search turned up is the party's to act on.

character_id instance-attribute

character_id: str

The member who searched.

kind instance-attribute

kind: str

What was searched for: "secret_doors", "room_traps", "construction", or "treasure_traps" for a treasure feature inspected by a thief.

found class-attribute instance-attribute

found: tuple[str, ...] = ()

What turned up, as references like "secret_door:north", "room_trap:<area id>", or "construction:<feature id>", and empty when nothing did. A room trap found through a door from the searched cell has the door's direction in a third segment, "room_trap:<area id>:<direction>", and one found inside the searched area has none. A found secret door becomes an ordinary door the party can see and use, and a found room trap no longer springs on the party.

SpellDeclaredEvent

Bases: Event

Somebody declared a spell, before anyone knows who acts first.

Emitted by ResolveBattleRound for each caster who declared one, party member or NPC alike, at the start of the round.

In B/X, spells are declared before initiative is rolled. A caster who takes damage before their turn loses the spell, and the other side knows what is coming. A lost spell arrives later in the round as a SpellDisruptedEvent.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'battle.spell.declared'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['spell_declared'] = 'spell_declared'

The event type, spell_declared, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'battle.spell.declared'

The message code, always battle.spell.declared.

visibility class-attribute instance-attribute

Player visibility: a declaration is made out loud.

caster_id instance-attribute

caster_id: str

Who is casting: a party member's id, or an NPC adventurer's.

spell_id instance-attribute

spell_id: str

Which spell was declared, as its catalog id.

reversed class-attribute instance-attribute

reversed: bool = False

Whether the reversed form was declared, for a spell that has one.

StanceChangedEvent

Bases: Event

The monsters' attitude toward the party changed.

Emitted when an encounter opens, with the first stance. Also emitted when Parley changes the monsters' mood, when an uncertain stance is rolled again on a later encounter round and changes, and when undead that TurnUndead failed to turn attack.

The 2d6 reaction roll behind a stance is a kernel event at referee visibility. An encounter whose stance the adventure's author fixed has no roll. What reaches the party is how the creatures are acting.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'encounter.stance.changed'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['stance_changed'] = 'stance_changed'

The event type, stance_changed, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'encounter.stance.changed'

The message code, always encounter.stance.changed.

visibility class-attribute instance-attribute

Player visibility: behavior is visible even when the roll behind it isn't.

stance instance-attribute

stance: str

How the monsters are acting now, as a ReactionResult value: "attacks", "hostile", "uncertain", "indifferent", or "friendly". An attacking stance opens battle in the same result.

SurpriseRolledEvent

Bases: Event

One side's surprise die, rolled in secret.

Emitted twice when an encounter opens, once for each side, before EncounterStartedEvent reports the outcomes to the players.

A side that can't be surprised doesn't roll, and its event has roll set to None. The party doesn't roll when it already heard the monsters through the door. The monsters don't roll when they know the party is coming, when they can see its light, or when they're wandering monsters, which know the dungeon. An NPC party met on a wandering check still rolls.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'encounter.surprise.rolled'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['surprise_rolled'] = 'surprise_rolled'

The event type, surprise_rolled, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'encounter.surprise.rolled'

The message code, always encounter.surprise.rolled.

visibility class-attribute instance-attribute

Referee visibility: the die is the referee's, and the result reaches the players through the encounter event.

side instance-attribute

side: str

Which side rolled: "party" or "monsters".

threshold instance-attribute

threshold: int

The number on a d6 at or under which that side is surprised. It's 2, except for a party without light that has a living member without infravision, where it's 3.

roll class-attribute instance-attribute

roll: int | None = None

The d6 that came up, or None when this side never had to roll.

surprised instance-attribute

surprised: bool

Whether this side was surprised.

TimeAdvancedEvent

Bases: Event

The referee moved the clock.

Emitted by AdvanceTime, after the events of the time that passed. Effects run out, lights burn out, and the session uses up provisions for each day crossed, and those events arrive in the same result. No wandering-monster check and no fatigue check runs: a referee moving the clock decides what happens.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.time.advanced'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['time_advanced'] = 'time_advanced'

The event type, time_advanced, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.time.advanced'

The message code, always session.time.advanced.

visibility class-attribute instance-attribute

Referee visibility: the players see what the time passing does, not the command that passed it.

n instance-attribute

n: int

How many units were asked for.

unit instance-attribute

unit: str

Which unit, as a lowercase TimeUnit value: "round", "turn", or "day".

rounds_total instance-attribute

rounds_total: int

Where the clock now stands, in rounds since the session began. It's the same number as GameSession.clock.rounds.

TrapEvent

Bases: Event

A trap sprang, was found, was removed, resisted removal, or was known and didn't spring.

Emitted by the commands that can set a trap off or look for one: MoveParty, UseStairs and EnterDungeon, which run the arrival cell's entry checks the same way a step does, OpenDoor and ForceDoor, Search, TakeTreasure, InspectTreasure, and RemoveTreasureTrap. A trap that fires resolves at once, so its saves and damage follow in the same result as kernel events.

A trap the party doesn't know about that fails to fire emits no TrapEvent. Its die goes only into the referee-visibility DetectionRolledEvent, so to the players an uneventful step looks like a step on safe ground.

What finding a trap does depends on the kind of trap. A found room trap never springs, whether the party enters its area or opens one of its doors: the party walks around the known pit and stands clear of the known blade, so the engine rolls no die for it and emits nothing more. A found treasure trap still gets its 2-in-6 roll when the party takes the treasure with TakeTreasure, unless a thief has removed it with RemoveTreasureTrap, because finding a treasure trap doesn't disarm it. That is why exploration.trap.safe, a known trap getting its chance and not springing, appears only for a treasure cache.

A thief who fails to remove a treasure trap springs it, unless Ruleset.failed_trap_removal_springs is off. With the flag off, the failure emits exploration.trap.removal_failed and the trap stays armed and found.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset(
    {
        "exploration.trap.sprung",
        "exploration.trap.safe",
        "exploration.trap.found",
        "exploration.trap.removed",
        "exploration.trap.removal_failed",
    }
)

exploration.trap.sprung when a trap goes off, .found when a search or inspection reveals one, .removed when a thief disarms one, .removal_failed when a thief fails to disarm one and it doesn't spring, and .safe when a trap the party already knows about got its chance and didn't fire, which only a treasure trap does. A failed removal gives .removal_failed only when Ruleset.failed_trap_removal_springs is off. Otherwise the trap springs.

event_type class-attribute instance-attribute

event_type: Literal['trap'] = 'trap'

The event type, trap, which identifies this class in serialized form.

visibility class-attribute instance-attribute

Player visibility: the party feels the trap go off, or sees the one it found.

trap_ref instance-attribute

trap_ref: str

Which trap this is, as "<dungeon id>:<level number>:<area or feature id>". The session stores the same reference in its lists of found, sprung, and removed traps, so a trap that has sprung or been removed stays that way.

character_id class-attribute instance-attribute

character_id: str | None = None

The member the event is about. For exploration.trap.sprung and exploration.trap.safe, it's the member who set the trap off: the one who forced the door, reached into the cache, or tried to remove the trap. For a trap that springs when the party enters its area or opens its door with OpenDoor, it's the first living member in marching order. It's set even when the trap hits the whole party. For exploration.trap.removed and exploration.trap.removal_failed, and for a treasure trap found with InspectTreasure, it's the thief who tried. For a room trap found with Search, it's the member who searched.

direction class-attribute instance-attribute

direction: str | None = None

The direction of the door a room trap was found through, from the searched cell, as a Direction value. Set for that find alone: it is None on a room trap found inside the searched area, on a treasure trap found on a cache, and on every code but exploration.trap.found.

TreasureSoldEvent

Bases: Event

Valuables were sold in town, and the coins are in the purse.

Emitted by SellTreasure, one event for each member whose valuables were sold. Gems and jewellery sell for their full listed value, so selling them neither adds to nor takes from the treasure the experience award counts.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'town.treasure.sold'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['treasure_sold'] = 'treasure_sold'

The event type, treasure_sold, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'town.treasure.sold'

The message code, always town.treasure.sold.

visibility class-attribute instance-attribute

Player visibility: the party made the sale.

character_id instance-attribute

character_id: str

The member who sold them and now has the coins.

instance_ids instance-attribute

instance_ids: tuple[str, ...]

The session-scoped ids of the valuables that were sold.

gp_value instance-attribute

gp_value: int

What they fetched, in gold pieces.

TriggerFiredEvent

Bases: Event

A trigger the adventure's author wrote fired.

A trigger is a rule the adventure's author wrote: when a given event happens, run given commands. Emitted by MarkTriggerFired every time it runs, including for a trigger that has fired before. The session keeps only whether a trigger has fired, and these events are the record of each firing.

It has referee visibility, because which trigger fired is part of how the adventure works, not part of the story the players see. Text the author wrote for the players goes in the journal and arrives as a JournalEntryAddedEvent or as one of the quest events.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.trigger.fired'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['trigger_fired'] = 'trigger_fired'

The event type, trigger_fired, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.trigger.fired'

The message code, always session.trigger.fired.

visibility class-attribute instance-attribute

Referee visibility: which triggers an adventure has is hidden from the players.

trigger_id instance-attribute

trigger_id: str

Which trigger fired, as the id the adventure gave it.

narrative class-attribute instance-attribute

narrative: str | None = None

The text the author wrote for this firing, or None. The author wrote it, not the engine, and format_message adds it after the line it builds from the code. This event has referee visibility, so the players don't see this text. Text meant for them belongs in the journal.

WanderingCheckEvent

Bases: Event

A wandering-monster check came due and the referee rolled for it.

Emitted by wandering_check, which the session runs every few turns while it's in exploring mode (see wandering_interval). Any command that passes those turns can emit it, most often MoveParty or Rest. When the check hits, the encounter opens in the same result, and the command passes no more time.

It has referee visibility because the party can't know a check was made. It knows only what it meets.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'exploration.wandering.checked'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['wandering_check'] = 'wandering_check'

The event type, wandering_check, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'exploration.wandering.checked'

The message code, always exploration.wandering.checked.

visibility class-attribute instance-attribute

Referee visibility: the referee makes the check in secret, and the party sees only what it produces.

chance instance-attribute

chance: int

The chance in six that the check needed, limited to the range 0 to 6. It's the level's chance, adjusted for noise, bright light, and a rest with hidden set.

roll class-attribute instance-attribute

roll: int | None = None

The d6 that was rolled, or None when the chance came out at zero and no die was rolled.

encounter instance-attribute

encounter: bool

Whether the check produced an encounter. When it did, the encounter's events follow in the same result.

XpAwardedEvent

Bases: Event

One character was awarded experience.

Emitted wherever an award is made: after the AdventureXpAwardEvent on TravelToTown, and by the referee's AwardXP. When the ruleset is set to award experience immediately, it's also emitted at the end of an encounter in which monsters were defeated, and by a TakeTreasure that takes coins, gems, or jewellery. When the award crosses a threshold, a CharacterLeveledUpEvent for the same member follows it at once.

allowed_codes class-attribute

allowed_codes: frozenset[str] = frozenset({'session.xp.awarded'})

The only message code this event uses.

event_type class-attribute instance-attribute

event_type: Literal['xp_awarded'] = 'xp_awarded'

The event type, xp_awarded, which identifies this class in serialized form.

code class-attribute instance-attribute

code: str = 'session.xp.awarded'

The message code, always session.xp.awarded.

visibility class-attribute instance-attribute

Player visibility: it goes on the character's sheet.

character_id instance-attribute

character_id: str

The member who received it.

award instance-attribute

award: int

The award as the session handed it over, before the character's adjustment.

modified_award instance-attribute

modified_award: int

The award after the class's prime-requisite adjustment, rounded down. The character gains this much, except when it would raise them two levels: one award raises a character at most one level, so their total stops one point short of the level after next and the rest is lost.

level_after instance-attribute

level_after: int

The member's level once the award was applied.

parse_any_event

parse_any_event(data: Mapping[str, object]) -> Event | None

Rebuild one serialized event, kernel or crawl, skipping types and codes this version doesn't define.

Call it on records that came out of an event's model_dump or out of a save's event log, like a log you are replaying, a stream you received over a network, or a file you are analyzing. load_game calls it for each entry in a save's event log, and keeps the raw record for an entry that returns None.

A newer osrlib can add event types, and message codes on an existing type, within the same schema version. For an event_type this version has no class for, or a well-formed code that the type's class doesn't list in allowed_codes, it returns None rather than raising, so a log from a newer osrlib still loads. Fields the class doesn't define are ignored. What you get back is an instance of the matching class, which you can pass to format_message like any other event.

Parameters:

Name Type Description Default
data Mapping[str, object]

One event as a mapping, from model_dump (in either Python or JSON mode) or from parsed JSON.

required

Returns:

Type Description
Event | None

The event, or None when its event_type belongs to no class in ALL_EVENT_CLASSES, or when its class doesn't define its code.

Raises:

Type Description
ContentValidationError

If the event type and code are known but the payload doesn't fit the class, like a record missing a required field or a code in the wrong format. The message includes pydantic's report.

Examples:

from osrlib.crawl.events import PartyMovedEvent, parse_any_event

event = PartyMovedEvent(code="exploration.party.moved", x=1, y=0, facing="east")
record = event.model_dump()
print(parse_any_event(record) == event)
# True

print(parse_any_event({"event_type": "teleported", "code": "exploration.party.teleported"}))
# None

print(parse_any_event({**record, "code": "exploration.party.teleported"}))
# None