Skip to content

Views and visibility

B/X hides information from players by design. A fighter doesn't know the goblin has 4 hit points left, only that it's bleeding. The referee alone sees the monsters' morale roll and the reaction roll that decides whether they attack or flee. osrlib builds that asymmetry into the API instead of trusting the front end to enforce it.

Visibility shows up in two places: on individual events, and on the two whole-state projections a GameSession can build. Over a network that split becomes a boundary you enforce on the server, because a client must never see more than the player is meant to. The complete example is at the end of the page, and every snippet along the way comes from it.

Visibility on events

Every Event has a Visibility: PLAYER or REFEREE. Most events default to PLAYER, like a party move, a door opening, or damage dealt. A specific set default to REFEREE because B/X keeps them behind the screen: morale checks, reaction rolls, wandering-monster checks, detection rolls, and the event that reports a creature's current and maximum hit points (HitPointsReportedEvent). If your front end streams or narrates the raw event log as it happens, like an LLM referee doing turn-by-turn narration, check .visibility yourself before you show an event to a player.

Authored content splits the same way. A journal entry is written for the table, so JournalEntryAddedEvent is player-visible and includes the authored text as content data in a structured field, alongside the event's message code. The text isn't English the engine wrote. The setup that produced the entry is referee-only. A fired trigger (TriggerFiredEvent) and a referee note (NoteRecordedEvent) are referee-only, like a flag write, because the players aren't meant to see the connection between what the party does and what that action sets off. Player-visible events and the player view are two of the three ways authored text reaches a player. The third is a gate's refusal text, which the engine returns in an ordinary rejection. Render it like any other refusal (see Gates, triggers, and quests).

Most front ends don't filter by hand, because osrlib also provides two projections of the whole session, one per audience, each already filtered for that audience.

The two views

Pass a Visibility to GameSession.view and you get the matching projection:

player_view = session.view(Visibility.PLAYER)
referee_view = session.view(Visibility.REFEREE)

PlayerView is an explicit list of fields, built straight from session state and never from the event log, so it can't leak a referee-visibility event that happened to mention a hidden number.

You get the adventure's and town's public names and descriptions, the town's list of services, what the town's temple charges for each healing service, the party's location and facing, the elapsed clock, and the session mode.

Each party member has a character sheet (MemberView), because a player always sees their characters in full. The sheet has every number on a B/X character sheet, so a client that has only the player view can draw one. It has the member's id, name, race, class, level and title, alignment, experience points and the total the next level needs, hit points, and conditions. It also has the six ability scores and their modifiers, THAC0 and attack bonus, both armour classes, the five saving throws, the movement rate, the languages, the inventory, the spell book and memorized spells, and a thief's skill chances. The numbers count what the member wears, like armour, a shield, or a ring of protection. A timed effect from a spell or a potion isn't in the numbers. It's in PlayerView.effects.

Unidentified magic items are masked to a category-level description rather than their true name (see MagicItemCategory), so even in a character's inventory, the view shows an item's name only after the party identifies it. An unidentified weapon is the one exception to "name only": when its display string includes the name of the weapon underneath, the view also includes that weapon's qualities and missile_ranges, which are enough for a front end to tell a melee declaration from a missile one. That's an enchanted arm, whose display string is built from the base weapon ("a sword with a faint aura"), and a magic staff, which displays as "a staff" and is a mundane staff underneath. Every magic staff shows the same qualities, so they don't set one staff apart from the others. The bonus, any curse, and the template id stay hidden until identification. Any other item whose display string comes from its category, like "a wand", includes neither field.

The armour class on the sheet counts an unidentified magic item the member wears, because it's the armour class the monsters roll against. So an unarmoured fighter who takes up an unidentified shield +1 goes from armour class 9 to 7, one better than a plain shield gives, while the inventory still calls the item "a shield with a faint aura".

