QuickMUD is a modern Python port of the legendary ROM 2.4b6 MUD engine, derived from ROM 2.4b6, Merc 2.1 and DikuMUD. This is a complete rewrite that brings the classic text-based MMORPG experience to modern Python with async networking and JSON world data. The engine currently has a green suite and broad ROM audit coverage, but parity trust rebuild / revalidation is in progress after live bugs exposed gaps in observable-behavior verification.
A "Multi-User Dungeon" (MUD) is a text-based MMORPG that runs over telnet. ROM is renowned for its fast-paced combat system and rich player interaction. ROM was also the foundation for Carrion Fields, one of the most acclaimed MUDs ever created.
- 🎯 ROM parity trust rebuild in progress: audit coverage is broad, but user-visible command/session surfaces are being revalidated against stricter ROM-exact tests
- 🚀 Modern Python Architecture: Fully async/await networking with SQLAlchemy ORM
- 📡 Multiple Connection Options: Telnet, WebSocket, and SSH server support
- 🗺️ JSON World Loading: Easy-to-edit world data with 352+ room resets
- 🏪 Complete Shop System: Buy, sell, and list items with working economy
- ⚔️ ROM Combat System: Classic ROM combat mechanics and skill system
- 👥 Social Features: Say, tell, shout, and 100+ social interactions
- 🛠️ Admin Commands: Teleport, spawn, ban management, and OLC building
- 📊 Comprehensive Testing: 5,329 passing tests across unit, integration, and command-registry suites
- 🔧 ROM C-Compatible API: Public API wrappers for external tools and scripts (27 functions)
pip install quickmudRun a QuickMUD server:
Telnet Server (port 5001):
python3 -m mud socketserver
# or
mud socketserver
⚠️ macOS Users: Port 5000 is used by macOS AirPlay Receiver (Monterey+). QuickMUD defaults to port 5001 to avoid conflicts. To use a different port:python3 -m mud socketserver --port 4000
WebSocket Server (port 8000):
python3 -m mud websocketserver
# or
mud websocketserverWebSocket dependency note: browser WebSocket clients require Uvicorn to have a supported WebSocket implementation available. If
/wsupgrade requests fail, install one of:./venv/bin/python -m pip install websockets # or ./venv/bin/python -m pip install 'uvicorn[standard]'
SSH Server (port 2222):
python3 -m mud sshserver
# or
mud sshserverAll servers provide:
- ✓ Game tick running at 4 Hz
- ✓ Time advancement
- ✓ Mob AI active
Connect to the server:
Via Telnet:
telnet localhost 5001Via SSH:
ssh -p 2222 player@localhost
# Note: SSH username/password are ignored; MUD authentication happens after connectionQuickMUD includes a WebSocket server, but the browser interface lives in a separate companion project so this engine repo can remain the canonical, ROM-faithful Python backend.
Recommended layout:
~/dev/projects/
rom24-quickmud-python/
quickmud-web-client/
The browser client should connect to:
ws://127.0.0.1:8000/ws
From the companion quickmud-web-client repo:
cd ~/dev/projects/quickmud-web-client
npm install
npm run dev:allThat workflow:
- starts this QuickMUD engine's WebSocket server
- starts the frontend development server
- opens the browser client against the local
/wsendpoint
The browser client is intended to follow the same ANSI, account login, account creation, character selection, and in-game command flow as telnet/SSH rather than using a browser-only shortcut login path.
The web interface is intended to live in a separate repository named
quickmud-web-client. Keep that project focused on browser UX, terminal
rendering, reconnect behavior, and login flow while leaving gameplay and ROM
parity logic in this backend repo.
git clone https://github.com/Nostoi/rom24-quickmud-python.git
cd rom24-quickmud-python
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e .[dev]pytest # Run the full suite
pytest tests/integration/ -v # Run the integration suitepython -m mud # Start development serverHonest one-line summary: broad implementation and audit coverage of ROM 2.4b6 is complete and the test suite is green, but the project is in a verification trust-rebuild phase — "audited" means a per-file audit document exists, not that behavior is proven bug-free, and a small number of parity gaps remain open.
- Version: 2.12.80
- ROM 2.4b Gameplay Parity:
⚠️ broadly implemented, verification hardening in progress — combat, skills, spells, movement, communication, world/db, save/load, mob programs, and all 255 ROM commands are implemented and pass their tests. However, some surfaces that were previously marked "verified" were only smoke-tested, and are being rechecked with ROM-exact assertions. Treat the audit coverage below as process completeness, not a guarantee of bit-for-bit correctness. - ROM C Source Audit: ✅ 100% audit-bound coverage — 40 of 40 applicable ROM C
files have a completed audit document, with 3 additional ROM files intentionally N/A
(
recycle.c,mem.c,imc.c). This tracks that every applicable file has been reviewed and documented; it does not by itself certify behavioral parity (three production bugs this year shipped against files marked ≥95% audited — see the cross-file invariants tracker for why per-file audits are necessary but not sufficient). Seedocs/parity/ROM_C_SUBSYSTEM_AUDIT_TRACKER.md. - Cross-file Invariants: ✅ 25/25 enforced — message delivery, prompt clamping,
registry membership, same-room combat, death/connection behavior, RNG determinism,
persistence coherence, and room-flag survival (
.are→JSON→runtime) are locked by dedicated regression tests. This layer exists specifically to catch the contract violations that per-file audits miss. - Open parity gaps: a small backlog of identified divergences is tracked and being
closed one failing-test-first commit at a time (current example:
HANDLER-004,is_nameuses a substring match rather than ROM's whole-wordstr_prefix). Open gaps are logged in the per-filedocs/parity/*_C_AUDIT.mddocuments. - Test Suite: ✅ 5361 passed, 4 skipped (full
pytestrun, ~155s parallel). Three layers — unit (tests/test_*.py), integration (tests/integration/), and command-registry (test_all_commands.py). - Active focus: trust rebuild — replacing weak smoke assertions with ROM-exact output, boundary, and runtime-path tests on the highest-risk user-visible surfaces, and closing the remaining documented parity gaps.
- Compatibility: Python 3.10+, cross-platform
- Async Networking: Modern async/await with Telnet, WebSocket, and SSH servers
- SQLAlchemy ORM: Robust database layer with migrations
- JSON World Data: Human-readable area files with full ROM compatibility
- Modular Design: Clean separation of concerns (commands, world, networking)
- Type Safety: Comprehensive type hints throughout codebase
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please read our Contributing Guidelines and feel free to submit pull requests.
- ROM C subsystem tracker - canonical audit surface
- ROM parity verification guide - current verification standard
- ROM 2.4b6 Parity Certification - historical certification document; claims are being revalidated
- User Guide - Player and server operator documentation
- Admin Guide - Administrator and immortal documentation
- Builder Migration Guide - For ROM builders transitioning to QuickMUD
- ROM Parity Feature Tracker - Detailed parity status
- ROM API Reference - ROM C-compatible public API
- Installation Guide
- Configuration
- World Building
- API Reference
- Companion browser client:
quickmud-web-client(separate repo)
Experience the classic MUD gameplay with modern Python reliability! 🐍✨
For a fully reproducible environment, use the pinned requirements files generated with pip-tools:
pip install -r requirements-dev.txtTo update the pinned dependencies:
pip-compile requirements.in
pip-compile requirements-dev.inTools like Poetry provide a similar workflow if you prefer that approach.
Run tests with:
pytestTo release a new version to PyPI:
- Update the version in
pyproject.toml. - Commit and tag:
git commit -am "release: v1.2.3"
git tag v1.2.3
git push origin main --tagsThe GitHub Actions workflow will build and publish the package when the tag is pushed.
Game systems are implemented in Python modules:
mud/netprovides asynchronous telnet and websocket servers.mud/game_loop.pydrives the tick-based update loop.mud/commandscontains the command dispatcher and handlers.mud/combatandmud/skillsimplement combat and abilities.mud/account/andmud/db/handle character persistence and account state.
Start the server with:
python -m mud runserverBuild and run the Python server with Docker:
docker build -t quickmud .
docker run -p 5001:5001 quickmudOr use docker-compose to rebuild on changes and mount the repository:
docker-compose upConnect via:
telnet localhost 5001The mud/models package defines dataclasses used by the game engine.
They mirror the JSON schemas in schemas/ and supply enums and registries
for loading and manipulating area, room, object, and character data.
QuickMUD implements the full ROM 2.4b6 gameplay surface and has broad, documented audit coverage of the original C codebase. It is feature-complete and running on a green test suite, and is in an active verification trust-rebuild phase rather than claiming finished, certified parity. "Implemented" below means the system exists and passes its current tests; it does not assert bit-for-bit behavioral parity, which is being hardened gap-by-gap (see Project Status above).
- Combat Engine: Complete ROM combat mechanics with THAC0, damage calculations, and weapon special attacks
- Skills & Spells: All ROM skills and spells with correct formulas and targeting
- Character System: Classes, races, advancement, equipment, and encumbrance
- World System: Area loading, room resets, mob/object spawning, and JSON world data
- Shop Economy: Buy/sell with pricing formulas, shop restocking, and inventory management
- Communication: Say, tell, shout, channels, and 100+ social interactions
- Mob Programs: Complete trigger system with conditional logic and ROM API
- OLC Building: Area/room/mob/object/help editors with save/load functionality
- Admin Tools: Teleport, spawn, ban management, wiznet, and debug commands
- Networking: Async telnet, WebSocket, and SSH servers with game tick integration
- Test Suite: 5,329 passing, 4 skipped on the latest full run.
- Audit Coverage: every ROM 2.4b6 gameplay subsystem has a completed audit document (combat, skills, spells, movement, communication, world/db, save/load, mob programs, 255/255 commands). Audit completion means reviewed and documented, not certified bug-free — verification rigor is still being hardened.
- ROM C Source Audit: 40 of 40 applicable ROM files have an audit document, plus 3 intentional N/A files.
- Cross-file Invariants: 25 of 25 enforced by dedicated regression tests.
- Open gaps: a small, tracked backlog of identified divergences is being closed one test-first commit at a time.
For developers interested in extending QuickMUD beyond ROM 2.4b:
- Modern Architecture: Async/await networking, SQLAlchemy ORM, type hints
- JSON World Data: Human-readable area files (easier editing than ROM .are format)
- Multiple Protocols: Telnet, WebSocket, SSH connection options
- ROM API Wrapper: 27 public API functions for external tools and scripts
- Comprehensive Testing: Golden file tests derived from ROM C behavior
- Documentation: User guides, admin guides, and builder migration guides
See ROM_PARITY_FEATURE_TRACKER.md for detailed feature status and AGENTS.md for AI-assisted development workflows.
Development Guidelines:
- ROM Parity First: Reference original ROM 2.4 C sources in
src/for canonical behavior - Test Coverage: Add tests in
tests/with golden files derived from ROM behavior - Backward Compatibility: Don't break existing save files or area data
- Documentation: Update relevant docs and inline code documentation
- Performance: Consider impact on the main game loop and player experience
Experience authentic ROM 2.4 gameplay with modern Python reliability! 🐍✨