PipeWorks MUD Server

User Guide

  • Getting Started
    • Prerequisites
    • Installation
      • Clone and Setup
      • Initialize Database
      • Create Superuser
    • Running the Server
      • Start the Server
    • First Login
    • Creating Your First World
    • Development Setup
    • Running Components Separately
      • API Server Only
      • Admin TUI (Terminal Interface)
    • Guest Registration
      • Example: POST /register (client-supplied username)
      • Example: POST /register-guest (server-generated username)
      • Example: POST /characters/create (self-service generated name)
    • Environment Variables
    • CLI Reference
    • Next Steps
  • Architecture
    • Overview
    • Three-Tier Design
    • Chat Interaction Data Flow
    • WebUI Architecture
    • Package Layout
    • World Package Layout
    • System Components
      • Backend (FastAPI)
      • Game Engine
      • Axis Engine
      • JSONL Ledger
      • Translation Layer
      • Event Bus Architecture
      • Database Layer
    • Data Flow
    • Technology Stack
    • Key Design Patterns
      • Session Management
      • Role-Based Access Control
      • Command Pattern
      • Repository Pattern
      • Ledger-First Authority
      • Known Limitations
    • Performance
      • Current Capacity
      • Scaling Considerations
  • Database
    • Current Database Schema
    • Notes
  • Axis State System
    • Overview
    • Canonical Policy Objects (DB)
    • Resolution Grammar
      • Grammar Dataclasses
    • Resolver Functions
      • dominance_shift
      • shared_drain
      • no_effect
    • Axis Engine
      • Resolution Sequence
      • Result Dataclasses
      • IPC Hash and Ledger Linkage
      • Locking Model
    • World Integration
    • Policy Validation Report
    • Registry Seeding
    • Event Application
    • Admin Inspection
    • Database Tables (Authoritative)
    • Snapshots (Derived)
    • Multi-World Isolation
    • Why Normalised + JSON?
  • JSONL Ledger
    • Overview
    • File Location
    • Startup Integrity Check
    • Envelope Format
    • Checksum Verification
    • File Locking
    • Event Types
      • chat.mechanical_resolution
      • chat.translation
      • ipc_hash Linkage
    • Pre-Axis-Engine Era
    • Python API
      • append_event()
      • verify_world_ledger()
    • Hardening Notes
  • Translation Layer
    • Overview
    • Configuration
    • Translation Pipeline
    • System Prompt Template
    • Canonical Prompt Management
    • PASSTHROUGH Sentinel
    • Character Profile Builder
    • Axis Snapshot in Ledger Events
    • IPC Hash and Deterministic Mode
    • Per-World Enable/Disable
    • Hardening Notes
  • Axis Descriptor Lab Integration
    • Overview
    • Active Lab API Surface
    • Removed Legacy Routes (Breaking)
    • Operational Flow (DB-Only)
  • Admin Axis Inspector
    • Overview
    • Access
    • What You Are Looking At
    • Axis State Panel
    • Axis Events Panel
    • Policy Validation Report
    • Debugging Workflow
    • Common Issues
    • Security Notes
  • Security
    • Password Security
      • Password Policy
      • Password Hashing
      • Common Password Detection
    • Authentication
      • Session Management
      • Role-Based Access Control
      • Guest Accounts
    • API Security
      • Request Validation
      • CORS Configuration
      • Error Handling
    • Database Security
      • SQLite Security
      • Input Sanitization
    • Security Checklist
      • Development
      • Production
    • Known Limitations
    • Security Contact
    • See Also
  • Admin Web UI Deployment (mTLS)
    • Overview
    • Path Conventions
    • Prerequisites
    • Step 1: Create an Internal CA and Client Certificates
    • Step 2: Install Client Certificates
    • Step 3: Obtain TLS Certificate for the Admin Domain
    • Step 4: Configure the Admin Vhost (mTLS)
    • Step 5: Block /admin on the Public API Domain
    • Step 6: Bind the API Backend to Localhost
    • Step 7: Validate
    • Renewal and Rotation
    • Troubleshooting
  • Play Web UI
    • Overview
    • Routing model
    • Files and structure
    • CSS layering order
    • Play shell sections
    • Account Dashboard Layout (Select-World State)
    • World UI scaffold
    • Creating a new world UI
    • Security note
    • Testing and docs build
    • Local dev + CORS sanity checklist
  • Operator Guide: API-Only Canonical Policy Operations
    • Canonical Source of Truth
    • Artifact Import Workflow
    • init-db Bootstrap Behavior
    • Breaking Change Summary
    • Command Replacement Table
  • Extending the Server
    • Adding New Commands
      • 1. Add Method to GameEngine
      • 2. Add Command Handler
      • 3. Restart Server
    • Extending World Data
      • Adding Room Properties
    • Adding Database Tables
      • Define Schema
      • Add CRUD Functions
      • Add API Endpoint
      • Add Client Wrapper
    • Adding API Endpoints
      • Define Pydantic Model
      • Add Route
    • Testing Strategy
      • Unit Tests
      • Integration Tests
      • API Tests
    • Key Implementation Principles
      • 1. Determinism First
      • 2. Separation of Concerns
      • 3. Data-Driven Design
      • Enabling Subsystems Per World
      • Adding a New Resolver
      • 4. API Stability
    • Best Practices
      • Code Organization
      • Migration Strategy
    • Contributing
  • Examples
    • ASCII Movement Demo
      • Features
      • World Layout
      • Running the Demo
      • API Endpoints Used
      • Request/Response Examples
      • Code Structure
      • Extending the Demo
      • Event Bus Integration
      • CORS Troubleshooting