A STR that an item sets doesn't change the STR in the sheet's scores. The sheet has it as effective_strength, the STR the rules use during play, and the melee modifier and the chance to force a door come from it. A member who wears gauntlets of ogre power has STR 18 there, and a member under the curse of a ring of weakness has STR 3. So a fighter who rolled STR 11 and puts on the gauntlets shows STR 11 in scores, 18 as effective_strength, a melee modifier of +3, and a 5 in 6 chance to force a door. To show a player what the gauntlets did, show both STR numbers. Combat and the session's roll to force a door use the same numbers. Like the armour class, these numbers count the gauntlets before the party identifies them.

For the map, you get the mapped cells with their edges (ExploredLevelView and EdgeView): every cell the party has walked, every cell the party's light has shown, and whatever that light reveals from where the party stands right now. The cells the light has shown persist as map memory in DungeonState.seen, so the automap you draw can still show a torchlit room after the party walks on. The view shows an undiscovered secret door as a plain wall. Known dropped piles and emptied treasure caches in that explored space are in the view too.

Active effects on party members come with their remaining duration, except a potion's: by the rules as written, the referee tracks a potion's duration secretly, so the view reports it as unknown. The view also reports fatigue, exhaustion, and deprivation status, and the session journal as written (JournalEntry): the entries in order of discovery, each with the clock position when it was added. The view doesn't include the records of which triggers fired to add those entries.

The quests in play appear as QuestView values with an id, a name, the offer text and its speaker, and the revealed objectives with their ids, display names, and states. When an encounter or battle is running, the view also contains its public state (EncounterView and EncounterGroupView). For each monster group, that's its id, its living count, its distance, its visible conditions and how many members have each, and whether it has fled, but never its hit points.

A group also has what to call its members and what kind of creature they are. Show label for one member, like "goblin", and label_plural for more, like "goblins". The label is text for the players, and a group your code opens can have any label, so to decide what a group is, read family_id and categories instead. A group of hellhounds has the family id "hellhound" whatever their Hit Dice, and a group of skeletons has the category "undead".

The view also reports what the table knows about the current round, in three fields of EncounterView: who must declare (declarers), who is held fast (immobile), and who is still reloading (reloading).

In a battle, each member stands at a separate place on the range track, the measure of distance a battle uses, so the view reports where everyone stands:

  • EncounterView.advance_feet gives each member's place, in feet forward of the party line, where the party stood when the encounter opened. Two members reach each other when their places differ by 5' or less. A member has to reach another to hand them an item, to give them a potion to drink, or to touch them with a staff of healing or a touch spell like cure light wounds.
  • Each group's member_distance_feet gives every member's distance to that group.
  • Each group's front_rank lists the members who can attack that group in melee this round without moving. They're also the only members the group's melee reaches. To decide who can attack a group hand to hand, read this field, not EncounterView.front_rank, which is the first row toward the nearest group, however far away it stands.
  • EncounterView.formation_width gives how many members can fight side by side, so you can show how many places are left in a group's front rank. The monsters of each group fight in a front rank as wide, made of the group's first living monsters, and only those monsters make melee attacks. So the most monsters of a group that can strike is the smaller of its count and this width.
  • MemberView.encounter_rate_feet gives how far a member can move in a round. A member can close on a group and attack it in the same round when their distance to it is at most that rate plus 5'.
  • EncounterView.party_free_round marks the round in which a thief's back-stab is legal.
  • Each group's lit and seen_by say whether the party's light reaches it and which members can see it.

To check a member's choice against the choices already made for the round, call preview_battle_round with the declarations planned so far. It judges them the way ResolveBattleRound would, and returns each declaration's rejections, where each member would stand, and each group's front rank, without playing the round. A battle screen can call it after each choice and grey out the choices ResolveBattleRound would refuse.

RefereeView is the opposite: everything except the RNG stream states and the master seed. It has one field for each group that session_state writes for a save, and each field uses the session's model, so view.monsters contains full MonsterInstance values with real hit points, and view.flags, view.npcs, view.exploration, and view.event_log are the flag store, the NPC roster, the session counters, and the complete event log with referee-visibility events in it. Dumping the view to JSON gives that save payload back without the two withheld keys. Use it for LLM referees and tools that need the truth rather than a player's approximation of it. Never send it to a client over the network.

