osrlib.crawl.views

The projection API: the player's safe whitelist and the referee's full state.

execute() mutates session state; build_player_view and build_referee_view build these frozen projections from that state alone, never from the event log.

The player view is an enumerated whitelist: party public sheets, location and facing, explored cells with their edges (secret doors only if discovered — an undiscovered secret door renders as wall), known piles and emptied caches in explored space, active effects on party members with remaining durations, the elapsed clock, the mode, the current encounter/battle public state (names, counts, distances, visible conditions — never HP), fatigue/exhaustion/deprivation status, and the adventure's public prose. It never carries unexplored geometry, undiscovered traps or secret doors, monster HP or stat internals, referee-visibility roll outcomes, session flags, RNG state, or the seed — the seed lives only in the save, and neither view carries it.

The referee view carries everything else the save does, minus RNG internals and the seed, for LLM referees and tests. A front end must never trust the client: a networked game keeps the session and the referee view server-side, and returns only the player view — or player-visibility events — over the wire.

EdgeView

Bases: BaseModel

One visible edge: its kind (undiscovered secret doors render as wall) and door state.

kind instance-attribute

kind: str

door_open class-attribute instance-attribute

door_open: bool | None = None

door_wedged class-attribute instance-attribute

door_wedged: bool | None = None

EncounterGroupView

Bases: BaseModel

A monster group as the players see it: id, name, count, distance, behavior — never HP.

The group id is the command vocabulary: battle declarations name their target_group_id with it, so the projection must carry it for a wire client to fight at all — an allocator ordinal, not a secret (the id doctrine MemberView already sets).

id instance-attribute

id: str

label instance-attribute

label: str

count instance-attribute

count: int

distance_feet instance-attribute

distance_feet: int

visible_conditions instance-attribute

visible_conditions: tuple[str, ...]

EncounterView

Bases: BaseModel

The current encounter or battle's public state.

groups instance-attribute

groups: tuple[EncounterGroupView, ...]

stance instance-attribute

stance: str | None

in_battle instance-attribute

in_battle: bool

battle_round class-attribute instance-attribute

battle_round: int | None = None

pursuit_gap_feet class-attribute instance-attribute

pursuit_gap_feet: int | None = None

ExploredLevelView

Bases: BaseModel

One level's explored map: cells and their edges.

dungeon_id instance-attribute

dungeon_id: str

level_number instance-attribute

level_number: int

cells instance-attribute

cells: tuple[Position, ...]

edges instance-attribute

edges: dict[str, EdgeView]

MemberEffectView

Bases: BaseModel

An active effect on a party member — players track their own torches and spells.

character_id instance-attribute

character_id: str

kind instance-attribute

kind: str

remaining_rounds instance-attribute

remaining_rounds: int | None

MemberView

Bases: BaseModel

One member's public sheet: the players know their own characters.

id instance-attribute

id: str

name instance-attribute

name: str

class_id instance-attribute

class_id: str

level instance-attribute

level: int

current_hp instance-attribute

current_hp: int

max_hp instance-attribute

max_hp: int

conditions instance-attribute

conditions: tuple[str, ...]

inventory instance-attribute

inventory: dict

memorized_spells instance-attribute

memorized_spells: tuple[dict, ...]

PileView

Bases: BaseModel

A known dropped pile in explored space.

items instance-attribute

items: tuple[str, ...]

coins_gp_value instance-attribute

coins_gp_value: int

PlayerView

Bases: BaseModel

The safe projection: an enumerated whitelist of exactly the fields a player may see.

adventure_name instance-attribute

adventure_name: str

adventure_description instance-attribute

adventure_description: str

town_name instance-attribute

town_name: str

town_description instance-attribute

town_description: str

town_services instance-attribute

town_services: tuple[str, ...]

party instance-attribute

party: tuple[MemberView, ...]

location instance-attribute

location: PartyLocation

clock_rounds instance-attribute

clock_rounds: int

mode instance-attribute

mode: str

explored instance-attribute

explored: tuple[ExploredLevelView, ...]

piles instance-attribute

piles: dict[str, PileView]

emptied_caches instance-attribute

emptied_caches: tuple[str, ...]

effects instance-attribute

effects: tuple[MemberEffectView, ...]

fatigued instance-attribute

fatigued: bool

exhausted instance-attribute

exhausted: bool

deprivation instance-attribute

deprivation: dict[str, dict[str, int]]

encounter class-attribute instance-attribute

encounter: EncounterView | None = None

RefereeView

Bases: BaseModel

The full state projection minus RNG internals, for LLM referees and tests.

state instance-attribute

state: dict

build_player_view

build_player_view(session) -> PlayerView

Build the player view from session state (never from the event log).

Parameters:

Name	Type	Description	Default
session	GameSession	The running session.	required

Returns:

Type	Description
PlayerView	The frozen whitelist projection.

build_referee_view

build_referee_view(session) -> RefereeView

Build the referee view: everything but RNG internals and the seed.

Parameters:

Name	Type	Description	Default
session	GameSession	The running session.	required

Returns:

Type	Description
RefereeView	The full-state projection.