Reference

  • API Reference
    • Overview
    • Interactive API Docs
    • API Endpoints
      • Authentication
      • Register Guest Examples
      • Character Provisioning (Account Session)
      • World List Metadata
      • Game Actions
      • Admin
      • Health
      • Lab Integration
      • Canonical Policy APIs
      • Pipeline Generation
        • Request body
        • Response (200)
        • Structured error response
        • Operational telemetry
    • Authentication
      • Password Requirements
      • Guest Accounts
      • Session Creation
      • Session Format
    • Role-Based Access
    • Error Handling
      • HTTP Status Codes
      • Error Response Format
    • CORS Configuration
    • WebSocket Support (Future)
    • Python API Documentation
  • Policy Service Package Design
    • Goals
    • Canonical Invariants
    • Package Modules
    • Facade Contract
    • Legacy Removal Scope
    • Testing Expectations
  • Changelog
    • Changelog
      • Unreleased
        • Breaking Changes
        • Migration Notes
      • 0.5.9 (2026-04-13)
        • Features
        • Bug Fixes
        • Documentation
      • 0.5.8 (2026-03-21)
        • Bug Fixes
      • 0.5.7 (2026-03-15)
        • Bug Fixes
        • Documentation
      • 0.5.6 (2026-03-15)
        • Bug Fixes
      • 0.5.5 (2026-03-15)
        • Bug Fixes
      • 0.5.4 (2026-03-15)
        • Features
      • 0.5.3 (2026-03-14)
        • Features
      • 0.5.2 (2026-03-13)
        • Features
      • 0.5.1 (2026-03-13)
        • Bug Fixes
      • 0.5.0 (2026-03-13)
        • ⚠ BREAKING CHANGES
        • Features
        • Bug Fixes
        • Code Refactoring
      • 0.4.22 (2026-03-13)
        • Features
        • Bug Fixes
      • 0.4.21 (2026-03-12)
        • Bug Fixes
      • 0.4.20 (2026-03-12)
        • Features
        • Bug Fixes
      • 0.4.19 (2026-03-11)
        • Features
      • 0.4.18 (2026-03-10)
        • Bug Fixes
      • 0.4.17 (2026-03-10)
        • Bug Fixes
      • 0.4.16 (2026-03-10)
        • Bug Fixes
      • 0.4.15 (2026-03-10)
        • Features
        • Bug Fixes
      • 0.4.14 (2026-03-09)
        • Features
        • Performance Improvements
        • Documentation
      • 0.4.13 (2026-03-08)
        • Bug Fixes
      • 0.4.12 (2026-03-08)
        • Bug Fixes
      • 0.4.11 (2026-03-08)
        • Features
        • Documentation
      • 0.4.10 (2026-03-06)
        • Features
        • Bug Fixes
      • 0.4.9 (2026-03-04)
        • Documentation
      • 0.4.8 (2026-03-04)
        • Features
      • 0.4.7 (2026-03-01)
        • Features
      • 0.4.6 (2026-03-01)
        • Features
      • 0.4.5 (2026-03-01)
        • Bug Fixes
      • 0.4.4 (2026-02-28)
        • Bug Fixes
      • 0.4.3 (2026-02-28)
        • Bug Fixes
      • 0.4.2 (2026-02-28)
        • Features
        • Bug Fixes
      • 0.4.1 (2026-02-27)
        • Bug Fixes
      • 0.4.0 (2026-02-27)
        • Features
        • Bug Fixes
        • Miscellaneous Chores
      • 0.3.11 (2026-02-26)
        • Features
        • Bug Fixes
      • 0.3.10 (2026-02-18)
        • Features
        • Bug Fixes
        • Documentation
      • 0.3.9 (2026-02-16)
        • Features
      • 0.3.8 (2026-02-16)
        • Features
      • 0.3.7 (2026-02-16)
        • Features
      • 0.3.6 (2026-02-15)
        • Features
      • 0.3.5 (2026-02-14)
        • Features
        • Bug Fixes
        • Documentation
      • 0.3.4 (2026-02-14)
        • Features
        • Documentation
      • 0.3.3 (2026-02-13)
        • Documentation
      • 0.3.2 (2026-02-13)
        • Features
        • Bug Fixes
        • Documentation
      • 0.3.1 (2026-02-11)
        • Features
        • Bug Fixes
      • 0.3.0 (2026-02-10)
        • ⚠ BREAKING CHANGES
        • Features
        • Bug Fixes
      • 0.2.10 (2026-02-01)
        • Bug Fixes
      • 0.2.9 (2026-02-01)
        • Features
      • 0.2.8 (2026-01-31)
        • Features
        • Bug Fixes
      • 0.2.7 (2026-01-31)
        • Features
      • 0.2.6 (2026-01-31)
        • Bug Fixes
      • 0.2.5 (2026-01-31)
        • Features
      • 0.2.4 (2026-01-30)
        • Features
      • 0.2.3 (2026-01-30)
        • Features
        • Bug Fixes
        • Documentation
      • 0.2.2 (2026-01-30)
        • Features
        • Bug Fixes
      • 0.2.1 (2026-01-30)
        • Documentation
      • 0.2.0 (2026-01-30)
        • ⚠ BREAKING CHANGES
        • Features
        • Bug Fixes
        • Documentation
      • 0.1.2 (2026-01-27)
        • Bug Fixes
      • 0.1.1 (2026-01-26)
        • Features
        • Bug Fixes

API Documentation

  • API Reference
    • mud_server
      • Version Management
      • Submodules
        • mud_server.admin_tui
        • mud_server.api
        • mud_server.axis
        • mud_server.cli
        • mud_server.config
        • mud_server.core
        • mud_server.db
        • mud_server.ledger
        • mud_server.services
        • mud_server.translation
        • mud_server.web
PipeWorks MUD Server
  • Search

© Copyright 2026, PipeWorks Team.

Built with Sphinx using a theme provided by Read the Docs.