osrlib.messages
Turn an event into a line of English.
osrlib puts no prose in an event. A GameSession
responds to a command with typed events made of structured facts, like who attacked, what they
rolled, and how much damage they dealt, and you decide what a player reads. This
module is the default formatter that comes with osrlib.
format_message takes an event and returns a plain
English sentence, so you can print a session's output before you write a renderer of your
own.
The event's code determines the line you get. A code is a dotted name like
combat.attack.hit that identifies the outcome the event records, and this module has one
template per code. Every event class declares the codes it can use in allowed_codes, and
ALL_EVENT_CLASSES lists every event class, so
{code for cls in ALL_EVENT_CLASSES for code in cls.allowed_codes} is every code osrlib
defines.
The message code reference
lists the same codes with the event class of each one, its default visibility, and its
template. Read it when you decide which codes to handle differently.
Use this formatter for a log, a transcript, a debugging view, or the first working version
of a game. When you want your own wording, replace the whole formatter: read the event's
fields and write your own line, or pass the event to a narrator. There's nothing here to
configure, no way to register a template, and no translation. You have the same structured
fields this formatter reads, so you can write any wording you like. Entity ids
come out as ids, like orc-1, because an event refers to creatures by id. The quest and
objective events are the exception: they include a display name the adventure's author
wrote, and the line uses it.
format_message only builds a string. It reads no files, makes no calls, and changes nothing,
so you can call it 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 event in a session's event_log, to get a transcript a person can
read. If you're showing the result to a player, first keep only the events whose
visibility is Visibility.PLAYER, so referee-only
events stay hidden.
A session's event_log can also contain plain dicts. After
load_game, an entry whose event type this version of
osrlib doesn't recognize stays the dict it was in the save. Skip those, or print their
code key, before you filter on visibility. A dict has no visibility attribute, and
this function takes an event object, not a dict.
On an event osrlib built, it doesn't raise and it doesn't return an empty string. An
event whose code has no template, like a base Event you
build with a code of your own, comes back as the code itself. An event you build by hand
can still raise AttributeError, because a template reads the fields its event class
declares: give an event a code from another class and the field that template needs
isn't there. When you build an event by hand, use the class that declares its code.
Some events include a narrative, the sentence an adventure's author wrote for that
moment. When there is one, it's added to the end of the templated line, word for word,
because the wording of authored text belongs to the author.
Write your own formatter when you want control of the wording. This one prints entity ids as ids, writes only English, and has no way to change a template. Every fact it uses is a typed field on the event, so your version can read the same fields and use your own names for things.
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