pipeworks_mud_mapper.services.world_service

World metadata helpers for cross-zone navigation.

The mapper needs a lightweight way to discover which zones exist and what rooms they expose so we can build cross-zone exit pickers. The MUD server stores this information in world.json alongside the exported zone files.

This module provides best-effort readers that:

  • Prefer world.json when present (authoritative list of zones)

  • Fall back to enumerating zone files if the world file is missing

  • Gracefully handle missing or malformed data

Functions

load_world_json([world_path, zones_dir])

Load the world.json payload as a dictionary when available.

load_world_zone_ids([zones_dir, world_path])

Return the list of zone IDs known to the world.

load_zone_room_ids(zone_id[, zones_dir])

Return room IDs for a specific zone export.

Module Contents

pipeworks_mud_mapper.services.world_service.load_world_json(world_path=None, zones_dir=None)[source]

Load the world.json payload as a dictionary when available.

pipeworks_mud_mapper.services.world_service.load_world_zone_ids(zones_dir=None, world_path=None)[source]

Return the list of zone IDs known to the world.

Parameters:

  • zones_dir (Path | None) – Optional override for the zones directory. When omitted, the path from config/server.ini (or defaults) is used.

  • world_path (Path | None) – Optional override for the world.json path. Defaults to the configured world_json_path, or to the parent of zones_dir when provided.

Returns:

Sorted list of zone IDs. Returns an empty list if no zones are found.

Return type:

list[str]

pipeworks_mud_mapper.services.world_service.load_zone_room_ids(zone_id, zones_dir=None)[source]

Return room IDs for a specific zone export.

Parameters:

  • zone_id (str) – Zone ID to read from <zones_dir>/<zone_id>.json.

  • zones_dir (Path | None) – Optional override for the zones directory. When omitted, the path from config/server.ini (or defaults) is used.

Returns:

Sorted list of room IDs for the zone. Empty if the zone file is missing or invalid.

Return type:

list[str]