The split in practice

A spawned monster shows the split. The referee view contains the monster's live hit points. The player-facing encounter group contains only what the party could plausibly perceive: what the monster is, how many are still standing, how far away they are, and what conditions show.

# The referee sees the goblin's hit points; the player view never contains them.
referee_monster = referee_view.monsters[0]
assert referee_monster.current_hp > 0

player_group = player_view.encounter.groups[0]
assert (player_group.label, player_group.family_id, player_group.categories) == ("goblin", "goblin", ("person",))
assert player_group.count == 1
assert "current_hp" not in player_group.model_dump()

Authored content shows the same split from the other side. The player view contains the whole journal and none of the triggers behind its entries.

# The beat is for the table; the trigger that produced it is referee-only setup.
assert [entry.text for entry in journal_view.journal][-1] == "The lever grinds."
assert "lever-east" not in journal_view.model_dump_json()
assert referee_after.fired_triggers == ("lever-east",)

Quests split the same way, in more detail. PlayerView.quests contains the active quests only, in document order. A quest the party hasn't been given yet is absent, because the clause that activates it is hidden from the players, the same as a trigger's logic. A finished quest is no longer in PlayerView.quests, because its record is the journal. Under each quest, only the revealed objectives appear. A hidden objective's id is not in the projection at all until its reveal_when clause fires or the objective completes, which is why ObjectiveView.state needs only "incomplete" and "complete". The player view contains nothing else about a quest: no clause, no pattern, no condition, no reward, and no guidance from any narrative block or level.

# Active quests only, revealed objectives only, and none of the setup behind them.
quest_view = player_view.quests[0]
assert (quest_view.id, quest_view.speaker) == ("the-lamps", "Sister Halda")
assert [entry.id for entry in quest_view.objectives] == ["find-the-lever"]
assert quest_view.objectives[0].name == "Find the lever"  # the authored name, or the id when unauthored
assert "name-the-dead" not in player_view.model_dump_json()

How a client knows the journal grew

JournalEntryAddedEvent is not the only event the engine emits when the journal grows. A quest's journal entry is the line that the quest's lifecycle event already reports, so the engine emits no journal event after it. Emitting both would show the table one line twice. If you render the journal incrementally, watch these codes rather than one: session.journal.entry_added, session.quest.activated, session.quest.objective_revealed, session.quest.objective_completed, and session.quest.completed. If you'd rather not track any of them, read PlayerView.journal, which is always the whole record.

Never trust the client

The moment a game goes over a network, this split becomes a security boundary. Keep the session, with its full referee-visible state, on the server. A client never runs execute itself and never receives the referee view. Each request sends a command, the server calls session.execute(command), and the response sends back only session.view(Visibility.PLAYER), or a rendering of the accepted result's events filtered the same way. A client that could see the referee view, or run commands against a local copy of the session, could read monster hit points straight off the wire or replay commands the server never accepted. B/X reserves that information and control for the person running the table. The FastAPI pattern walks through this boundary end to end. You keep one session per game on the server and pass every response through the player view before it leaves the process.

The complete example

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 (
    AddJournalEntry,
    EnterDungeon,
    MarkTriggerFired,
    RecordNote,
    SessionMode,
    SetFlag,
    SpawnMonsters,
)
from osrlib.crawl.dungeon import DungeonSpec, LevelSpec
from osrlib.crawl.interpreter import Interpreter
from osrlib.crawl.narrative import NarrativeBlock
from osrlib.crawl.party import Party
from osrlib.crawl.quests import ObjectiveSpec, QuestSpec, TriggerClause
from osrlib.crawl.session import GameSession
from osrlib.crawl.triggers import DungeonEnteredPattern, FlagSetPattern

rules = Ruleset()
creation = RngStreams(master_seed=13).get(CHARACTER_CREATION_STREAM)
hero = create_character(
    name="Rurik",
    class_id="fighter",
    alignment=Alignment.LAWFUL,
    ruleset=rules,
    stream=creation,
)
party = Party(members=[hero.character])

