MudProto

A modern, server-authoritative real-time MUD framework in Python, built solo with a polished web client, persistent world systems, multiplayer async concurrency, and a schema-driven LLM content generation pipeline.

Built end-to-end as a solo engineering project to showcase real-time networking, persistent world state, polished browser UX, and fast world-building workflows.

The live demo highlights one of the strongest parts of the project: a polished web client that players can open instantly in the browser, with aliases, key bindings, reactive actions, saved configs, and streamlined settings.

Play MudProto live in your browser

Live demo. No install required.

View full screenshot gallery

Why it stands out

• Solo-built end-to-end: backend networking, game systems, persistence, browser UX, CI, and deployment all work together in one playable stack.
• A browser-first client with aliases, key bindings, and reactive actions, plus saved configs, toast feedback, modal settings, and direct in-browser play.
• Server-authoritative architecture and concurrent multiplayer state handling built for real shared gameplay, not just a static demo.
• Fast content iteration through structured assets and a schema-driven LLM content pipeline that can generate drop-in zones, NPCs, items, spells, and skills.

Browser Client Highlights

• Fast command entry with aliases, key bindings, and reactive actions for responsive play.
• Polished quality-of-life UX including saved configs, help views, floating feedback, and streamlined settings flows.
• Instant browser access for quick demos with no install required.

What this demonstrates

• Real-time and concurrent multiplayer engineering across networking, session flow, combat timing, shared room state, and persistence.
• Product-minded frontend work with a usable, polished browser interface rather than a bare debug client.
• CI-backed development with automated regression testing across server logic, persistence boundaries, and web-client parity.
• Data-driven design using JSON-backed game content and configurable mechanics.
• Practical AI tooling through a schema-driven pipeline for generating structured world assets.
• End-to-end ownership: architecture, gameplay systems, client UX, testing, and iteration.

Quick Start

# Clone
git clone https://github.com/WilliamSmithEdward/mudproto.git
cd mudproto

# Create and activate virtual environment
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate     # macOS/Linux

# Install runtime dependencies
pip install -r requirements.txt

# Start server
python mudproto_server/core_logic/server.py

# Open the web client
start mudproto_client_web/index.html      # Windows
# open mudproto_client_web/index.html     # macOS
# xdg-open mudproto_client_web/index.html # Linux

Note: MudProto is now web-first. The old terminal path is gone, and the desktop Python GUI has been retired.

First commands to try:

• start
• look
• score
• inventory
• scan

Web Client As the Primary Experience

MudProto treats the web client as the main player interface so the best UX is available instantly in the browser instead of being split across multiple front ends.

That means:

• new client UX work should go into mudproto_client_web
• client-side settings and quality-of-life features should be added in the web client
• the retired Python GUI should not be brought back as a second actively maintained front end

Current Gameplay Highlights

Combat and Abilities

• Multi-target room combat with shared round output.
• Skills and spells with round cooldowns and optional game-hour cooldowns.
• Class kits with JSON-configured spell, skill, and passive unlock levels.
• Timed and battle-round support effects.
• NPC ability usage with independent skill/spell cooldown tracking.
• Bash-style target lag now also forces target posture to sitting.

Posture System

• Postures: standing, sitting, resting.
• Commands:
  • sit aliases: si, sit
  • rest aliases: r, re, res, rest
  • stand aliases: st, sta, stan, stand
• Sitting and resting can block movement using posture config flags.
• Posture damage multipliers are data-driven from posture config.
• Resting can apply regeneration bonus multipliers.
• Room look output shows posture for living NPCs and players.
• Score output shows current posture state.

Social and Grouping

• Follow, watch, group flows.
• Swap command supports self/member and member/member reorder patterns.
• Follow/group behavior reconciles correctly on death and movement.

Persistence, Items, and World

• SQLite-backed player persistence.
• Shared room state for NPCs, corpses, coin piles, and ground items.
• Corpses now follow the same shared container rules as other lootable containers.
• Potions are modeled directly with item_type values and support both use and quaff-style aliases.
• JSON-driven content for rooms, zones, NPCs, items, spells, skills, and attributes.
• Server runtime and presentation config is split under mudproto_server/configuration/server/settings.json, mudproto_server/configuration/server/directions.json, mudproto_server/configuration/server/health_conditions.json, mudproto_server/configuration/server/display_feedback.json, and mudproto_server/configuration/server/display_colors.json.

Architecture

Clients send raw text commands. The server owns all game logic and returns structured display envelopes.

See ARCHITECTURE.md for a deeper technical breakdown.

AI Content Pipeline

MudProto includes a schema-driven LLM content pipeline for mechanically complete asset bundle generation.

Main entrypoint:

• mudproto_llm_interfaces/generate_asset_payload_generation_instructions.py

Generated instruction payload:

• mudproto_llm_interfaces/asset_payload_generation_instructions.json

Typical workflow:

1. Regenerate instruction payload.
2. Provide payload plus a content brief to an AI model.
3. Save returned JSON payload under mudproto_server/configuration/assets/asset_payloads/.
4. Restart server to load new content.

Full process details: LLM_CONTENT_GENERATION.md.

Project Layout

mudproto/
├── ARCHITECTURE.md
├── ASSET_GENERATION.md
├── LLM_CONTENT_GENERATION.md
├── mudproto_client_web/
│   ├── index.html
│   └── documentation/
├── mudproto_llm_interfaces/
│   ├── generate_asset_payload_generation_instructions.py
│   └── asset_payload_generation_instructions.json
├── mudproto_server/
│   ├── configuration/
│   │   ├── server/
│   │   │   ├── settings.json
│   │   │   ├── directions.json
│   │   │   ├── health_conditions.json
│   │   │   ├── display_feedback.json
│   │   │   └── display_colors.json
│   │   ├── assets/
│   │   └── attributes/
│   └── core_logic/
│       ├── server.py
│       ├── command_handlers/
│       └── tests/
├── images/
└── README.md

Development Notes

• Python version target: 3.12+
• Runtime dependencies are tracked in requirements.txt
• Development/test dependencies are tracked in requirements-dev.txt
• Core test suite lives under mudproto_server/core_logic/tests

Development Setup

# From repo root (with venv active)
pip install -r requirements-dev.txt

Recommended local workflow:

1. Keep your virtual environment in venv/ (already gitignored).
2. Install runtime deps with requirements.txt for game-only usage.
3. Install requirements-dev.txt when running tests regularly.
4. Use python -m pytest from mudproto_server/core_logic for full regression runs.
5. GitHub Actions CI runs pytest automatically on pushes to main and on pull requests.

Run tests:

cd mudproto_server/core_logic
python -m pytest

MudProto is designed to be practical to run, straightforward to read, and easy to extend.

_{────────────}

Roll for initiative. 🎲