Usage Guide =========== This guide covers how to use the PipeWorks MUD Mapper to create and edit maps for your MUD world. 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). Typical workflow:: 1. Create/edit map → SQLite DB (data/mapper.db) 2. Save changes → Preserves coordinates for future editing 3. Export Zone JSON → data/zones/my_zone.json (coords stripped) Starting the Application ------------------------ From the command line:: python -m pipeworks_mud_mapper Or with custom settings:: python -c "from pipeworks_mud_mapper.app import run_app; run_app(debug=False, port=8080)" The application will be available at http://127.0.0.1:8050 (or your custom port). Interface Overview ------------------ The mapper has a three-column layout: **Left Column - Game Server Exports** Shows the exported zone JSON files in the configured zones directory. This helps verify what the server will consume. **Center Column - Map View** Interactive Plotly graph showing rooms as nodes and exits as connecting lines. Click rooms to select them. Use the Z-level selector below the map to view different floors. **Right Column - Properties Panel** Form for editing room properties. Shows room ID, name, description, coordinates, and exit checkboxes. Also includes the Ollama LLM integration section for generating room descriptions. **Workspace Panel (Center Column)** Tabs for SQLite status, room lists, cross-zone exits, and the API runner. The **API** tab lets you save remote service definitions and run HTTP commands directly from the UI. Workspace API Runner -------------------- The **Workspace → API** tab can store remote API definitions and reusable commands (GET/POST/etc). This is useful for calling external services like the Pipeworks Name Generation API without leaving the mapper UI. **Configuration** The API catalog is stored in its own SQLite database. You can change the location via ``config/server.ini``: .. code-block:: ini [paths] api_db_path = data/api_services.db **Basic Workflow** 1. Create a **Service** with a name and base URL (for example, ``https://name.api.pipe-works.org``). 2. Add a **Command** (method, path, optional query/body JSON). 3. Click **Run** to execute; the response appears in the panel below. **Notes** - Query and body fields require valid JSON. - Service auth secrets are stored as plain text until a vault integration is added. Creating a New Map ------------------ 1. Click the **New Map** button in the action row 2. Enter a **Zone ID** (lowercase, no spaces, e.g., ``my_dungeon``) 3. Enter a **Zone Name** (display name, e.g., ``My Dungeon``) 4. Optionally add a **Description** 5. Click **Create** The new map is stored in SQLite. You can export map/zone JSON when needed. Adding Rooms ------------ 1. Click **New Room** in the action row 2. Enter a unique **Room ID** (e.g., ``hallway_north``) 3. Enter a **Room Name** (e.g., ``Northern Hallway``) 4. Add a **Description** (optional) 5. Set **Coordinates** (X, Y, Z) to position the room on the map 6. Click **Add Room** The room appears on the map at the specified coordinates. Editing Rooms ------------- 1. Click a room on the map to select it (turns red) 2. The properties panel fills with the room's current values 3. Modify the name, description, or coordinates 4. Click **Update** to save changes Note: Room ID cannot be changed after creation. Managing Exits -------------- Exits connect rooms together. The mapper creates bidirectional exits by default. **Adding Exits** 1. Select a room on the map 2. Check the direction checkboxes (N, E, S, W, U, D) in the Exits section 3. The mapper finds the nearest room in that direction and creates: - An exit from the current room to the target - A reverse exit from the target back to current room 4. If no room exists in that direction, the checkbox unchecks and shows a warning **Removing Exits** 1. Select a room with exits 2. Uncheck the direction checkbox 3. The exit is removed (but the reverse exit on the other room remains) To create one-way exits, add the exit, then select the target room and uncheck the reverse direction. Generating Descriptions with Ollama ----------------------------------- The mapper integrates with a local Ollama server to generate room descriptions using LLMs. **Setup** 1. Install Ollama from https://ollama.ai 2. Pull a model (e.g., ``ollama pull llama3.2``) 3. Ensure Ollama is running (default: http://localhost:11434) **Using the LLM Generator** 1. In the center column, open the **LLM Assistant (Ollama)** panel beneath the map 2. Enter the Ollama server URL (default: http://localhost:11434) 3. Click **Refresh Models** to load available models 4. Select a model from the dropdown 5. Customize the system prompt (optional) and enter a user prompt 6. Click **Generate** to create a description 7. Review the generated text in the response area 8. Click **Send to Description** to apply it to the selected room **Tips** - The system prompt sets the tone and style for generated descriptions - The user prompt should describe what you want (e.g., "A dark cellar with cobwebs") - You can edit the generated text before sending it to the room - Generation marks the room as having unsaved changes - A validator staging panel shows hard-rule hits without blocking authors - Validator results are saved into the map file as authoring metadata Template Strategy ^^^^^^^^^^^^^^^^^ Templates strongly influence length and style. The default Ledgerfall template is optimized for 60–120 word outputs. For short outputs, use the dedicated short template: - ``Ledgerfall Goblin (Short)`` (``ledgerfall_goblin_short``) for 25–40 words - ``Ledgerfall Goblin`` (``ledgerfall_goblin``) for 60–120 words If you request 30 words while using the long template, small models often drift longer because the examples are longer than your target. Length Control (Target Words vs Tokens) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Length is controlled by two knobs: - **Target Words** (template guidance): sets the suggested word range in the system prompt. - **Max Tokens (num_predict)**: hard ceiling on output length. For short descriptions, set **Max Tokens** low enough to prevent rambling: - 30 words ≈ 40–50 tokens → set ``num_predict`` to **60–80** - 60 words ≈ 80–90 tokens → set ``num_predict`` to **110–140** If ``num_predict`` is very high (e.g., 512), small models will often overshoot. Sampling Controls (Temperature, Top-P, Top-K) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ These parameters shape verbosity and drift: - **Temperature**: lower = tighter, higher = more wandering. Try **0.4–0.6** for short outputs, **0.7–0.9** for longer. - **Top-P**: lower = less variety. Try **0.7–0.85** for short outputs. - **Top-K**: lower = more focused. Try **20–40** for short outputs. Short Output Checklist ^^^^^^^^^^^^^^^^^^^^^^ If you need 25–40 words: - Use ``ledgerfall_goblin_short`` - Set ``num_predict`` to 60–80 - Use a strict user prompt: “Write 30 words exactly. One paragraph.” - Keep Temperature ≤ 0.6 and Top-P ≤ 0.85 Saving and Exporting -------------------- **Saving Maps** Changes are tracked but not automatically saved. The status indicator at the bottom shows: - **Gray dot**: No file loaded - **Yellow dot**: Unsaved changes (Save enabled, Export disabled) - **Green dot**: All changes saved (Save disabled, Export enabled) Click **Save** to persist changes to the SQLite database. **Exporting Zone Files** Once your map is saved, click **Export Zone JSON** to create the game truth file: - Exported to ``data/zones/{zone_id}.json`` - Coordinates are stripped (game engine doesn't need them) - Room IDs, names, descriptions, and exits are preserved The exported zone file is what the MUD server consumes. Validating Your Map ------------------- The **Validate Zone** button runs comprehensive checks on your map to catch common issues before export. **Validation Categories** *Connectivity* - **Broken exits**: Exits pointing to non-existent rooms (ERROR) - **Unreachable rooms**: Rooms with no path from spawn (WARNING) - **Dead ends**: Rooms with no exits (INFO) *Exit Consistency* - **Asymmetric exits**: Room A→B exists but B→A doesn't (INFO) - **Direction mismatch**: Exit says "north" but coordinates suggest "south" (WARNING) *Language-Direction* - **Vertical naming conflicts**: Room named "Upper Landing" not reached via "up" (INFO) **Severity Levels** - **ERROR**: Must be fixed before export (e.g., broken references) - **WARNING**: Should be reviewed but may be intentional - **INFO**: Informational only (e.g., intentional one-way doors) **Validation Report** When you validate, a JSON report is written to ``data/validation/{zone_id}.validation.json``. This file contains: - Timestamp of validation - Summary counts by severity - Pass/fail status (passes if no errors) - Detailed list of all warnings The report file is useful for CI/CD integration or keeping records. **Using Validation** 1. Load a map file 2. Click **Validate Zone** in the file browser 3. Review the results modal showing any issues 4. Click on room IDs in the modal to select them on the map 5. Fix issues and re-validate as needed 6. Export once validation passes Keyboard Shortcuts ------------------ Currently, the mapper is mouse-driven. Keyboard shortcuts may be added in future versions. Tips and Best Practices ----------------------- **Room Naming** Use consistent naming conventions for room IDs. Consider prefixing with area names (e.g., ``tavern_common_room``, ``tavern_kitchen``). **Coordinate Planning** Plan your coordinate grid before building. Common approaches: - Unit spacing: Each room 1 unit apart - Grid spacing: Rooms at 5-unit intervals - Logical spacing: Match the "feel" of distances **Z-Levels** Use Z-levels for multi-story buildings, dungeons, or elevation changes. Connect levels with "up" and "down" exits. **Incremental Saving** Save frequently to avoid losing work. The mapper doesn't auto-save. **Export When Ready** Export zone files when your map is ready for testing in the MUD server. Keep editing the map file; re-export when you make changes. **Version Control** Both map files and zone files are JSON and work well with git. Commit map files as your source of truth; zone files are derived.