osrlib.messages
Turn an event into a line of English.
osrlib never puts prose in an event. A GameSession
answers a command with typed events made of structured facts, like who attacked, what they
rolled, and how much damage landed, and your front end decides what a player reads. This
module is the answer that comes in the box.
format_message takes an event and returns a plain
English sentence, so you can print a session's output before you've written any rendering of
your own.
The event's code decides what you get. It's a dotted name like combat.attack.hit that
says which outcome the event records. Every event class declares the codes it can use, and
this module keeps one template per code.
The message-code reference lists every code that ships, the event class
behind it, the event's default visibility, and the template itself. Read that page when
you're deciding which codes your front end handles differently.
Use this formatter for a log, a transcript, a debugging view, or the first working version
of a game. Replace it when you want wording of your own, and you replace the whole of it:
read the event's fields and write your own line, or hand the event to a narrator. There's
nothing here to configure, no way to register a template, and no translation, because a
front end that cares about wording already has the structured fields it needs to write any
wording it likes. Entity ids come out as ids, since only your game knows the name behind
orc-1. The quest and objective events are the exception, and include a display name the
adventure's author wrote.
Formatting is string work. It reads no files, makes no calls, and changes nothing, so it's safe on any event from any source.
Typical usage:
from osrlib.core.events import DamageDealtEvent
from osrlib.messages import format_message
event = DamageDealtEvent(target_id="orc-1", attacker_id="hild", amount=5)
print(format_message(event))
# orc-1 takes 5 damage from hild.
format_message
Format an event as a line of default English.
Call it on each event in a CommandResult's
events, or on each entry in a session's event log, to get a transcript a person can
read. Filter on the event's visibility first if you're showing the result to a player,
so referee-only events stay hidden.
On an event osrlib built, it doesn't raise and it doesn't return an empty string. An
event whose code has no template comes back as the code itself, so a log written by a
newer osrlib than the one reading it still prints, one plain line per event, instead of
failing part way through. An event you assemble by hand can still raise AttributeError,
because a template reads the fields its own event class declares: give an event a code
from another class and the field that template wants isn't there.
Some events include a narrative, the sentence an adventure's author wrote for that
moment. When one is there it's appended to the templated line, word for word, because the
wording of authored text belongs to the author.
Write your own formatter as soon as you want control of the wording. This one prints entity ids as ids, writes only English, and has no hook for changing a template. Every fact it uses is a typed field on the event, so your version reads the same fields and uses your own game's names.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
Event
|
Any event, from a command result, a session's event log, or a save you loaded. |
required |
Returns:
| Type | Description |
|---|---|
str
|
One line, with no trailing newline: the template for the event's code, followed by
the event's |
Examples:
from osrlib.core.events import DamageDealtEvent, Event, Visibility
from osrlib.messages import format_message
event = DamageDealtEvent(target_id="orc-1", attacker_id="hild", amount=5)
print(format_message(event))
# orc-1 takes 5 damage from hild.
unknown = Event(code="future.thing.happened", visibility=Visibility.PLAYER)
print(format_message(unknown))
# future.thing.happened