mud_server.core.world

World data management and structures.

This module defines the world data structures (rooms and items) and provides the World class for loading and querying world data. The world is loaded from JSON files at server startup and kept in memory for fast access.

World Structure: - Rooms: Named locations with descriptions, exits to other rooms, and items - Items: Objects that can be found in rooms and picked up by players - Exits: Directional connections between rooms (north, south, east, west, up, down) - Zones: Collections of related rooms loaded from separate files

Data Storage (Zone-based - preferred): - World registry: data/world.json (zone list, global config) - Zone files: data/zones/<zone_id>.json (rooms and items per zone)

Data Storage (Legacy - fallback): - Single file: data/world_data.json (all rooms and items)

Design Notes: - Rooms and items are identified by unique string IDs - Exits are one-way unless defined in both rooms - Items in rooms are shared (multiple players can pick up same item) - Room descriptions are generated dynamically to include current state - Cross-zone exits use “zone:room” format (e.g., “docks:east_pier”)

Attributes

`logger`
`DATA_DIR`
`WORLD_JSON_PATH`
`ZONES_DIR`

Classes

`Room`	Represents a room/location in the MUD world.
`Item`	Represents an item/object in the MUD world.
`Zone`	Represents a zone/region in the MUD world.
`World`	Manages the MUD world data, providing access to rooms and items.

Module Contents

mud_server.core.world.logger

mud_server.core.world.DATA_DIR

mud_server.core.world.WORLD_JSON_PATH

mud_server.core.world.ZONES_DIR

class mud_server.core.world.Room[source]

Represents a room/location in the MUD world.

Rooms are the fundamental spatial unit of the game world. Players move between rooms using directional exits. Each room can contain items and multiple players.

id: Unique identifier for this room (e.g., “spawn”, “forest_1”)

name: Human-readable name displayed to players (e.g., “Spawn Zone”)

description: Detailed description of the room’s appearance

exits: Dictionary mapping directions to destination room IDs Format: {“north”: “forest_1”, “south”: “desert_1”}

items: List of item IDs currently in this room

Example

Room(: id=”spawn”, name=”Spawn Zone”, description=”You stand in a peaceful plaza…”, exits={“north”: “forest_1”, “south”: “desert_1”}, items=[“torch”, “rope”]

)

id: str

name: str

description: str

exits: dict[str, str]

items: list[str]

class mud_server.core.world.Item[source]

Represents an item/object in the MUD world.

Items can be found in rooms and picked up by players. They are stored in player inventories and can be dropped back into rooms.

id: Unique identifier for this item (e.g., “torch”, “sword_1”)

name: Human-readable name displayed to players (e.g., “Rusty Torch”)

description: Detailed description of the item’s appearance

Example

Item(: id=”torch”, name=”Rusty Torch”, description=”A flickering torch that barely lights the way.”

)

Note

Items currently have no gameplay mechanics (no stats, durability, etc.) They are purely for inventory and flavor. Future enhancements could add item types, usability, combat stats, etc.

id: str

name: str

description: str

class mud_server.core.world.Zone[source]

Represents a zone/region in the MUD world.

Zones are collections of related rooms loaded from separate JSON files. Each zone has its own spawn point and can define zone-specific items.

id: Unique identifier for this zone (e.g., “crooked_pipe”, “docks”)

name: Human-readable name (e.g., “Crooked Pipe District”)

description: Description of the zone’s theme/purpose

spawn_room: Default room ID for players entering this zone

rooms: List of room IDs belonging to this zone

Example

Zone(: id=”crooked_pipe”, name=”Crooked Pipe District”, description=”A warren of goblin pubs…”, spawn_room=”spawn”, rooms=[“spawn”, “front_parlour”, “back_parlour”, …]

)

id: str

name: str

description: str

spawn_room: str

rooms: list[str] = []

class mud_server.core.world.World(*, world_root=None)[source]

Manages the MUD world data, providing access to rooms and items.

This class is instantiated once at server startup and loads all world data from JSON files into memory. It supports two loading modes:

Zone-based (preferred): Loads world.json registry + individual zone files
Legacy (fallback): Loads single world_data.json file

rooms: Dictionary mapping room IDs to Room objects

items: Dictionary mapping item IDs to Item objects

zones: Dictionary mapping zone IDs to Zone objects

default_spawn: Tuple of (zone_id, room_id) for new player spawn

world_name: Name of the world (from world.json)

Design Notes:

World data is immutable after loading (read-only)
All data kept in memory for fast access
No database storage for world data (uses JSON files)
Changes to JSON require server restart to take effect
Zone-based loading allows modular world building

Initialize the World by loading data from JSON files.

Loads zone-based data (world.json + zones/).

Parameters:

world_root (pathlib.Path | None) – Optional path to a world package directory. When provided, world.json and zones are loaded relative to this directory.

Raises:

FileNotFoundError – If no world data files exist
JSONDecodeError – If JSON files are malformed
KeyError – If required fields are missing from JSON

