Metadata-Version: 2.4
Name: rom24-quickmud-python
Version: 2.7.0
Summary: A modern Python port of the ROM 2.4b6 MUD engine with full telnet server and JSON world loading
Author-email: Mark Jedrzejczyk <mark.jedrzejczyk@gmail.com>
Maintainer-email: Mark Jedrzejczyk <mark.jedrzejczyk@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Nostoi/rom24-quickmud-python
Project-URL: Repository, https://github.com/Nostoi/rom24-quickmud-python.git
Project-URL: Documentation, https://github.com/Nostoi/rom24-quickmud-python/blob/master/README.md
Project-URL: Bug Tracker, https://github.com/Nostoi/rom24-quickmud-python/issues
Project-URL: Changelog, https://github.com/Nostoi/rom24-quickmud-python/releases
Keywords: mud,rom,game,mmo,telnet,server
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment :: Multi-User Dungeons (MUD)
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: SQLAlchemy<3,>=2.0
Requires-Dist: typer>=0.9
Requires-Dist: python-dotenv>=1.0
Requires-Dist: fastapi>=0.68.0
Requires-Dist: uvicorn>=0.15.0
Requires-Dist: pytest-timeout>=2.1.0
Requires-Dist: asyncssh>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: jsonschema>=4.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov>=6.0; extra == "test"
Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
Dynamic: license-file

# QuickMUD - A Modern ROM 2.4 Python Port

