osrlib.crawl.narrative
Authored text for gates, triggers, quests, and objectives, written for three audiences.
A NarrativeBlock contains the text an adventure's author
writes for one of those objects. Each of its fields is a beat: one line of text for one moment,
like a gate's refusal or a quest's offer.
You put a block in the narrative field of a gate
(GateSpec), a trigger
(TriggerSpec), a quest
(QuestSpec), or a quest objective
(ObjectiveSpec). All four are part of the
Adventure document. osrlib evaluates nothing in the block.
The code that runs the object reads the beats it needs: the door and transition handlers of
GameSession.execute for a gate, the
Interpreter for a trigger, and the quest commands for a
quest or an objective. You get the beats back in the narrative field of an event like
DoorEvent,
TriggerFiredEvent, or
QuestActivatedEvent, in the text of a
JournalEntryAddedEvent, or in the parameters of the
rejection the session returns when a gate's condition isn't met.
The three audiences are:
- The display beats,
refusal,success,fired,offer,progress, andcompletion, which you show exactly as written in the code you write to show the game to a player. The default English formatter,format_message, appends an event's beat after its templated line, so a plain transcript shows the author's words unchanged. - The
journalbeat, the object's entry in the party's journal (the written record the session keeps of the adventure). osrlib reads it only for a trigger. A trigger'sfiredbeat goes on a referee-only event that players never see, so write the line meant for the players injournal. For a quest, the session writes the display beat it showed to the journal instead. - The
guidancebeat, instructions for a language model that narrates the game. Don't show it to a player as written. Give it to the narrator as authored content, the same way you give it an area's description.
Which beats osrlib reads, and who sees them, depends on the object the block belongs to. The block has no visibility setting. Text meant for a player reaches them on a player-visible event or in a rejection. The conditions, flags, and guidance that produced it stay in referee-only events and in the adventure document.
NarrativeBlock
Bases: BaseModel
The authored beats for one gate, trigger, quest, or objective.
Construct one and pass it as the narrative of the object it belongs to. Every field is free
text. The empty string, the default, means the beat isn't written, so a block with only a
refusal is normal. Which beats osrlib reads depends on the object the block belongs to:
- For a gate (
GateSpec), osrlib readsrefusalandsuccess. When the session refuses an attempt, its rejection includesrefusal. When an attempt succeeds, its event includessuccess. - For a trigger (
TriggerSpec), osrlib readsfiredandjournalwhen its consequences run.firedgoes on a referee-only event, so it's the referee's line about what happened.journalis the players' line about the same moment. - For a quest (
QuestSpec), osrlib readsofferwhen the quest activates andcompletionwhen it completes. - For an objective (
ObjectiveSpec), osrlib readsofferwhen the objective is revealed andprogresswhen it completes. If an objective completes before it's revealed, the session uses only itsprogress.
osrlib ignores the beats it doesn't read for an object, like progress on a quest, completion on an
objective, fired on a gate, or offer on a trigger. A block that sets them still parses.
Two fields apply to every object. guidance is instructions for a narrator that uses a language
model, and osrlib never reads it. speaker is an attribution, like "the bronze sentinel" or
"Sister Halda", that you can show in front of a beat.
Examples:
from osrlib.crawl.narrative import NarrativeBlock
narrative = NarrativeBlock(
refusal="The sentinel's eyes stay dark. It wants the brass key.",
success="The key turns, and the sentinel steps aside.",
speaker="the bronze sentinel",
)
print(repr(narrative.offer)) # a beat you don't write is the empty string, never None
# ''
print(sorted(narrative.model_dump(exclude_defaults=True)))
# ['refusal', 'speaker', 'success']
refusal
class-attribute
instance-attribute
refusal: str = ''
A gate's refusal line. When the session refuses an attempt because the gate's condition isn't
met, the rejection includes this line as its refusal parameter. Leave it empty and the
rejection has no refusal parameter.
success
class-attribute
instance-attribute
success: str = ''
A gate's success line. It goes in the narrative of the event for the successful attempt: a
DoorEvent for a door, a
LocationEnteredEvent for a transition to another
level, or a PartyMovedEvent for a transition to another
cell of the same level.
fired
class-attribute
instance-attribute
fired: str = ''
A trigger's firing line, for the referee. It goes in the narrative of the
TriggerFiredEvent, which players never see.
offer
class-attribute
instance-attribute
offer: str = ''
A quest's activation line, or an objective's reveal line. It goes in the event's narrative
and into the journal.
progress
class-attribute
instance-attribute
progress: str = ''
An objective's completion line. It goes in the event's narrative and into the journal.
osrlib doesn't read it on a quest.
completion
class-attribute
instance-attribute
completion: str = ''
A quest's completion line. It goes in the event's narrative and into the journal. osrlib
doesn't read it on an objective.
journal
class-attribute
instance-attribute
journal: str = ''
A trigger's journal line, for the players. When the trigger fires, the
Interpreter adds it to the journal with
AddJournalEntry. osrlib doesn't read it on a quest,
because for a quest the session writes the line it showed to the journal.
guidance
class-attribute
instance-attribute
guidance: str = ''
Instructions for a narrator that uses a language model, while the object is in play. It isn't text to show a player as written.
osrlib never reads it, no event includes it, and no rule depends on it. Read it from the
adventure document when your narrator writes its text. The adventure document is referee-only
content, so don't show the field to a player. LevelSpec.guidance
does the same job for a whole level.
speaker
class-attribute
instance-attribute
speaker: str = ''
An attribution, like "the bronze sentinel", that you can show in front of a beat.
osrlib reads it only on a quest, and passes it to the player view as
QuestView.speaker.