PipeWorks MUD Server

A deterministic, procedural multiplayer text game engine for building accountable interactive fiction worlds.

A modern, extensible MUD (Multi-User Dungeon) server framework built with Python, FastAPI, and Gradio. Provides a solid foundation for creating text-based multiplayer games with deterministic mechanics, JSON-driven world data, and clean architecture.

User Guide

• Getting Started
  • Prerequisites
  • Installation
  • Running the Server
  • First Login
  • Creating Your First World
  • Development Setup
  • Running Components Separately
  • Guest Registration
  • Environment Variables
  • CLI Reference
  • Next Steps
• Architecture
  • Overview
  • Three-Tier Design
  • Modular Client Architecture
  • System Components
  • Data Flow
  • Technology Stack
  • Key Design Patterns
  • Database Schema
  • Security Considerations
  • Performance
• Database
  • Current Database Schema
  • Notes
• Security
  • Password Security
  • Authentication
  • API Security
  • Database Security
  • Security Checklist
  • Known Limitations
  • Security Contact
  • See Also
• Extending the Server
  • Adding New Commands
  • Extending World Data
  • Adding Database Tables
  • Adding API Endpoints
  • Testing Strategy
  • Key Implementation Principles
  • Best Practices
  • Contributing
• Examples
  • ASCII Movement Demo

Reference

• API Reference
  • Overview
  • Interactive API Docs
  • API Endpoints
  • Authentication
  • Role-Based Access
  • Error Handling
  • CORS Configuration
  • WebSocket Support (Future)
  • Python API Documentation
• Changelog
  • Changelog

API Documentation

• API Reference
  • mud_server
    • Submodules

Key Features

• Deterministic: Same seed always produces same game state

• Data-driven: JSON world definitions, no code changes needed

• Modern stack: FastAPI + Gradio + SQLite

• Secure: CLI-based superuser management, bcrypt passwords

• Extensible: Modular architecture, clean API

• Well-tested: Comprehensive test suite with coverage

Quick Start

Installation:

# Clone the repository
git clone https://github.com/pipe-works/pipeworks_mud_server.git
cd pipeworks_mud_server

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

# Initialize database and create superuser
mud-server init-db
mud-server create-superuser

init-db bootstraps the schema and can also create the initial superuser if MUD_ADMIN_USER and MUD_ADMIN_PASSWORD are set and no users exist.

Running the Server:

mud-server run

# The server will start on:
# - API: http://localhost:8000
# - Web UI: http://localhost:7860

Superuser Setup

The server uses secure credential management with strong password requirements.

Password Requirements (STANDARD policy):

• Minimum 12 characters

• Cannot be a commonly used password

• No sequential characters (abc, 123)

• No excessive repeated characters (aaa)

Option 1: Interactive (recommended for local development):

mud-server create-superuser
# Follow prompts for username and password
# Password requirements will be displayed

Option 2: Environment variables (for CI/deployment):

export MUD_ADMIN_USER=myadmin
export MUD_ADMIN_PASSWORD="MySecure#Pass2024"  # Must meet policy requirements
mud-server create-superuser

Use Cases

PipeWorks MUD Server is suitable for:

• Fantasy MUDs - Traditional dungeon exploration

• Sci-Fi Adventures - Space stations and starships

• Educational Games - Learning through interaction

• Any text-based multiplayer world you can imagine

Design Philosophy

Programmatic Authority

• All game logic and state is deterministic and code-driven

• Game mechanics are reproducible and testable

• No LLM involvement in authoritative systems (state, logic, resolution)

Extensibility First

• World data is JSON-driven (swap worlds without code changes)

• Commands are extensible (add new actions without server rewrites)

• Modular architecture supports plugins and custom mechanics

Available Commands

Movement:

• north / n, south / s, east / e, west / w

• up / u, down / d

Observation:

• look / l - Observe current surroundings

• inventory / inv / i - Check inventory

Items:

• pickup <item> / get <item> - Pick up an item

• drop <item> - Drop an item

Communication:

• say <message> - Speak to others in same room

• yell <message> - Shout to nearby areas

• whisper <username> <message> - Private message

Utility:

• who - See all players online

• help - Show help information

Indices and Tables

• Index

• Module Index

• Search Page