PipeWorks MUD Mapper Documentation

Documentation Status

PipeWorks MUD Mapper is a visual authoring tool for creating and editing MUD (Multi-User Dungeon) zone files. It provides an interactive map editor built with Dash and Plotly, generating JSON zone files compatible with the PipeWorks MUD Server.

Features

  • Visual Map Editor - Interactive 2D map with Plotly-based rendering

  • Room Management - Create, edit, and delete rooms with intuitive form

  • Exit System - Bidirectional exit creation with automatic reverse linking

  • Multi-Level Support - Z-axis filtering for 3D dungeon visualization

  • SQLite + Export Workflow - Authoring in DB, exports for the server

  • Validation - Check for connectivity, consistency, and language-direction issues

  • LLM Integration - Generate room descriptions using local Ollama server

  • Description Validator - Advisory checks for LLM prose constraints

  • Workspace API - Save and run remote API commands from the UI

  • JSON Schema - Editor validation support for map files

SQLite + Export Workflow

The mapper now stores authoring data in SQLite and exports JSON on demand:

Mapper DB (data/mapper.db)

Authoring source of truth with coordinates for visual editing.

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

Optional authoring exports that preserve coordinates.

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

Game truth files exported without coordinates. These are what the MUD server consumes. Coordinates are stripped because the game engine operates on topology (connections), not geometry (positions).

Workflow:

Edit map  →  Save  →  Export Zone JSON
     ↓         ↓              ↓
SQLite DB  Preserved    Coords stripped

Quick Start

Install the mapper:

pip install -e ".[dev]"

Run the application:

python -m pipeworks_mud_mapper

Or from code:

from pipeworks_mud_mapper.app import run_app
run_app(debug=True, port=8050)

Then open http://127.0.0.1:8050 in your browser.

Coordinate System

The mapper uses a 3D Cartesian coordinate system:

  • X-axis: East (+) / West (-)

  • Y-axis: North (+) / South (-)

  • Z-axis: Up (+) / Down (-)

The spawn room is typically placed at origin (0, 0, 0).

Architecture

The mapper follows a modular architecture:

src/pipeworks_mud_mapper/
├── app.py              # Application entry point
├── layout/             # UI structure (Dash components)
├── callbacks/          # Interactivity (Dash callbacks)
├── services/           # Business logic (pure Python)
├── models/             # Domain models (Pydantic)
├── components/         # Reusable Plotly components
└── utils/              # File I/O utilities

This separation enables:

  • Testability - Services can be tested without Dash

  • Maintainability - Clear boundaries between concerns

  • Extensibility - New features can be added in isolation

Contents

User Guide

API Reference

Project

Indices and tables