[![Version](https://img.shields.io/badge/version-2.6.3-blue.svg)](https://github.com/Nostoi/rom24-quickmud-python)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-3508%2F3521%20passing-brightgreen.svg)](https://github.com/Nostoi/rom24-quickmud-python)
[![ROM 2.4b Parity](https://img.shields.io/badge/ROM%202.4b%20Parity-gameplay%20100%25-success.svg)](ROM_2.4B6_PARITY_CERTIFICATION.md)
[![Function Coverage](https://img.shields.io/badge/ROM%20C%20Functions-96.1%25-blue.svg)](FUNCTION_MAPPING.md)
[![Integration Tests](https://img.shields.io/badge/integration%20tests-1000%2B-brightgreen.svg)](tests/integration/)

**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, JSON world data, and **100% ROM 2.4b behavioral parity**.

## 🎮 What is a MUD?

A "[Multi-User Dungeon](https://en.wikipedia.org/wiki/MUD)" (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](http://www.carrionfields.net/), one of the most acclaimed MUDs ever created.

## ✨ Key Features

- **🎯 100% ROM 2.4b Behavioral Parity CERTIFIED**: Official certification with comprehensive audits ([see certification](ROM_2.4B6_PARITY_CERTIFICATION.md))
- **🚀 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**: 3,508 / 3,521 tests passing (99.6%) across unit, integration (1,000+), and command-registry suites
- **🔧 ROM C-Compatible API**: Public API wrappers for external tools and scripts (27 functions)

## 📦 Installation

### For Players & Server Operators

```bash
pip install quickmud
```

### Quick Start

Run a QuickMUD server:

**Telnet Server (port 5001):**
```bash
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):**
```bash
python3 -m mud websocketserver
# or
mud websocketserver
```

> **WebSocket dependency note:** browser WebSocket clients require Uvicorn to
> have a supported WebSocket implementation available. If `/ws` upgrade requests
> fail, install one of:
> ```bash
> ./venv/bin/python -m pip install websockets
> # or
> ./venv/bin/python -m pip install 'uvicorn[standard]'
> ```

**SSH Server (port 2222):**
```bash
python3 -m mud sshserver
# or
mud sshserver
```

All servers provide:
- ✓ Game tick running at 4 Hz
- ✓ Time advancement
- ✓ Mob AI active

Connect to the server:

**Via Telnet:**
```bash
telnet localhost 5001
```

**Via SSH:**
```bash
ssh -p 2222 player@localhost
# Note: SSH username/password are ignored; MUD authentication happens after connection
```

## 🌐 Web Interface

QuickMUD 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:

```text
~/dev/projects/
  rom24-quickmud-python/
  quickmud-web-client/
```

The browser client should connect to:

```text
ws://127.0.0.1:8000/ws
```

### Browser Client Setup

From the companion `quickmud-web-client` repo:

```bash
cd ~/dev/projects/quickmud-web-client
npm install
npm run dev:all
```

That workflow:

- starts this QuickMUD engine's WebSocket server
- starts the frontend development server
- opens the browser client against the local `/ws` endpoint

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.

### Companion Repo

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.

## 🏗️ For Developers

## 🏗️ For Developers

### Development Installation

```bash
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]
```

### Running Tests

```bash
pytest  # Run all 3,500+ tests
pytest tests/integration/ -v  # Run integration suite (1,000+ tests)
```

### Development Server

```bash
python -m mud  # Start development server
```

## 🎯 Project Status

- **Version**: 2.6.73 (Production Ready — gameplay parity shipped, OLC cluster in progress)
- **ROM 2.4b Gameplay Parity**: ✅ **100%** ([official certification](ROM_2.4B6_PARITY_CERTIFICATION.md)) —
  combat, skills, spells, movement, communication, world/db, save/load, mob programs,
  and all 255 ROM commands are implemented and audited.
- **ROM C Source Audit**: 34 of 43 ROM C source files audited (24 at strict 100%);
  remaining work is the OLC editor cluster (`olc.c`, `olc_act.c`, `olc_save.c`,
  `olc_mpcode.c`, `hedit.c`) plus a small partial-audit tail (`board.c` 95%).
  Several audited files sit at 85–98% with deferred-by-design or sibling-gated
  gaps (`act_move.c`, `comm.c`, `nanny.c`, `const.c`, `music.c`, `board.c`).
  Gameplay is not blocked on any of them. See
  [`docs/parity/ROM_C_SUBSYSTEM_AUDIT_TRACKER.md`](docs/parity/ROM_C_SUBSYSTEM_AUDIT_TRACKER.md).
- **ROM C Function Coverage**: 96.1% (716/745 functions mapped)
- **Test Suite**: 3,508 / 3,521 passing (99.6%), 11 skipped, 2 known
  pre-existing failures, full run ~8 min. Three layers — unit (`tests/test_*.py`),
  integration (`tests/integration/`, 1,000+ tests), and command-registry
  (`test_all_commands.py`). Pre-existing skips/failures are catalogued in
  [`docs/parity/PRE_EXISTING_FAILURES_TRIAGE.md`](docs/parity/PRE_EXISTING_FAILURES_TRIAGE.md).
- **Active focus**: `olc.c` cluster — OLC-020/022/023 + STRING-001..012 closed;
  remaining CRITICAL gaps (OLC-016/017/018/019, the `*edit create` subcommands)
  gated on the held `olc_act.c` sibling audit.
- **Compatibility**: Python 3.10+, cross-platform

## 🏛️ Architecture

- **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

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) and feel free to submit pull requests.

## 📚 Documentation

### Official Certification
- [ROM 2.4b6 Parity Certification](ROM_2.4B6_PARITY_CERTIFICATION.md) - **Official 100% parity certification**

### User Documentation
- [User Guide](docs/USER_GUIDE.md) - Player and server operator documentation
- [Admin Guide](docs/ADMIN_GUIDE.md) - Administrator and immortal documentation  
- [Builder Migration Guide](docs/BUILDER_MIGRATION_GUIDE.md) - For ROM builders transitioning to QuickMUD

### Developer Documentation
- [ROM Parity Feature Tracker](docs/parity/ROM_PARITY_FEATURE_TRACKER.md) - Detailed parity status
- [ROM API Reference](ROM_API_COMPLETION_REPORT.md) - ROM C-compatible public API
- [Installation Guide](docs/installation.md)
- [Configuration](docs/configuration.md)
- [World Building](docs/world-building.md)
- [API Reference](docs/api.md)
- 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](https://github.com/jazzband/pip-tools):

```bash
pip install -r requirements-dev.txt
```

To update the pinned dependencies:

```bash
pip-compile requirements.in
pip-compile requirements-dev.in
```

Tools like [Poetry](https://python-poetry.org/) provide a similar workflow if you prefer that approach.

Run tests with:

```bash
pytest
```

### Publishing

To release a new version to PyPI:

1. Update the version in `pyproject.toml`.
2. Commit and tag:

```bash
git commit -am "release: v1.2.3"
git tag v1.2.3
git push origin main --tags
```

The GitHub Actions workflow will build and publish the package when the tag is pushed.

## Python Architecture

Game systems are implemented in Python modules:

- `mud/net` provides asynchronous telnet and websocket servers.
- `mud/game_loop.py` drives the tick-based update loop.
- `mud/commands` contains the command dispatcher and handlers.
- `mud/combat` and `mud/skills` implement combat and abilities.
- `mud/persistence.py` handles saving characters and world state.

Start the server with:

```sh
python -m mud runserver
```

## Docker Image

Build and run the Python server with Docker:

```bash
docker build -t quickmud .
docker run -p 5001:5001 quickmud
```

Or use docker-compose to rebuild on changes and mount the repository:

```bash
docker-compose up
```

Connect via:

```bash
telnet localhost 5001
```

## Data Models

The `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.

## Project Completeness

QuickMUD is a **production-ready ROM 2.4b MUD** with ✅ **100% behavioral parity** to the original ROM 2.4b6 C codebase:

### ✅ Fully Implemented Systems

- **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

### 📈 Quality Metrics

- **Test Suite**: 3,508 / 3,521 passing (99.6%), 11 skipped, 2 known
  pre-existing failures (full run ~8 min); pre-existing skips/failures are
  catalogued in
  [`docs/parity/PRE_EXISTING_FAILURES_TRIAGE.md`](docs/parity/PRE_EXISTING_FAILURES_TRIAGE.md).
- **Behavioral Parity**: 100% of ROM 2.4b6 gameplay subsystems audited (combat,
  skills, spells, movement, communication, world/db, save/load, mob programs,
  255/255 commands).
- **Function Coverage**: 716/745 ROM C functions mapped (96.1%)
- **ROM C Source Audit**: 34 of 43 files audited (24 at strict 100%); remainder
  is the OLC editor cluster (`olc.c`/`olc_act.c`/`olc_save.c`/`olc_mpcode.c`/`hedit.c`)
  and a small partial tail (`board.c` 95%).

### 🔧 Advanced Features

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

### 📚 For Contributors

See [ROM_PARITY_FEATURE_TRACKER.md](docs/parity/ROM_PARITY_FEATURE_TRACKER.md) for detailed feature status and [AGENTS.md](AGENTS.md) for AI-assisted development workflows.

**Development Guidelines**:

1. **ROM Parity First**: Reference original ROM 2.4 C sources in `src/` for canonical behavior
2. **Test Coverage**: Add tests in `tests/` with golden files derived from ROM behavior  
3. **Backward Compatibility**: Don't break existing save files or area data
4. **Documentation**: Update relevant docs and inline code documentation
5. **Performance**: Consider impact on the main game loop and player experience

---

**Experience authentic ROM 2.4 gameplay with modern Python reliability!** 🐍✨
