osrlib.crawl.commands
The command set: typed models, the discriminated union, and the result envelope.
Commands are the write API: build one and pass it to
GameSession.execute.
CommandResult is the envelope execute
returns: accepted, the kernel's Rejection
models verbatim, and the events. Commands mirror the event conventions exactly:
frozen pydantic models, a single-valued command_type Literal discriminator
(snake_case, schema-stable, additive-only), an
AnyCommand discriminated union, and
parse_command returning None on unknown
types.
Each command declares its legal session modes as an allowed_modes class
attribute; the session rejects a wrong-mode command with
session.command.wrong_mode. Referee commands are legal in every mode except
those that would resume play in a session that has ended, and are logged and
replayed like any other. Every command class documents its contract in three
sections: Modes: (the legal session modes), Rejections: (the rejection codes
it can return), and Events: (what it emits when accepted).
ALL_COMMAND_CLASSES
module-attribute
ALL_COMMAND_CLASSES: tuple[type[Command], ...] = (
MoveParty,
TurnParty,
ReorderParty,
OpenDoor,
CloseDoor,
ForceDoor,
WedgeDoor,
ListenAtDoor,
PickLock,
Search,
InspectTreasure,
RemoveTreasureTrap,
TakeTreasure,
DropItems,
GiveItems,
LightSource,
ExtinguishSource,
EquipItem,
UnequipItem,
Rest,
PrepareSpells,
LearnSpell,
CastSpell,
UseItem,
UseStairs,
EnterDungeon,
TravelToTown,
PurchaseEquipment,
SellTreasure,
PurchaseHealing,
Parley,
Evade,
EngageBattle,
Wait,
TurnUndead,
ResolveBattleRound,
GrantItem,
GrantCoins,
AwardXP,
SetFlag,
SpawnMonsters,
SpawnNpcParty,
SetDoorState,
PlaceParty,
AdvanceTime,
IdentifyItem,
RollDice,
MarkTriggerFired,
AddJournalEntry,
RecordNote,
ActivateQuest,
RevealObjective,
CompleteObjective,
CompleteQuest,
)
Every command class — the discriminated union's members, in a stable wire order.
CONSEQUENCE_COMMAND_CLASSES
module-attribute
CONSEQUENCE_COMMAND_CLASSES: tuple[type[Command], ...] = (
GrantItem,
GrantCoins,
AwardXP,
SetFlag,
SpawnMonsters,
SpawnNpcParty,
SetDoorState,
PlaceParty,
AdvanceTime,
)
The referee commands an adventure document may carry as authored consequences, in a stable wire order.
Referee commands sit outside the surface for one of three reasons:
MarkTriggerFired,AddJournalEntry,RecordNote,ActivateQuest,RevealObjective,CompleteObjective, andCompleteQuestare the vocabulary the trigger and quest interpreter writes its own bookkeeping in — it marks, journals, annotates, and advances quest state on the author's behalf, so an authored copy would double the record.IdentifyItemaddresses a magic item by its session-scoped instance id, which no document can know.RollDiceproduces a result no authored construct reads, so an authored roll would be a no-op that moved the adjudication stream.
The character_id of a grant or an award is a party selector in an authored
consequence — never a literal id, for the same unknowability reason IdentifyItem is
excluded; see osrlib.crawl.triggers for the selector
vocabulary.
AnyCommand
module-attribute
AnyCommand = Annotated[Union[*ALL_COMMAND_CLASSES,], Field(discriminator='command_type')]
Any command, discriminated by command_type.
ConsequenceCommand
module-attribute
ConsequenceCommand = Annotated[
GrantItem
| GrantCoins
| AwardXP
| SetFlag
| SpawnMonsters
| SpawnNpcParty
| SetDoorState
| PlaceParty
| AdvanceTime,
Field(discriminator="command_type"),
]
An authored consequence, discriminated by command_type — the sub-union over
CONSEQUENCE_COMMAND_CLASSES,
spelled out so a static type checker can read it. A document naming any other command
type fails to parse, which is the whole enforcement: typing a field with this union
needs no validator behind it.
ActivateQuest
Bases: Command
Referee: put an authored quest into play.
The first of the four commands that drive an adventure's quest state — a
per-quest status (inactive → active → completed) and, under it, a
revealed/complete pair per objective. That state is engine-owned session state
beside the flag store, and these four are its only writers, so a replay rebuilds
it by re-executing the log.
Quest and objective ids are a closed domain: they resolve against the
adventure's QuestSpecs, and an id no quest
spec holds is rejected. That is the deliberate opposite of
MarkTriggerFired's open trigger id:
a mark is bookkeeping a game may drive with ids from its own systems, while an
activated quest is projected into the player view with a name, an offer, and an
objective list — an id with no quest behind it has none of them.
An accepted activation appends the quest's offer beat to the journal when its
author wrote one, and the event carries the same line; the append emits no
JournalEntryAddedEvent, because
the lifecycle event is that beat's event. Quest state is monotonic, so only an
inactive quest activates. Referee commands are legal in every mode, terminal
modes included.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
session.command.unknown_quest—quest_idnames no quest of the adventure.session.command.quest_state— the quest is already active or already completed; the rejection names the quest and the state that refused it.
Events
QuestActivatedEvent with the
quest id, the quest's name, and the offer beat.
AddJournalEntry
Bases: Command
Referee: append an authored beat to the session journal.
The journal is the party's record of the adventure in order of discovery:
entries append, are never rewritten, and are never derived from other state, so
a beat outlives whatever produced it. Each entry is stamped with the clock
position it landed at, and
PlayerView.journal ships the entries as they
were written. Referee commands are legal in every mode, terminal modes included
— a closing beat lands after the adventure has concluded.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
None.
Events
JournalEntryAddedEvent with
the text and the clock position.
AdvanceTime
Bases: Command
Referee: advance the clock directly.
Referee commands are legal in every mode, terminal modes included — the clock a revival window is measured in keeps running after the party falls. Time passes with full bookkeeping — effect expiries, provisions on day boundaries — but no wandering cadence: the referee controls encounters.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
None.
Events
The span's bookkeeping events (effect expiries and their player-facing
light translations, provisions), then
TimeAdvancedEvent with the
total.
AwardXP
Bases: Command
Referee: apply an XP award to one character, outside the adventure award.
Referee commands are legal in every mode, terminal modes included — an adventure's rewards land after the session has concluded. The award applies the prime-requisite modifier and can trigger level gains.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
session.command.unknown_member—character_idnames no party member.
Events
XpAwardedEvent with the award, the
modified award, and the level after; when the award crosses a level
threshold, a
CharacterLeveledUpEvent
follows with the levels, the hit points gained, and the new title.
character_id
instance-attribute
character_id: str
In an authored consequence or reward, this field takes the party selectors
("@party", "@first"), expanded to literal member ids by the interpreter
before issue; issued directly, it must be a literal member id or the command
rejects.
BattleDeclaration
Bases: BaseModel
One party member's declared action for a battle round.
attack names a target group and optionally a wielded weapon (None is
unarmed); cast names the spell, mode, form, and targets; move is the
range-track intent; use_item covers thrown splash items against a group.
Turn undead resolves in the magic phase but is never disruptable — turning is
a class ability, not a spell.
CastSpell
Bases: Command
Cast a memorized spell outside battle (one round).
targets are entity ids, or cell: references for location-bound casts. In
encounter mode a hostile cast is opened through
EngageBattle and the first round's
declarations instead; in battle, casting is a declaration kind.
Modes
town, exploring
Rejections
session.command.wrong_mode— an encounter or battle is underway, or the game is over.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.magic.cast.unknown_spell—spell_idnames no spell.magic.cast.silenced_area— a silence effect covers the party's cell.magic.cast.unknown_target— a target reference resolves to nothing.magic.cast.not_memorized— no memorized copy (non-casters included).magic.cast.caster_incapacitated,magic.cast.caster_restrained,magic.cast.anti_magic_shell— the caster cannot cast right now.magic.cast.not_reversible—reversedon a spell with no reversed form.magic.cast.unknown_mode—modenames no mode of the spell.magic.cast.target_count— the wrong number of targets for the mode.magic.cast.out_of_range— a target lies beyond the spell's range.
Events
SpellCastEvent plus the spell's own
resolution — saving throws, damage, healing, effect attachments — each its
own event. One round passes.
CloseDoor
Bases: Command
Close an open door on one side of the party's cell (zero time).
The party must be exploring a dungeon (see
EnterDungeon).
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.exploration.door.no_door— no known door on that side of the cell.exploration.door.already_closed— the door is already closed.exploration.door.wedged— a wedged door cannot swing.
Events
DoorEvent with code
exploration.door.closed.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
Command
Bases: BaseModel
Base class for all commands.
Commands are frozen: they are requests, logged verbatim when accepted, never
mutated. Subclasses must keep extra="ignore" (the additive-schema contract)
and declare a single-valued command_type Literal plus their legal session
modes.
source
class-attribute
instance-attribute
An annotation naming the authored object — a trigger or quest id — or the game
system on whose behalf the command was issued. Execution never reads it: a stamped
command does exactly what the same command unstamped does. It is logged and replayed
with the command, so the log alone answers "why did this happen". Absent is None;
the empty string is not a value.
CommandResult
Bases: BaseModel
The execute envelope: accepted or rejected, with the events either way.
A rejected command consumes no RNG draws, no clock time, mutates nothing, and is excluded from the command log — its result carries the rejections and no events.
An accepted command's events carries the complete chain: the handler's own
events, plus everything the nested commands a listener issued logged while it
ran — each event exactly once, in log order — so a front end renders the whole
reaction from one envelope without reading session.event_log.
CompleteObjective
Bases: Command
Referee: mark one objective of an active quest done.
Completing surfaces a hidden objective on the way: an objective the party
finished before it was ever announced is revealed and complete in one step, with
no separate RevealObjective. Ids are
the closed domain ActivateQuest
documents.
Completing the last objective a quest's completion rule needs does not
complete the quest: CompleteQuest is its
own command, so whoever drives the quest layer decides when the rule is
satisfied. An accepted completion appends the objective's progress beat to the
journal when its author wrote one, and the event carries the same line; no
JournalEntryAddedEvent follows.
Referee commands are legal in every mode, terminal modes included.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
session.command.unknown_quest—quest_idnames no quest of the adventure.session.command.unknown_objective—objective_idnames no objective of that quest.session.command.quest_state— the quest is not active, or the objective is already complete; the rejection names the quest and the state that refused it.
Events
ObjectiveCompletedEvent with
the quest id, the objective id, and the objective's progress beat.
CompleteQuest
Bases: Command
Referee: finish an active quest — and, on the concluding quest, the adventure.
The quest must be active, and that is the whole test: the completion rule is
not checked here. Ruling a quest done is the referee's call, and an authored
quest layer is simply a disciplined issuer that checks the rule before issuing.
Ids are the closed domain
ActivateQuest documents.
Rewards are not this command's business: whoever completes the quest issues the
authored rewards afterwards as ordinary commands of their own, so a completion
driven by hand grants nothing and every reward that does land is a line in the
log. The completion appends the quest's completion beat to the journal when
its author wrote one, and the events carry the same line; no
JournalEntryAddedEvent follows.
The victory transition. Completing a quest whose spec carries
concludes_adventure from a non-terminal mode clears any open encounter and
battle — a concluded session holds no live play state — and switches the session
to victory. This is the one entrance to that mode. From a terminal mode
(game_over or victory) the quest still completes and still journals, but
nothing transitions and no adventure-completed event lands: an ended session
never ends again, so the record shows a fallen party finishing the job without
resurrecting the adventure around it. Referee commands are legal in every mode,
terminal modes included.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
session.command.unknown_quest—quest_idnames no quest of the adventure.session.command.quest_state— the quest is inactive or already completed; the rejection names the quest and the state that refused it.
Events
QuestCompletedEvent with the
quest id, the quest's name, and the completion beat, followed by
AdventureCompletedEvent
carrying the same beat when the quest concludes the adventure and the
session had not already ended.
DropItems
Bases: Command
Drop items and coins onto the party's cell (or the pursuit trail).
Each item_ids entry drops one unit (repeat an id for more). Legal while
exploring a dungeon and during an encounter — dropping treasure or food is the
pursuit-distraction move.
Modes
exploring, encounter
Rejections
session.command.wrong_mode— the session is in town, in battle, or over.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.items.curse.stuck— a revealed cursed item cannot be discarded.exploration.item.not_carried— the member lacks an item or the coins.encounter.none_active— defensive twin of the mode gate; not reachable through normal play.
Events
ItemsDroppedEvent with what
fell. In an encounter the round then closes — the monsters act per their
stance — or, mid-pursuit, a
PursuitEvent round resolves with the
drop as bait.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING, SessionMode.ENCOUNTER})
EngageBattle
Bases: Command
Open battle: every offensive action goes through here (except turn undead).
An encounter must be open. Monsters surprised at the encounter's start grant the party a free opening round; engaging mid-pursuit turns the party to fight at the current gap.
Modes
encounter
Rejections
session.command.wrong_mode— no encounter is open.encounter.none_active— defensive twin of the mode gate; not reachable through normal play.
Events
BattleStartedEvent; groups at
morale 2 rout at once
(MonsterFledEvent), and a battle
whose every group routs ends immediately
(BattleEndedEvent and the
encounter's conclusion).
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.ENCOUNTER})
command_type
class-attribute
instance-attribute
command_type: Literal['engage_battle'] = 'engage_battle'
EnterDungeon
Bases: Command
Travel from town to a dungeon's entrance and start exploring.
The party must be in town. Travel takes the adventure's authored cost in
turns; arrival places the party at the entrance and switches the session to
exploring. Departure also snapshots the party's treasure valuation — the
end-of-adventure XP award is the delta against it.
Modes
town
Rejections
session.command.wrong_mode— the party is not in town.session.command.unknown_location—dungeon_idnames no dungeon, or the dungeon has no entrance level.
Events
LocationEnteredEvent for the
dungeon, after the travel time's own events. Arrival runs the entrance
cell's entry checks (area treasure, room traps, keyed encounters), each
reporting its own events.
command_type
class-attribute
instance-attribute
command_type: Literal['enter_dungeon'] = 'enter_dungeon'
EquipItem
Bases: Command
Equip an item from a member's item list (zero time).
Legal in town and while exploring. Class armour and weapon policies validate
before anything changes. item_id is the magic item's instance id for a magic
item, or the catalog id for a mundane one, which has no per-instance id — a
shipped id (from load_equipment, see the
equipment id index) or one the adventure bundles, which no
index documents.
Modes
town, exploring
Rejections
session.command.wrong_mode— an encounter or battle is underway, or the game is over.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.exploration.item.not_carried— nothing by that id in the item list.items.equip.armour_forbidden,items.equip.armour_not_allowed,items.equip.shield_forbidden,items.equip.weapon_not_allowed,items.equip.weapon_forbidden— the class policy forbids it.items.equip.two_handed_with_shield— a two-handed weapon and a shield cannot pair.items.equip.not_equippable— potions, scrolls, ammunition, and plain gear without a combat use do not equip.items.equip.not_usable— the magic device is not usable by this class.items.ring.hands_full— two rings are already worn.
Events
Usually none. Equipping a worn magic item can attach its effects
(EffectAttachedEvent); a cursed
ring identifies and reveals at wearing
(ItemIdentifiedEvent,
CurseRevealedEvent).
Evade
Bases: Command
Flee the encounter (legal only before battle begins, RAW).
An encounter must be open. drop scatters distraction bait as the party runs:
treasure tempts intelligent monsters, food unintelligent ones. Only attacking
or hostile monsters pursue; outrunning them ends the encounter cleanly.
Modes
encounter
Rejections
session.command.wrong_mode— no encounter is open.encounter.none_active— defensive twin of the mode gate; not reachable through normal play.encounter.evade.already_evading— the pursuit is already running.encounter.evade.nothing_to_drop— no coins (fortreasure) or rations (forfood) to scatter.
Events
ItemsDroppedEvents for scattered
bait, then EvasionEvent with code
encounter.evasion.succeeded — the encounter ends
(EncounterEndedEvent) — or
encounter.evasion.pursuit, and
PursuitEvent rounds follow: escape,
exhaustion at the round cap, or battle at the party's heels.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.ENCOUNTER})
ExtinguishSource
Bases: Command
Extinguish the bearer's burning source, forfeiting the remainder (zero time).
Legal in town and while exploring. A doused torch or lantern is spent — the remaining burn time does not bank.
Modes
town, exploring
Rejections
session.command.wrong_mode— an encounter or battle is underway, or the game is over.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.exploration.light.not_burning— the member carries no burning torch or lantern.
Events
An EffectReleasedEvent and a
LightEvent with code
exploration.light.extinguished per doused source.
command_type
class-attribute
instance-attribute
command_type: Literal['extinguish_source'] = 'extinguish_source'
ForceDoor
Bases: Command
Force a stuck door: the character's STR open-doors check; noise is the cost.
The party must be exploring a dungeon (see
EnterDungeon). Any attempt bangs on the
door — the next wandering check takes the noise bonus — and a failed attempt
alerts the room beyond, denying the party surprise there. A successful force
is an opening: an unfound open-trigger room trap on either adjoining area
gets its 2-in-6 spring check, and the forcing character is the one it lands
on — or the next member standing, if an earlier spring felled them.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.exploration.door.no_door— no known door on that side of the cell.exploration.door.already_open— the door already stands open.exploration.door.locked— locked doors needPickLock, not muscle.exploration.door.not_stuck— an unstuck door opens withOpenDoor.exploration.door.gate_refused— the door carries an authored condition (GateSpec) the party does not satisfy. Checked before the shoulder ever hits the door: a gate-refused forcing makes no noise, denies no surprise, and rolls nothing.
Events
ItemConsumedEvent first when the
gate's condition consumes what it asks for, then
DoorEvent with code
exploration.door.forced on success (carrying the gate's success text when
its author wrote one) or exploration.door.stuck on failure, then the trap
events when a door trap's spring check runs.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
GiveItems
Bases: Command
Hand items and coins from one party member to another (zero time).
The distribute-the-load move: character_id is the giver, recipient_id the
companion who takes the goods. Each item_ids entry gives one unit (repeat an
id for more); a given magic item releases any worn effects first and lands
unequipped in the recipient's pack. Legal in town and while exploring — not
mid-encounter or in battle. Both members must be able-bodied.
Modes
town, exploring
Rejections
session.command.wrong_mode— an encounter or battle is underway, or the game is over.session.command.unknown_member—character_idorrecipient_idnames no party member.session.command.member_incapacitated— the giver or recipient cannot act.exploration.give.same_member— giver and recipient are the same member.items.curse.stuck— a revealed cursed item cannot be handed off.exploration.item.not_carried— the giver lacks an item or the coins.
Events
ItemsGivenEvent with what changed
hands. A worn magic item's effects release
(EffectReleasedEvent).
GrantCoins
Bases: Command
Referee: place coins directly into a member's purse.
Referee commands are legal in every mode, terminal modes included.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
session.command.unknown_member—character_idnames no party member.
Events
ItemAcquiredEvent with the coin
value.
command_type
class-attribute
instance-attribute
command_type: Literal['grant_coins'] = 'grant_coins'
character_id
instance-attribute
character_id: str
In an authored consequence or reward, this field takes the party selectors
("@party", "@first"), expanded to literal member ids by the interpreter
before issue; issued directly, it must be a literal member id or the command
rejects.
GrantItem
Bases: Command
Referee: place an item directly into a member's inventory.
Referee commands are legal in every mode, terminal modes included, and are logged and replayed like any other.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
session.command.unknown_member—character_idnames no party member.session.command.unknown_item—item_idnames no item in the session'seffective_equipmentcatalog: neither a shipped id nor one the adventure bundles.
Events
ItemAcquiredEvent with the
granted items.
character_id
instance-attribute
character_id: str
In an authored consequence or reward, this field takes the party selectors
("@party", "@first"), expanded to literal member ids by the interpreter
before issue; issued directly, it must be a literal member id or the command
rejects.
IdentifyItem
Bases: Command
Referee: identify a magic item outright — game-driven identification.
Referee commands are legal in every mode, terminal modes included, and are logged and replayed like any other.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
session.command.unknown_member—character_idnames no party member.session.command.unknown_item— the member carries no magic item with that instance id.
Events
ItemIdentifiedEvent; a cursed
item also reveals with a
CurseRevealedEvent.
InspectTreasure
Bases: Command
Search a treasure feature for a treasure trap: thief-only, one turn.
The party must be exploring a dungeon (see
EnterDungeon), with light. One attempt
per character per feature.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.exploration.trap.not_a_thief— the member has no thief skills.exploration.feature.unknown—feature_idnames no treasure cache on this cell.exploration.action.requires_light— inspecting needs real light.exploration.search.already_tried— this character already inspected this feature.
Events
DetectionRolledEvent with the
skill roll, then a TrapEvent with code
exploration.trap.found or a
SearchCompletedEvent
reporting nothing. One turn passes with its usual follow-on events.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
command_type
class-attribute
instance-attribute
command_type: Literal['inspect_treasure'] = 'inspect_treasure'
LearnSpell
Bases: Command
Add a spell to an arcane caster's spell book — leveling or mentoring made concrete.
Legal in town and while exploring. The book holds, per spell level, at most the caster's current slot count at that level, and it never shrinks — a drained caster's book may sit over capacity, taking nothing more until capacity catches up. No game time passes: the fiction around the learning (the mentor's week, a copied scroll's costs) belongs to the game.
Modes
town, exploring
Rejections
session.command.wrong_mode— an encounter or battle is underway, or the game is over.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.magic.book.not_arcane— the class keeps no spell book.magic.book.unknown_spell—spell_idnames no spell.magic.book.wrong_list— the spell is off the caster's spell list.magic.book.duplicate— the book already holds the spell.magic.book.capacity_exceeded— no open slot at the spell's level.
Events
SpellBookUpdatedEvent with
the added spell. No game time passes.
command_type
class-attribute
instance-attribute
command_type: Literal['learn_spell'] = 'learn_spell'
LightSource
Bases: Command
Light a torch or lantern, or ignite dropped oil (one round).
Legal in town and while exploring. Without an open flame already burning in
the party, the bearer needs a tinder box, and striking it is a 2-in-6 chance —
the round is spent per attempt (RAW). Lighting an oil_flask ignites a flask
previously dropped on the party's cell as a burning pool.
Modes
town, exploring
Rejections
session.command.wrong_mode— an encounter or battle is underway, or the game is over.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.exploration.light.not_a_source—item_idis nottorch,lantern, oroil_flask.exploration.item.not_carried— the member lacks the source (or oil for the lantern), or no dropped flask lies on the cell.exploration.light.no_flame— no open flame and no tinder box.
Events
LightEvent with code
exploration.light.lit — an
EffectAttachedEvent carries the
burn-down effect — or exploration.light.failed when the tinder does not
catch. One round passes.
command_type
class-attribute
instance-attribute
command_type: Literal['light_source'] = 'light_source'
ListenAtDoor
Bases: Command
Listen at a door: once per character per door, ever (zero time).
The party must be exploring a dungeon (see
EnterDungeon), and the listener needs
light (infravision suffices). Hearing occupants marks the party aware for the
room's eventual encounter.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.exploration.door.no_door— no known door on that side of the cell.exploration.action.requires_light— the party is in the dark and the listener lacks infravision.exploration.listen.already_tried— this character has already listened at this door.
Events
DetectionRolledEvent with the
roll, then ListenedEvent with code
exploration.listen.heard or exploration.listen.silent.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
command_type
class-attribute
instance-attribute
command_type: Literal['listen_at_door'] = 'listen_at_door'
MarkTriggerFired
Bases: Command
Referee: record that an authored trigger has fired.
One of the lifecycle commands a trigger-and-quest interpreter, a game's own listener, or an LLM referee drives: the mark goes in before the trigger's consequences issue, so fired-state is what answers once-only semantics, and it survives save, load, and replay like any other session state. Referee commands are legal in every mode, terminal modes included. Marking an already-marked trigger is accepted and changes nothing: session state records that a trigger has fired, while each mark in the command log records one firing.
trigger_id is an open domain: a mark records that something fired, needs no
authored trigger behind it, and a game drives it with ids from its own systems.
The quest lifecycle commands invert that deliberately —
ActivateQuest and its three siblings
resolve their ids against the adventure's quest specs, because the state they
advance is projected into the player view and an id with no spec behind it has
nothing to show.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
None.
Events
TriggerFiredEvent with the
trigger id and the beat, for every mark.
command_type
class-attribute
instance-attribute
command_type: Literal['mark_trigger_fired'] = 'mark_trigger_fired'
narrative
class-attribute
instance-attribute
The authored beat for the firing, carried out on the event at referee
visibility. Trigger internals are the game's secret, so this is the referee's
line about the wiring; the players' line is a journal entry
(AddJournalEntry). Authored text on a
command is content data in a structured field — the command still carries its
type and its facts.
MoveParty
Bases: Command
Move the party one cell; facing follows the movement direction.
The party must already be inside a dungeon: a fresh session starts in town, and
EnterDungeon is what places the party at
the entrance and switches the session to exploring.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.exploration.move.cannot_move— the party cannot move: it is overloaded, or a living member is unable to walk.exploration.move.blocked— a wall, a closed or secret door, or the map edge blocks that direction.
Events
PartyMovedEvent with the new position
and facing. Entering a new cell can also trigger area descriptions, keyed
encounters, traps, treasure discovery, wandering-monster checks, light
burn-down, and doors swinging shut, each reported by its own event.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
OpenDoor
Bases: Command
Open an unstuck, unlocked door on one side of the party's cell (zero time).
The party must be exploring a dungeon (see
EnterDungeon). An undiscovered secret
door rejects exactly like blank wall — commands never leak hidden geometry.
Opening a door of an area whose room trap triggers on open is the trap's
springing action: 2-in-6 to spring on the first living member in marching
order, unless the trap has already been found.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.exploration.door.no_door— no known door on that side of the cell (undiscovered secret doors included).exploration.door.already_open— the door already stands open.exploration.door.locked— the lock has not been picked or otherwise undone.exploration.door.stuck— a stuck door needsForceDoor.exploration.door.gate_refused— the door carries an authored condition (GateSpec) the party does not satisfy; the refusal carries the author's own text. Checked last, after every other refusal, so it fires only when the gate alone bars the way.
Events
ItemConsumedEvent first when the
gate's condition consumes what it asks for, then
DoorEvent with code
exploration.door.opened (carrying the gate's success text when its author
wrote one), then the trap events when a door trap's spring check runs.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
Parley
Bases: Command
Speak with the monsters: a fresh reaction roll with the speaker's CHA modifier.
An encounter must be open — encounters begin from wandering checks, keyed areas, or the referee spawn commands. Any number of re-rolls is legal; a hostile turn self-limits the conversation.
Modes
encounter
Rejections
session.command.wrong_mode— no encounter is open.encounter.none_active— defensive twin of the mode gate; not reachable through normal play.encounter.parley.mid_pursuit— no talking while being chased.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the speaker cannot act.
Events
ReactionRolledEvent, and a
StanceChangedEvent when the
stance shifts. An attacks result opens battle at once
(BattleStartedEvent and what
follows); otherwise the encounter round closes with the monsters' beat.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.ENCOUNTER})
PickLock
Bases: Command
Pick a locked door's lock: thief-only, needs thieves' tools, one turn.
The party must be exploring a dungeon (see
EnterDungeon). A failed attempt locks
that character out of that lock until the next level gain.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.exploration.lock.not_a_thief— the member has no thief skills.exploration.lock.no_tools— the member carries no thieves' tools.exploration.door.no_door— no known door on that side of the cell.exploration.lock.not_locked— the door has no lock left to pick.exploration.action.requires_light— picking needs real light; infravision does not suffice.exploration.lock.locked_out— this character already failed here at their current level.
Events
DetectionRolledEvent with the
skill roll and, on success, a DoorEvent
with code exploration.door.unlocked. The attempt costs one turn, whose
bookkeeping (light burn-down, the rest cadence, wandering checks) reports
through its own events.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
PlaceParty
Bases: Command
Referee: teleport the party to a location.
The party cannot be teleported out of an open encounter or battle. Placing
into a dungeon marks the cell explored and switches the session to
exploring; placing in town switches it to town. That switch is play
resuming, which is why this is the one referee command a concluded adventure
withholds: it is illegal in victory. It stays legal in game_over, where it
is the salvage door — carrying the fallen party to town is the first step of
the revival flow that ends at
PurchaseHealing's raise_dead.
Modes
town, exploring, encounter, battle, game_over
Rejections
session.command.encounter_in_progress— an encounter or battle is open.session.command.unknown_location— the location names no dungeon level.session.command.out_of_bounds— the position is off the level's grid.
Events
LocationEnteredEvent for the
destination.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = _ALL_MODES - frozenset({SessionMode.VICTORY})
command_type
class-attribute
instance-attribute
command_type: Literal['place_party'] = 'place_party'
PrepareSpells
Bases: Command
Prepare a caster's daily spells: once per sleep, after an uninterrupted night, six turns.
Legal in town and while exploring. The caster must have slept (a night or day
Rest) since the last preparation; the
selections replace the memorized list wholesale.
Modes
town, exploring
Rejections
session.command.wrong_mode— an encounter or battle is underway, or the game is over.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.magic.memorize.needs_sleep— no sleep since the last preparation.magic.memorize.not_a_caster— the class casts no spells.magic.memorize.unknown_spell— a selection names no known spell.magic.memorize.wrong_list— a selection is off the caster's spell list.magic.memorize.divine_reverses_at_cast— divine casters choose the reversed form at casting, not at prayer.magic.memorize.not_in_book— an arcane selection is missing from the spell book.magic.memorize.not_reversible— a reversed selection has no reversed form.magic.memorize.slots_exceeded— more selections at some spell level than the caster has slots.
Events
SpellsMemorizedEvent with the
prepared list. Six turns pass with their usual follow-on events.
command_type
class-attribute
instance-attribute
command_type: Literal['prepare_spells'] = 'prepare_spells'
PurchaseEquipment
Bases: Command
Buy equipment in town: each item_ids entry buys one purchase lot (zero time).
The party must be in town. The whole basket prices first; if the member cannot
afford the total, nothing is bought. The shop stocks the shipped equipment
lists (load_equipment — see the equipment id
index) and nothing else: an item the adventure bundles is
not for sale, however the party came by the id, and rejects as unstocked
rather than as unknown.
Modes
town
Rejections
session.command.wrong_mode— the party is not in town.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.session.command.unknown_item— an entry names no equipment item at all.items.purchase.not_stocked— an entry names an item the adventure bundles; the shop does not carry it.items.purchase.insufficient_funds— the purse cannot cover the total.
Events
ItemAcquiredEvent listing the
purchases.
command_type
class-attribute
instance-attribute
command_type: Literal['purchase_equipment'] = 'purchase_equipment'
PurchaseHealing
Bases: Command
Buy a temple healing service in town (zero time).
The party must be in town. The service list and prices are a documented adaptation — the OSE SRD's base-town material is prose: cure light wounds 25 gp, cure serious wounds 100 gp, cure disease 150 gp, neutralize poison 150 gp, remove curse 200 gp, raise dead 1,500 gp. Each resolves through the kernel spell path with an abstract temple cleric at the minimum level able to cast the spell; the named character is the target and pays from their own purse.
Modes
town
Rejections
session.command.wrong_mode— the party is not in town.session.command.unknown_member—character_idnames no party member.items.purchase.insufficient_funds— the character's purse cannot cover the service.
Events
HealingPurchasedEvent, then
the service spell's own resolution events (healing, effect releases, a
revival's outcome).
RecordNote
Bases: Command
Referee: record an annotation in the logs, with no state effect at all.
The note lands as a referee-visibility event and touches nothing: it is the mechanism for machine-issued records — a consequence that was dropped, a cascade that was cut short — and for a referee's own margin notes alike. Referee commands are legal in every mode, terminal modes included.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
None.
Events
NoteRecordedEvent with the text.
RemoveTreasureTrap
Bases: Command
Remove a found treasure trap: thief-only, one turn; failure springs it.
The party must be exploring a dungeon (see
EnterDungeon), with light, and the trap
must already have been found by
InspectTreasure.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.exploration.trap.not_a_thief— the member has no thief skills.exploration.feature.unknown—feature_idnames no trapped feature on this cell.exploration.trap.not_found— the trap has not been found yet.exploration.trap.already_resolved— the trap was already removed or has already sprung.exploration.action.requires_light— removal needs real light.exploration.search.already_tried— this character already attempted the removal.
Events
DetectionRolledEvent with the
skill roll, then a TrapEvent:
exploration.trap.removed on success, exploration.trap.sprung on failure
— the sprung trap resolves at once against the thief (saving throws,
damage, conditions, each its own event). One turn passes.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
command_type
class-attribute
instance-attribute
command_type: Literal['remove_treasure_trap'] = 'remove_treasure_trap'
ReorderParty
Bases: Command
Rewrite the marching order — the only way marching order changes.
Legal in town and while exploring; the order is locked once an encounter or battle has begun.
Modes
town, exploring
Rejections
session.command.wrong_mode— an encounter or battle is underway, or the game is over.exploration.party.bad_order—orderdoes not name exactly the current members, each once.
Events
None. An accepted reorder changes state silently.
ResolveBattleRound
Bases: Command
Resolve one battle round: one declaration per living, able party member.
A battle must be underway (see
EngageBattle). Validation is the pure
pre-phase: every declaration validates or the whole command rejects listing
every rejection — partial acceptance would tangle the replay contract.
Modes
battle
Rejections
session.command.wrong_mode— no battle is underway.battle.none_active— defensive twin of the mode gate; not reachable through normal play.battle.declaration.roster_mismatch— the declarations do not name exactly the living, able members.battle.declaration.unknown_action— an unrecognizedaction.- Move declarations:
battle.declaration.missing_move,battle.declaration.unknown_group,battle.declaration.cannot_move. - Attack declarations:
battle.declaration.unknown_group,battle.declaration.no_target,battle.declaration.weapon_not_wielded,battle.declaration.not_in_front_rank, and the kernel attack checks —combat.attack.out_of_reach,combat.attack.out_of_range,combat.attack.reload,combat.attack.attacker_incapacitated,combat.attack.attacker_blind. - Cast declarations:
battle.declaration.missing_spell,battle.declaration.unknown_group,battle.declaration.invisible_target, and the cast checks —magic.cast.unknown_spell,magic.cast.silenced_area,magic.cast.unknown_mode,magic.cast.unknown_target,magic.cast.not_memorized,magic.cast.caster_incapacitated,magic.cast.caster_restrained,magic.cast.anti_magic_shell,magic.cast.not_reversible,magic.cast.target_count,magic.cast.out_of_range. - Turn-undead declarations:
magic.turning.not_a_turner,magic.turning.caster_incapacitated. - Item declarations:
battle.declaration.item_unusable,battle.declaration.unknown_group,battle.declaration.no_target,items.use.not_usable,items.device.inert,items.scroll.spent,items.scroll.no_such_spell,items.scroll.wrong_caster,exploration.action.requires_light,combat.attack.out_of_reach.
Events
BattleRoundEvent opens the round;
declared casts post as
SpellDeclaredEvents;
InitiativeRolledEvent orders
the sides. The phases then report themselves — movement, missiles, magic,
melee: attack and damage rolls, saving throws, casts and disruptions,
morale checks, routs and defeats — each its own event. A terminal round
appends BattleEndedEvent and the
encounter's conclusion, or
GameOverEvent on a party wipe.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.BATTLE})
command_type
class-attribute
instance-attribute
command_type: Literal['resolve_battle_round'] = 'resolve_battle_round'
Rest
Bases: Command
Rest: one turn (the cadence rest), a night (48 turns), or a full day (144).
Legal in town and while exploring. In the dungeon a wandering encounter can interrupt the rest; a full day of rest also applies natural healing.
Modes
town, exploring
Rejections
session.command.wrong_mode— an encounter or battle is underway, or the game is over.
Events
RestedEvent with code
exploration.rest.rested, or exploration.rest.interrupted when a
wandering encounter breaks the rest. Clearing fatigue or exhaustion reports
a FatigueEvent or
ExhaustionEvent; a full day's
natural healing an
HealingAppliedEvent. The
elapsed turns report their own bookkeeping (light burn-down, provisions,
wandering checks).
RevealObjective
Bases: Command
Referee: surface a hidden objective of an active quest.
A hidden objective is absent from the player view until it is revealed or until
it completes — completing an objective reveals it, so a quest whose hidden
objective simply lands needs no reveal at all. Ids are the closed domain
ActivateQuest documents.
An accepted reveal appends the objective's offer beat to the journal when its
author wrote one, and the event carries the same line; no
JournalEntryAddedEvent follows,
because the lifecycle event is that beat's event. Referee commands are legal in
every mode, terminal modes included.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
session.command.unknown_quest—quest_idnames no quest of the adventure.session.command.unknown_objective—objective_idnames no objective of that quest.session.command.quest_state— the quest is not active, or the objective is already visible or already complete; the rejection names the quest and the state that refused it.
Events
ObjectiveRevealedEvent with
the quest id, the objective id, and the objective's offer beat.
RollDice
Bases: Command
Referee: roll a dice expression through the seeded session.
An authorial roll for freeform adjudication — the referee resolves a chance
outcome the content model can't express (a puzzle, a bluff, "does the frayed
rope hold?") by rolling through the engine rather than inventing a number, so
the result is logged, replayable, and grounded in a typed event. Referee
commands are legal in every mode, terminal modes included. The roll draws from
the dedicated
ADJUDICATION_STREAM, so an ad-hoc
referee roll never perturbs the draw sequence of keyed mechanics. A malformed
expression is rejected at construction, exactly as
SpawnMonsters's count_dice is, so it
never reaches the session and consumes no draw.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
None.
Events
DiceRolledEvent with the
expression, the total, and the individual die results.
Search
Bases: Command
Search the party's cell for one hidden-feature kind (one turn).
The party must be exploring a dungeon (see
EnterDungeon), with light (infravision
suffices). Each character gets one attempt per cell per kind, ever. A
room_traps search covers the cell's door edges too: an open-trigger trap
in an area beyond a known door is findable from this side of it, and a found
trap never springs. An undiscovered secret door hides its trap along with
itself.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.exploration.action.requires_light— the party is in the dark and the searcher lacks infravision.exploration.search.already_tried— this character already searched this cell for this kind.
Events
DetectionRolledEvent with the
roll, a TrapEvent when a room trap is
found, then
SearchCompletedEvent naming
what turned up. One turn passes with its usual follow-on events.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
SessionMode
Bases: StrEnum
The session modes gating command legality.
The wire values are lowercase — they serialize into saves; changing them is a
schema_version bump.
game_over and victory are the terminal modes: the session has ended. Play
commands are illegal in both, referee commands remain legal except the ones
that would resume play (PlaceParty in
victory, SpawnMonsters and
SpawnNpcParty in both), and no play
ever leaves either one. The referee's salvage door out of game_over is
PlaceParty, documented there.
SetDoorState
Bases: Command
Referee: rewrite a door's overlay anywhere (None fields stay unchanged).
Referee commands are legal in every mode, terminal modes included; the door may be on any level of any dungeon, not just under the party.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
session.command.unknown_location—dungeon_idorlevel_numberresolves to nothing.session.command.no_door— no door edge at that cell and direction.
Events
A referee-visibility DoorEvent when the
open state actually changes; otherwise none.
command_type
class-attribute
instance-attribute
command_type: Literal['set_door_state'] = 'set_door_state'
SellTreasure
Bases: Command
Sell valuables in town at full value (zero time).
The party must be in town. Each entry names a carried valuable's instance id;
the coins credit its carrier's purse. osrlib adopts full value_gp as the
sale price: the OSE SRD prices treasure but names no exchange spread, and full
value keeps the 1-gp-1-XP identity clean. Magic items have no fixed sale value
(RAW's own words) and reject; revealed curses stick.
Modes
town
Rejections
session.command.wrong_mode— the party is not in town.town.sell.no_fixed_value— magic items cannot be sold for a fixed price.exploration.item.not_carried— no member carries a valuable with that instance id.
Events
TreasureSoldEvent per selling
member, with the credited value.
command_type
class-attribute
instance-attribute
command_type: Literal['sell_treasure'] = 'sell_treasure'
SetFlag
Bases: Command
Referee: set a session flag (content wiring: the lever opens the portcullis).
Referee commands are legal in every mode, terminal modes included. Flags
serialize into saves; game code and listeners read them back, and authored
content reads them through
FlagEqualsCondition — the gate on a
door or stair that opens when the lever has been pulled.
Modes
town, exploring, encounter, battle, game_over, victory
Rejections
None.
Events
FlagSetEvent with the key and value.
SpawnMonsters
Bases: Command
Referee: spawn monsters and open an encounter at a distance.
The party must be standing in a dungeon with no encounter already open —
encounters live on the dungeon grid. Spawning is the one referee power a
terminal session withholds: an encounter is play, and a session that has
ended opens no new play state, so this is illegal in game_over and
victory alike. Exactly one of count_dice or count_fixed is required.
Modes
town, exploring, encounter, battle
Rejections
session.command.unknown_monster—template_idnames no monster.session.command.encounter_in_progress— an encounter or battle is already open.session.command.not_in_dungeon— the party is not on a dungeon cell.
Events
MonstersSpawnedEvent, then
the encounter opening —
SurpriseRolledEvents,
EncounterStartedEvent, the
reaction roll and
StanceChangedEvent; an attacks
stance opens battle at once.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = _ALL_MODES - frozenset({SessionMode.GAME_OVER, SessionMode.VICTORY})
command_type
class-attribute
instance-attribute
command_type: Literal['spawn_monsters'] = 'spawn_monsters'
SpawnNpcParty
Bases: Command
Referee: generate an NPC adventuring party and open an encounter.
count_dice=None rolls the compiled composition dice (Basic 1d4+4, Expert
1d6+3) — the surface for keyed content, quest listeners, and tests. The party
must be standing in a dungeon with no encounter already open, and, like
SpawnMonsters, the command is illegal
in a terminal mode: a concluded session opens no new encounter.
Modes
town, exploring, encounter, battle
Rejections
session.command.encounter_in_progress— an encounter or battle is already open.session.command.not_in_dungeon— the party is not on a dungeon cell.
Events
NpcPartySpawnedEvent (the
referee-visibility roster), then the encounter opening as with
SpawnMonsters.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = _ALL_MODES - frozenset({SessionMode.GAME_OVER, SessionMode.VICTORY})
command_type
class-attribute
instance-attribute
command_type: Literal['spawn_npc_party'] = 'spawn_npc_party'
TakeTreasure
Bases: Command
Empty a cache or pile into the party's packs (one turn, RAW).
The party must be exploring a dungeon (see
EnterDungeon). feature_id names an
authored cache, an engine-generated cache, or the literal pile for goods
dropped on the cell.
By default the haul spreads across the living members: items go to a
character whose class can use them (the fighter takes the plate mail, the
magic-user the arcane scroll), gems and jewellery divide by worth, and coins
divide evenly denomination by denomination. Nothing is ever loaded past the
1,600-coin maximum load, so a pickup cannot immobilise the party — the group
moves at its slowest member's rate, so one mule stops everyone. Name
recipient_id to override: that member alone fills their pack, up to their own
maximum load. Whatever exceeds the carriers' capacity stays in the drop pile on
the cell — nothing is destroyed, and the party can lighten up and come back for
it. This first pass is automatic bookkeeping, not a ruling: rearrange it freely
with GiveItems, and note that XP divides
evenly however the goods end up split, per RAW.
The named recipient — or the leading living member when none is named — is the one who reaches in, so taking a trapped cache with its trap unresolved risks springing it on them.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.session.command.no_living_members— no one is left to carry.session.command.unknown_member—recipient_idnames no party member.session.command.member_incapacitated— the recipient cannot act.exploration.feature.unknown— nothing by that id on this cell.exploration.feature.emptied— the cache has already been emptied.
Events
One ItemAcquiredEvent per member
who took something, listing their goods and coin value, in marching order;
an ItemsLeftBehindEvent when
the party could not carry it all. An unresolved treasure trap rolls first
(DetectionRolledEvent, a
TrapEvent, and the trap's resolution
when it springs). Under the immediate XP timing an
XpAwardedEvent follows per member.
One turn passes.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
command_type
class-attribute
instance-attribute
command_type: Literal['take_treasure'] = 'take_treasure'
TravelToTown
Bases: Command
Travel from the dungeon entrance back to town (the same travel cost).
The party must be exploring and standing on the entrance cell. Doors the party opened swing shut behind it, and under the on-return XP timing the adventure award pays out on arrival.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.exploration.travel.not_at_entrance— the party is not on the entrance cell.
Events
DoorEvents for doors swinging shut,
travel-time bookkeeping, then
LocationEnteredEvent for
town. Under the on-return XP timing an
AdventureXpAwardEvent and
per-member XpAwardedEvents follow.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
command_type
class-attribute
instance-attribute
command_type: Literal['travel_to_town'] = 'travel_to_town'
TurnParty
Bases: Command
Turn the party in place to a new facing (zero time).
The party must already be inside a dungeon — see
EnterDungeon.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.
Events
PartyMovedEvent with the unchanged
position and the new facing.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
TurnUndead
Bases: Command
Present the holy symbol — the one aggressive act with a pre-battle procedure.
An encounter must be open: exploration offers no candidates by definition, and in battle turning is a declaration kind. If any monster stands unturned, the survivors attack at once.
Modes
encounter
Rejections
session.command.wrong_mode— no encounter is open.encounter.none_active— defensive twin of the mode gate; not reachable through normal play.encounter.turning.mid_pursuit— no turning while being chased.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the cleric cannot act.magic.turning.not_a_turner— the class has no turn-undead ability.magic.turning.caster_incapacitated— a condition prevents the attempt.
Events
UndeadTurnedEvent with the roll
and the affected monsters (their conditions each their own event). When
every monster is turned or destroyed the encounter ends
(EncounterEndedEvent);
otherwise a StanceChangedEvent
to attacks and battle opens
(BattleStartedEvent).
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.ENCOUNTER})
command_type
class-attribute
instance-attribute
command_type: Literal['turn_undead'] = 'turn_undead'
UnequipItem
Bases: Command
Return an equipped item to the member's item list (zero time).
Legal in town and while exploring. A revealed cursed item stays put until remove curse.
Modes
town, exploring
Rejections
session.command.wrong_mode— an encounter or battle is underway, or the game is over.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.exploration.item.not_equipped— nothing by that id is equipped.items.curse.stuck— a revealed cursed item cannot be removed.
Events
Usually none; a worn magic item's effects release
(EffectReleasedEvent).
command_type
class-attribute
instance-attribute
command_type: Literal['unequip_item'] = 'unequip_item'
UseItem
Bases: Command
Use a magic item: drink a potion, read a scroll, activate a device (one round).
One round is the RAW activation cost (drinking is one round). target_id
names a character (the staff of healing's touch) or an encounter group (a
device's area); spell_id, mode, and targets select the inscribed spell
and its targets when reading a multi-spell scroll (the
CastSpell surface). In battle, item use
is the use_item declaration instead. First meaningful use identifies the
item — and reveals its curse.
Modes
exploring, encounter
Rejections
session.command.wrong_mode— the session is in town, in battle, or over.session.command.unknown_member—character_idnames no party member.session.command.member_incapacitated— the member cannot act.exploration.item.not_carried— the member carries no magic item with that instance id.items.use.not_usable— the item has no usable action, or the class cannot use the device.- Scrolls:
exploration.action.requires_light(reading needs real light),items.scroll.spent,items.scroll.no_such_spell,items.scroll.wrong_caster, and the cast validation codes (magic.cast.unknown_target,magic.cast.unknown_mode,magic.cast.target_count,magic.cast.out_of_range,magic.cast.caster_incapacitated,magic.cast.caster_restrained,magic.cast.anti_magic_shell). - Devices:
items.device.inert(no charges left),items.use.target_required,items.use.unknown_target, anditems.use.battle_only(a striking effect is a battle declaration).
Events
ItemUsedEvent naming what happened
(drunk, read, activated — or mixed potions, or a cursed scroll), with
ItemIdentifiedEvent and
CurseRevealedEvent at first
meaningful use, then the item's own resolution — healing, saving throws,
damage, effect attachments, a scroll's
SpellCastEvent — each its own
event. One round passes (in an encounter, the round beat follows instead).
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING, SessionMode.ENCOUNTER})
UseStairs
Bases: Command
Take the stair, ladder, or other transition on the party's cell.
The party must be exploring a dungeon (see
EnterDungeon) and standing on a cell
with an authored transition. The move costs one unexplored-cell step of
movement.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.exploration.stairs.none— no transition on the party's cell.exploration.transition.gate_refused— the transition carries an authored condition (GateSpec) the party does not satisfy; the refusal carries the author's own text, and costs no movement, no time, and no toll.
Events
ItemConsumedEvent first when the
gate's condition consumes what it asks for — the toll is paid at the
threshold — then
LocationEnteredEvent when the
level or dungeon changes, carrying the gate's success text when its author
wrote one. Arrival then runs the cell's entry checks — area treasure, room
traps, keyed encounters — each reporting its own events, and the movement
cost accrues toward the turn clock.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
Wait
Bases: Command
Hold for one encounter round; the monsters act per their stance.
An encounter must be open. Waiting burns a round to see what the monsters do — an uncertain stance re-rolls its reaction, a hostile one runs out its patience.
Modes
encounter
Rejections
session.command.wrong_mode— no encounter is open.encounter.none_active— defensive twin of the mode gate; not reachable through normal play.
Events
The round beat's events: an uncertain stance re-rolls
(ReactionRolledEvent, possibly
a StanceChangedEvent), and an
attacking or expired-patience hostile stance opens battle
(BattleStartedEvent). During a
pursuit a PursuitEvent round resolves
instead.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.ENCOUNTER})
WedgeDoor
Bases: Command
Wedge a door with an iron spike so it cannot swing shut (zero time).
The party must be exploring a dungeon (see
EnterDungeon). Any living member's
spike serves; one iron spike is consumed.
Modes
exploring
Rejections
session.command.wrong_mode— the session is not exploring a dungeon.exploration.door.no_door— no known door on that side of the cell.exploration.door.wedged— the door is already wedged.exploration.door.no_spike— no living member carries iron spikes.
Events
ItemConsumedEvent for the spike,
then DoorEvent with code
exploration.door.wedged.
allowed_modes
class-attribute
allowed_modes: frozenset[SessionMode] = frozenset({SessionMode.EXPLORING})
parse_command
Parse one serialized command, skipping unknown command types.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Mapping[str, object]
|
A mapping previously produced by a command's |
required |
Returns:
| Type | Description |
|---|---|
Command | None
|
The command, or |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the command type is known but the payload is malformed. |