File Formats

This document describes the JSON formats used by PipeWorks MUD Mapper. The mapper stores authoring data in SQLite and exports JSON for interchange and game deployment.

SQLite + Export Workflow

Map JSON Exports (data/exports/maps/*.map.json)

Optional authoring exports with coordinates. These mirror the SQLite data when you export for sharing or inspection.

Zone JSON Exports (data/zones/*.json)

Game truth files without coordinates. Exported for the MUD server. The game engine operates on topology (connections), not geometry.

data/
├── exports/
│   └── maps/             # Optional authoring exports (with coords)
│       ├── dungeon.map.json
│       └── town.map.json
│
└── zones/                # Game truth (exported, no coords)
    ├── dungeon.json
    └── town.json

Map JSON Export Format

Map JSON exports include coordinates for visualization and mirror the SQLite authoring data.

Extension: .map.json

Location: data/exports/maps/ (default)

JSON Schema: schemas/map-file.schema.json

A JSON Schema is provided for editor validation and autocomplete. To use it, add a $schema reference to your map file:

{
    "$schema": "../../schemas/map-file.schema.json",
    "id": "my_zone",
    ...
}

Basic Structure

{
    "id": "zone_identifier",
    "name": "Human Readable Name",
    "description": "Optional description text",
    "spawn_room": "starting_room_id",
    "rooms": {
        "room_id": {
            "id": "room_id",
            "name": "Room Name",
            "description": "Room description",
            "coords": [0, 0, 0],
            "llm_generation": {
                "model": "gemma2:2b",
                "actual_seed": 123,
                "template_id": "ledgerfall_goblin",
                "temperature": 0.7,
                "top_k": 40,
                "top_p": 0.9,
                "num_ctx": 4096,
                "num_predict": 512,
                "target_words": 300,
                "system_prompt": "You are a Game Master...",
                "user_prompt": "Describe a quiet alley",
                "generated_at": "2026-02-04T08:45:14+00:00"
            },
            "description_validation": {
                "valid": true,
                "hard_failures": [],
                "soft_failures": [],
                "metrics": {
                    "word_count": 52,
                    "target_words": 50,
                    "min_words": 33,
                    "max_words": 58
                },
                "rule_hits": {},
                "validated_at": "2026-02-04T08:46:02+00:00"
            },
            "exits": {"north": "other_room"},
            "items": []
        }
    },
    "items": {}
}

Key difference from zone files: Rooms include authoring metadata (coords, llm_generation, and description_validation).

Zone File Format

Zone files are game truth without coordinates. They are exported from map files and consumed by the MUD server.

Extension: .json

Location: data/zones/

Basic Structure

{
    "id": "zone_identifier",
    "name": "Human Readable Name",
    "description": "Optional description text",
    "spawn_room": "starting_room_id",
    "rooms": {
        "room_id": {
            "id": "room_id",
            "name": "Room Name",
            "description": "Room description",
            "exits": {"north": "other_room"},
            "items": []
        }
    },
    "items": {}
}

Key difference from map files: No coords field in rooms.

Top-Level Fields

These fields are common to both map and zone files:

id

Required. Unique identifier for the zone. Should contain only lowercase letters, numbers, and underscores. Used as the filename (e.g., my_dungeon becomes my_dungeon.json or my_dungeon.map.json).

name

Required. Human-readable display name for the zone.

description

Optional. Description text for the zone.

spawn_room

Required. Room ID where players enter the zone. Must reference an existing room in the rooms dictionary.

rooms

Required. Dictionary mapping room IDs to room objects.

items

Optional. Dictionary of zone-level item definitions (future use).

Room Fields

id

Required. Unique identifier for the room within this zone. Should match the key used in the rooms dictionary.

name

Required. Human-readable display name for the room.

description

Optional. Description text shown when a player enters the room.

coords

Map files only. Array of three integers [x, y, z] representing the room’s position in 3D space. Used by the mapper for rendering. Stripped when exporting to zone files.

llm_generation

Map files only. Metadata about how a description was generated via Ollama (model, prompts, and parameters). Authoring scaffolding only; stripped when exporting to zone files.

description_validation

Map files only. Latest validator output for the room description. Includes rule hits and word count metrics. Authoring scaffolding only; stripped when exporting to zone files.

exits

Optional. Dictionary mapping direction names to target room IDs. Valid directions: north, south, east, west, up, down.

items

Optional. Array of item IDs present in this room.

Coordinate System

The mapper uses a 3D Cartesian coordinate system (map files only):

Axis	Positive Direction	Negative Direction
X	East (+X)	West (-X)
Y	North (+Y)	South (-Y)
Z	Up (+Z)	Down (-Z)

The spawn room is conventionally placed at origin [0, 0, 0].

Exit Directions

Standard exit directions and their coordinate implications:

Direction	Typical Offset
north	Y increases
south	Y decreases
east	X increases
west	X decreases
up	Z increases
down	Z decreases

Cross-Zone Exits

To create exits that lead to other zones, use the format zone_id:room_id:

{
    "exits": {
        "north": "other_zone:entrance"
    }
}

Cross-zone exits are not visualized on the map but are preserved in both map and zone files.

Example Map File

A complete example of a map export (data/exports/maps/tutorial_area.map.json):

{
    "id": "tutorial_area",
    "name": "Tutorial Area",
    "description": "A small area for new players to learn the basics.",
    "spawn_room": "spawn",
    "rooms": {
        "spawn": {
            "id": "spawn",
            "name": "Arrival Chamber",
            "description": "You find yourself in a dimly lit stone chamber.",
            "coords": [0, 0, 0],
            "exits": {
                "north": "hallway"
            },
            "items": []
        },
        "hallway": {
            "id": "hallway",
            "name": "Long Hallway",
            "description": "A narrow hallway stretches before you.",
            "coords": [0, 1, 0],
            "exits": {
                "south": "spawn",
                "north": "exit_room"
            },
            "items": []
        },
        "exit_room": {
            "id": "exit_room",
            "name": "Exit Portal",
            "description": "A shimmering portal leads to the main world.",
            "coords": [0, 2, 0],
            "exits": {
                "south": "hallway",
                "north": "main_world:entrance"
            },
            "items": []
        }
    },
    "items": {}
}

Example Zone File

The same zone exported (data/zones/tutorial_area.json):

{
    "id": "tutorial_area",
    "name": "Tutorial Area",
    "description": "A small area for new players to learn the basics.",
    "spawn_room": "spawn",
    "rooms": {
        "spawn": {
            "id": "spawn",
            "name": "Arrival Chamber",
            "description": "You find yourself in a dimly lit stone chamber.",
            "exits": {
                "north": "hallway"
            },
            "items": []
        },
        "hallway": {
            "id": "hallway",
            "name": "Long Hallway",
            "description": "A narrow hallway stretches before you.",
            "exits": {
                "south": "spawn",
                "north": "exit_room"
            },
            "items": []
        },
        "exit_room": {
            "id": "exit_room",
            "name": "Exit Portal",
            "description": "A shimmering portal leads to the main world.",
            "exits": {
                "south": "hallway",
                "north": "main_world:entrance"
            },
            "items": []
        }
    },
    "items": {}
}

Note: The only difference is the absence of coords fields.

Validation Rules

When creating zones, ensure:

1. All room IDs are unique within the zone

2. All exit targets reference existing rooms (or valid cross-zone references)

3. The spawn_room references an existing room

4. Room IDs start with a letter and contain only alphanumeric characters and underscores

5. Coordinates are integers (not floats) - map files only

The mapper validates these rules when saving and shows errors for violations.