rooms: dict[str, Room]

items: dict[str, Item]

zones: dict[str, Zone]

world_name: str = 'Unknown World'

default_spawn: tuple[str, str] = ('', 'spawn')

world_id: str

get_translation_service()[source]

Return the OOCToICTranslationService for this world, or None.

Callers must check for None before use. A None return means the translation layer is either disabled in config, failed to initialise, or this world has no translation_layer block.

Returns:: OOCToICTranslationService instance, or None.

get_world_root()[source]

Return the on-disk root directory for this world package, if any.

get_world_json_path()[source]

Return the resolved world.json path for this world instance.

reload_translation_service(world_data)[source]

Rebuild the translation service from the provided world.json payload.

This is used by runtime admin flows that update translation-layer configuration on disk and need the in-memory service to reflect the new canonical world state without a full server restart.

translation_layer_enabled()[source]

Return True if the translation service is configured and active.

Returns:: True if a live OOCToICTranslationService is attached; False otherwise.
Return type:: bool

get_axis_engine()[source]

Return the AxisEngine for this world, or None.

Callers must check for None before use. A None return means the axis engine is either disabled in world.json, failed to initialise, or this world has no axis_engine block.

Returns:: AxisEngine instance, or None.

reload_axis_engine(world_data)[source]

Rebuild the axis engine from the provided world.json payload.

This is used by runtime promotion flows that rewrite canonical policy files and need the in-memory engine to reload against the latest package contents.

axis_resolution_enabled()[source]

Return True if the axis engine is configured and active.

Returns:: True if a live AxisEngine is attached; False otherwise.
Return type:: bool

resolve_room(room_ref)[source]

Resolve a room reference to a Room object.

Handles both simple room IDs and cross-zone references (zone:room). Currently all rooms are stored in a flat namespace, so the zone prefix is parsed but the room is looked up by ID only.

Parameters:: room_ref (str) – Room reference (e.g., “spawn” or “docks:east_pier”)
Returns:: Room object if found, None if room doesn’t exist
Return type:: Room | None

Example

>>> world.resolve_room("spawn")
Room(id='spawn', ...)
>>> world.resolve_room("docks:east_pier")
Room(id='east_pier', ...)  # Looks up 'east_pier' in rooms

get_room(room_id)[source]

Retrieve a room by its ID.

For cross-zone references (zone:room format), use resolve_room() instead.

Parameters:: room_id (str) – Unique room identifier (e.g., “spawn”, “forest_1”)
Returns:: Room object if found, None if room doesn’t exist
Return type:: Room | None

Example

>>> world.get_room("spawn")
Room(id='spawn', name='Spawn Zone', ...)
>>> world.get_room("nonexistent")
None

get_item(item_id)[source]

Retrieve an item by its ID.

Parameters:: item_id (str) – Unique item identifier (e.g., “torch”, “sword_1”)
Returns:: Item object if found, None if item doesn’t exist
Return type:: Item | None

Example

>>> world.get_item("torch")
Item(id='torch', name='Rusty Torch', ...)
>>> world.get_item("nonexistent")
None

get_room_description(room_id, username, *, world_id)[source]

Generate a detailed, formatted description of a room.

Creates a comprehensive room description including: - Room name and description - Items present in the room - Other players in the room (excluding the requesting player) - Available exits with destination names

Parameters:

room_id (str) – ID of the room to describe
username (str) – Username of the player requesting description (excluded from the player list)

Returns:

Formatted multi-line string with complete room information Returns “Unknown room.” if room_id doesn’t exist

Return type:

str

Format:

=== Room Name === Room description text here.

[Items here]:

Item Name 1
Item Name 2

[Players here]:

Player1
Player2

[Exits]:

north: Destination Room Name
south: Another Room Name

Example

>>> world.get_room_description("spawn", "player1")
'''
=== Spawn Zone ===
You stand in a peaceful plaza...

[Items here]:

Torch
Rope

[Players here]:

player2
admin

[Exits]:

north: Enchanted Forest
south: Golden Desert

‘’’

can_move(room_id, direction)[source]

Check if movement in a direction is valid and get the destination.

Validates that: 1. The current room exists 2. The room has an exit in the specified direction 3. The destination room exists (supports cross-zone exits)

Cross-zone exits use “zone:room” format (e.g., “docks:east_pier”). The zone will be lazy-loaded if not already present.

Parameters:

room_id (str) – Current room ID
direction (str) – Direction to move (e.g., “north”, “south”, “east”, “west”) Case-insensitive

Returns:

Tuple of (can_move, destination_room_id) - (True, “room_id”): Movement is valid, destination is the room ID - (False, None): Movement is invalid

Return type:

tuple[bool, str | None]

Example

>>> world.can_move("spawn", "north")
(True, "forest_1")
>>> world.can_move("spawn", "west")
(False, None)  # No west exit
>>> world.can_move("pub_entrance", "west")
(True, "east_pier")  # Cross-zone exit "docks:east_pier" resolves to "east_pier"