pipeworks_mud_mapper.services.world_service
===========================================

.. py:module:: pipeworks_mud_mapper.services.world_service

.. autoapi-nested-parse::

   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
---------

.. autoapisummary::

   pipeworks_mud_mapper.services.world_service.load_world_json
   pipeworks_mud_mapper.services.world_service.load_world_zone_ids
   pipeworks_mud_mapper.services.world_service.load_zone_room_ids


Module Contents
---------------

.. py:function:: load_world_json(world_path = None, zones_dir = None)

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


.. py:function:: load_world_zone_ids(zones_dir = None, world_path = None)

   Return the list of zone IDs known to the world.

   :param zones_dir: Optional override for the zones directory. When omitted, the path
                     from ``config/server.ini`` (or defaults) is used.
   :type zones_dir: :py:class:`Path | None`
   :param world_path: Optional override for the world.json path. Defaults to the configured
                      world_json_path, or to the parent of zones_dir when provided.
   :type world_path: :py:class:`Path | None`

   :returns: Sorted list of zone IDs. Returns an empty list if no zones are found.
   :rtype: :py:class:`list[str]`


.. py:function:: load_zone_room_ids(zone_id, zones_dir = None)

   Return room IDs for a specific zone export.

   :param zone_id: Zone ID to read from ``<zones_dir>/<zone_id>.json``.
   :type zone_id: :py:class:`str`
   :param zones_dir: Optional override for the zones directory. When omitted, the path
                     from ``config/server.ini`` (or defaults) is used.
   :type zones_dir: :py:class:`Path | None`

   :returns: Sorted list of room IDs for the zone. Empty if the zone file is
             missing or invalid.
   :rtype: :py:class:`list[str]`