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.
playeris for what the players learn.refereeis 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.
CRAWL_EVENT_CLASSES
module-attribute
CRAWL_EVENT_CLASSES: tuple[type[Event], ...] = (
PartyMovedEvent,
PartyReorderedEvent,
LocationEnteredEvent,
DoorEvent,
ListenedEvent,
DetectionRolledEvent,
SearchCompletedEvent,
TrapEvent,
ItemAcquiredEvent,
ItemConsumedEvent,
ItemsDroppedEvent,
ItemsLeftBehindEvent,
ItemsGivenEvent,
LightEvent,
RestedEvent,
FatigueEvent,
ProvisionsEvent,
WanderingCheckEvent,
EncounterStartedEvent,
EncounterGroupJoinedEvent,
SurpriseRolledEvent,
StanceChangedEvent,
EvasionEvent,
PursuitEvent,
ExhaustionEvent,
LootDroppedEvent,
EncounterEndedEvent,
BattleStartedEvent,
BattleRoundEvent,
SpellDeclaredEvent,
GroupMovedEvent,
MemberMovedEvent,
MemberWithdrewEvent,
MonsterFledEvent,
MonstersLeftBehindEvent,
MonsterDefeatedEvent,
BattleEndedEvent,
HoardGeneratedEvent,
ItemUsedEvent,
ItemIdentifiedEvent,
CurseRevealedEvent,
NpcPartySpawnedEvent,
AdventureXpAwardEvent,
TreasureSoldEvent,
HealingPurchasedEvent,
FlagSetEvent,
MonstersSpawnedEvent,
XpAwardedEvent,
CharacterLeveledUpEvent,
TimeAdvancedEvent,
GameOverEvent,
DiceRolledEvent,
TriggerFiredEvent,
JournalEntryAddedEvent,
NoteRecordedEvent,
QuestActivatedEvent,
ObjectiveRevealedEvent,
ObjectiveCompletedEvent,
QuestCompletedEvent,
AdventureCompletedEvent,
ItemsRemovedEvent,
MemberAddedEvent,
MemberRemovedEvent,
)
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: it's the party's ending.
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
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
visibility: Visibility = Visibility.PLAYER
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.
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
visibility: Visibility = Visibility.PLAYER
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: everyone knows which round it is.
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
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
visibility: Visibility = Visibility.PLAYER
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the new level goes on the character's sheet.
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the bearer learns about the curse when it takes hold.
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
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
visibility: Visibility = Visibility.REFEREE
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
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
visibility: Visibility = Visibility.REFEREE
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".
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
visibility: Visibility = Visibility.PLAYER
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.
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
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
visibility: Visibility = Visibility.PLAYER
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 anEndEncounter."departed": the party walked away from monsters that let it go, through anEndEncounter.
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
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
visibility: Visibility = Visibility.PLAYER
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
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.
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
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
visibility: Visibility = Visibility.PLAYER
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
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
visibility: Visibility = Visibility.PLAYER
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
visibility: Visibility = Visibility.PLAYER
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
visibility: Visibility = Visibility.PLAYER
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
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
visibility: Visibility = Visibility.REFEREE
Referee visibility: flags are bookkeeping that the players don't see.
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
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
visibility: Visibility = Visibility.PLAYER
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party watches them come on or draw off.
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
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
visibility: Visibility = Visibility.PLAYER
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".
payers
class-attribute
instance-attribute
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.
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
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
visibility: Visibility = Visibility.REFEREE
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
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
The session-scoped instance ids of the gems and jewellery 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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party knows what it picked up.
item_ids
class-attribute
instance-attribute
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party sees what it spent.
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
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
visibility: Visibility = Visibility.PLAYER
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
visibility: Visibility = Visibility.PLAYER
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
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party knows what it let go of.
item_ids
class-attribute
instance-attribute
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party arranged the handover.
item_ids
class-attribute
instance-attribute
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party can see the pile it's walking away from.
item_ids
class-attribute
instance-attribute
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party knows what it no longer has.
item_ids
class-attribute
instance-attribute
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
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
visibility: Visibility = Visibility.PLAYER
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
visibility: Visibility = Visibility.PLAYER
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
visibility: Visibility = Visibility.PLAYER
Player visibility: what a character heard is theirs to know, while the die behind it is not.
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:
EnterDungeonreports a dungeon entry.UseStairs, a passage crossed withMoveParty, 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
MovePartystep into a different area. TravelToTownreports 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
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
visibility: Visibility = Visibility.PLAYER
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party sees what the fallen left on the floor.
item_ids
class-attribute
instance-attribute
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
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
visibility: Visibility = Visibility.PLAYER
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.
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 amoveaction or with anattack, 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_withdrawalor aretreatthat 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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party sees its own members move.
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
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
visibility: Visibility = Visibility.PLAYER
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
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
visibility: Visibility = Visibility.PLAYER
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party sees them fall or flee.
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party sees them break.
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party can see who was abandoned.
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
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
visibility: Visibility = Visibility.REFEREE
Referee visibility: this is bookkeeping, not a moment in the fiction.
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
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
visibility: Visibility = Visibility.REFEREE
Referee visibility: a note is for the person running the game.
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
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
visibility: Visibility = Visibility.REFEREE
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
The session ids of its members, in roster order. The other three tuples line up with this one.
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party sees its progress.
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.
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party is being told what to do.
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.
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
MovePartythrough a passage, aTransitionSpecthat 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'sLocationEnteredEvent. - A
UseStairsto 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 itsnarrativecontains 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
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
visibility: Visibility = Visibility.PLAYER
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the players chose the order.
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party knows whether it ate and drank.
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party can see how close the chase is.
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party is being given the job.
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party learns the quest is done.
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
visibility: Visibility = Visibility.PLAYER
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
visibility: Visibility = Visibility.PLAYER
Player visibility: what the search turned up is the party's to act on.
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
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
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
visibility: Visibility = Visibility.PLAYER
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.
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
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
visibility: Visibility = Visibility.PLAYER
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
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
visibility: Visibility = Visibility.REFEREE
Referee visibility: the die is the referee's, and the result reaches the players through the encounter event.
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.
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
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
visibility: Visibility = Visibility.REFEREE
Referee visibility: the players see what the time passing does, not the command that passed it.
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
visibility: Visibility = Visibility.PLAYER
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: the party made the sale.
instance_ids
instance-attribute
The session-scoped ids of the valuables that were sold.
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
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
visibility: Visibility = Visibility.REFEREE
Referee visibility: which triggers an adventure has is hidden from the players.
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
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
visibility: Visibility = Visibility.REFEREE
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
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
visibility: Visibility = Visibility.PLAYER
Player visibility: it goes on the character's sheet.
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.
parse_any_event
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 |
required |
Returns:
| Type | Description |
|---|---|
Event | None
|
The event, or |
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