pipeworks_mud_mapper.services.zone_service

Zone service for file I/O operations.

This module handles loading, saving, and exporting zone/map files. It supports the export workflow described in goblin_cartography.md:

• Map JSON exports (*.map.json): Authoring exports with coordinates

• Zone JSON exports (*.json): Game truth without coordinates

The Export Workflow

::

Author edits: SQLite DB (data/mapper.db)

│ ▼

┌─────────────┐ │ MapFile │ (in memory) └──────┬──────┘

│

┌─────────────┴─────────────┐ ▼ ▼

save_map_file() export_zone()

│ │ ▼ ▼

data/exports/maps/*.map.json data/zones/my_zone.json (authoring export) (game truth, no coords)

File Format Detection

The service detects file type by:

1. Extension: .map.json = map file, .json = zone file

2. Content: presence of coords in rooms indicates map file

When loading a zone file (no coords), rooms are auto-placed at origin. A warning is returned to indicate coordinates need assignment.

Examples

Loading a map file:

from pathlib import Path
from pipeworks_mud_mapper.services import zone_service

map_file = zone_service.load_map_file(Path("data/exports/maps/tutorial.map.json"))

Saving changes:

zone_service.save_map_file(map_file, Path("data/exports/maps/tutorial.map.json"))

Exporting for game server:

zone_service.export_zone(map_file, Path("data/zones/tutorial.json"))

Creating a new zone:

map_file = zone_service.create_new_map_file(
    zone_id="new_zone",
    name="New Zone",
    spawn_room_name="Starting Room",
)

See also

-, -, -

Functions

load_map_file(path)	Load a map file from disk.
save_map_file(map_file, path, *[, bump_revision])	Save a map file to disk.
export_zone(map_file, path)	Export a map file as a zone file (strips coordinates and authoring metadata).
create_new_map_file(zone_id, name[, spawn_room_name, ...])	Create a new empty map file with a spawn room.
load_zone(path)	Load a zone file (game truth format).
get_suggested_export_path(map_path[, zones_dir])	Get the suggested zone export path for a map file.
list_map_files(directory)	List map files in a directory.
list_zone_files(directory)	List zone files in a directory.

Module Contents

pipeworks_mud_mapper.services.zone_service.load_map_file(path)

Load a map file from disk.

Handles both map files (with coords) and zone files (without coords). When loading a zone file, rooms are placed at origin with a warning.

Parameters:

path (Path) – Path to the map or zone file.

Returns:

The loaded map file, ready for editing.

Return type:

MapFile

Raises:

• FileNotFoundError – If the file does not exist.

• json.JSONDecodeError – If the file is not valid JSON.

• pydantic.ValidationError – If the JSON does not match the expected schema.

Examples

>>> map_file = load_map_file(Path("data/exports/maps/tutorial.map.json"))
>>> len(map_file.rooms)
5

pipeworks_mud_mapper.services.zone_service.save_map_file(map_file, path, *, bump_revision=True)

Save a map file to disk.

Saves in the legacy format with coords as [x, y, z] lists for compatibility with existing tools and data files.

Parameters:

• map_file (MapFile) – The map file to save.

• path (Path) – Destination path. Parent directories are created if needed.

• bump_revision (bool, optional) – When True, increment metadata.map_revision before saving. This is the default for explicit save actions.

Examples

>>> save_map_file(map_file, Path("data/exports/maps/tutorial.map.json"))

pipeworks_mud_mapper.services.zone_service.export_zone(map_file, path)

Export a map file as a zone file (strips coordinates and authoring metadata).

This creates the “game truth” file that the MUD server consumes. Coordinates and LLM generation metadata are removed because the game engine operates on topology (connections) not geometry (positions), and doesn’t need authoring provenance data.

Stripped Fields

The following “authoring scaffolding” fields are removed during export:

• coords: Room coordinates are visualization aids, not game state. Movement in a MUD is topological (room A connects to room B via “north”), not metric (room B is at position [1, 0, 0]).

• llm_generation: LLM generation metadata (model, seed, prompts, etc.) exists for authoring purposes only - it enables reproducibility and provenance tracking during map creation, but has no meaning to the game server.

This separation reflects the pipe-works philosophy that authoring scaffolding supports the creation process but is not part of the final game state.

param map_file:

The map file to export.

type map_file:

MapFile

param path:

Destination path for the zone file.

type path:

Path

Examples

>>> export_zone(map_file, Path("data/zones/tutorial.json"))

Notes

The exported zone file can be loaded back, but coordinates and LLM metadata will be lost. Always keep the original map file as the authoring source.

See also

MapRoom.to_room

Primary stripping mechanism (model conversion).

OllamaGenerationInfo

The metadata model that gets stripped.

pipeworks_mud_mapper.services.zone_service.create_new_map_file(zone_id, name, spawn_room_name='Spawn Room', description='')

Create a new empty map file with a spawn room.

Parameters:

• zone_id (str) – Unique identifier for the zone (e.g., “tutorial_area”).

• name (str) – Human-readable display name (e.g., “Tutorial Area”).

• spawn_room_name (str, default "Spawn Room") – Display name for the initial spawn room.

• description (str, optional) – Zone description text.

Returns:

A new map file with a single spawn room at origin.

Return type:

MapFile

Examples

>>> map_file = create_new_map_file(
...     zone_id="my_dungeon",
...     name="My Dungeon",
...     spawn_room_name="Entrance Hall",
... )
>>> map_file.spawn_room
'spawn'
>>> map_file.rooms["spawn"].name
'Entrance Hall'

pipeworks_mud_mapper.services.zone_service.load_zone(path)

Load a zone file (game truth format).

This loads a zone file without coordinates. Use this when you need to work with the game truth format directly.

Parameters:

path (Path) – Path to the zone file.

Returns:

The loaded zone.

Return type:

Zone

Examples

>>> zone = load_zone(Path("data/zones/tutorial.json"))

pipeworks_mud_mapper.services.zone_service.get_suggested_export_path(map_path, zones_dir=None)

Get the suggested zone export path for a map file.

Converts data/exports/maps/foo.map.json to data/zones/foo.json.

Parameters:

• map_path (Path) – Path to the map file.

• zones_dir (Path | None) – Optional override for the zones directory. When provided, exports will be placed in this directory regardless of the map path.

Returns:

Suggested path for the exported zone file.

Return type:

Path

Examples

>>> get_suggested_export_path(Path("data/exports/maps/tutorial.map.json"))
PosixPath('data/zones/tutorial.json')

pipeworks_mud_mapper.services.zone_service.list_map_files(directory)

List map files in a directory.

Returns sorted *.map.json files for map export inspection.

pipeworks_mud_mapper.services.zone_service.list_zone_files(directory)

List zone files in a directory.

Returns sorted *.json files for the zone file browser.