level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0))
crypt = DungeonSpec(id="crypt", name="The Old Crypt", levels=(level,))
town = TownSpec(name="Threshold", travel_turns={"crypt": 1})

# One errand, offered at the threshold: one objective the party is told about, and
# one it is not.
errand = QuestSpec(
    id="the-lamps",
    name="The Unlit Lamps",
    activation=TriggerClause(pattern=DungeonEnteredPattern(dungeon_id="crypt")),
    objectives=(
        ObjectiveSpec(
            id="find-the-lever",
            when=TriggerClause(pattern=FlagSetPattern(key="crypt.lever")),
            narrative=NarrativeBlock(progress="The lamps come up one by one."),
        ),
        ObjectiveSpec(id="name-the-dead", when=TriggerClause(pattern=FlagSetPattern(key="crypt.name")), hidden=True),
    ),
    narrative=NarrativeBlock(
        offer="Light the crypt's lamps before the moon sets.",
        speaker="Sister Halda",
    ),
)
adventure = Adventure(name="A First Delve", town=town, dungeons=(crypt,), quests=(errand,))
session = GameSession.new(party, adventure, seed=13)
session.register_listener(Interpreter(session))

session.execute(EnterDungeon(dungeon_id="crypt"))

# The referee creates a lone goblin and opens an encounter at 30 feet.
result = session.execute(SpawnMonsters(template_id="goblin", count_fixed=1, distance_feet=30))
assert result.accepted
assert session.mode is SessionMode.ENCOUNTER

player_view = session.view(Visibility.PLAYER)
referee_view = session.view(Visibility.REFEREE)

# The referee sees the goblin's hit points; the player view never contains them.
referee_monster = referee_view.monsters[0]
assert referee_monster.current_hp > 0

player_group = player_view.encounter.groups[0]
assert (player_group.label, player_group.family_id, player_group.categories) == ("goblin", "goblin", ("person",))
assert player_group.count == 1
assert "current_hp" not in player_group.model_dump()

# A trigger fires: it is marked, it writes a journal beat, and the referee annotates it.
session.execute(MarkTriggerFired(trigger_id="lever-east"))
session.execute(AddJournalEntry(text="The lever grinds.", source="trigger:lever-east"))
session.execute(RecordNote(text="The east lever is the only one that answers."))

journal_view = session.view(Visibility.PLAYER)
referee_after = session.view(Visibility.REFEREE)

# The beat is for the table; the trigger that produced it is referee-only setup.
assert [entry.text for entry in journal_view.journal][-1] == "The lever grinds."
assert "lever-east" not in journal_view.model_dump_json()
assert referee_after.fired_triggers == ("lever-east",)

# The quest activated at the threshold, and its offer opened the journal.
quest_view = journal_view.quests[0]
assert (quest_view.id, quest_view.name) == ("the-lamps", "The Unlit Lamps")
assert quest_view.narrative == "Light the crypt's lamps before the moon sets."
assert quest_view.speaker == "Sister Halda"
assert journal_view.journal[0].text == quest_view.narrative

# Only the revealed objective is projected, and none of the setup behind it.
assert [(entry.id, entry.state) for entry in quest_view.objectives] == [("find-the-lever", "incomplete")]
blob = journal_view.model_dump_json()
assert "name-the-dead" not in blob  # a hidden objective has no view at all
assert "pattern_type" not in blob and "crypt.lever" not in blob

# The flag that objective watches: the quest completes it, journals its beat, and
# reports the beat through its own event — no journal event follows.
lit = session.execute(SetFlag(key="crypt.lever", value=True))
codes = [event.code for event in lit.events]
assert "session.quest.objective_completed" in codes
assert "session.journal.entry_added" not in codes
assert session.journal[-1].text == "The lamps come up one by one."

after = session.view(Visibility.PLAYER)
assert [(entry.id, entry.state) for entry in after.quests[0].objectives] == [("find-the-lever", "complete")]
assert session.quests["the-lamps"].status == "active"  # the hidden objective is still open

Where next