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
Gradio Client Only
Admin TUI (Terminal Interface)
Guest Registration
Example:
POST
/register
(client-supplied username)
Example:
POST
/register-guest
(server-generated username)
Environment Variables
CLI Reference
Next Steps
Architecture
Overview
Three-Tier Design
Modular Client Architecture
System Components
Backend (FastAPI)
Game Engine
Event Bus Architecture
Database Layer
Data Flow
Technology Stack
Key Design Patterns
Session Management
Role-Based Access Control
Command Pattern
Repository Pattern
Database Schema
Users Table
Characters Table
Character Locations Table
Sessions Table
Chat Messages Table
Security Considerations
Authentication
Password Policy
Known Limitations
Performance
Current Capacity
Scaling Considerations
Database
Current Database Schema
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
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
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
Game Actions
Admin
Health
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
Changelog
Changelog
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
Submodules
mud_server.admin_gradio
mud_server.admin_tui
mud_server.api
mud_server.cli
mud_server.config
mud_server.core
mud_server.db
PipeWorks MUD Server
API Reference
mud_server
mud_server.db
View page source
mud_server.db
Submodules
mud_server.db.database