MUD AI Player

An autonomous AI player for MUD (Multi-User Dungeon) text-based games.

Features

• 🤖 Autonomous Gameplay: Simulates a human player from character creation to endgame
• 🗺️ Auto-Mapping: Builds a complete map of the MUD world with hybrid storage (SQLite + Memvid)
• ⚔️ Combat AI: Intelligent combat decisions, target selection, and survival tactics
• 📜 Quest System: Automatically detects, plans, and completes quests
• 🔍 Semantic Search: Find locations using natural language queries
• 📊 Progression Optimizer: Finds optimal grinding spots and equipment upgrades

Architecture

The application is built with a modular architecture:

• Core: Telnet client, ANSI parser, text parser, game state
• Modules:
  • Character Creator: Stats rolling, class/race selection
  • Auto-Mapper: World mapping with hybrid storage (SQLite + Memvid)
  • Decision Engine: AI decision-making, combat AI, goal management
  • Quest System: Quest detection, planning, execution
  • Progression Optimizer: Grinding optimization, equipment analysis

Installation

Using Poetry (Recommended)

# Install Poetry if not already installed
pip install poetry

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

Using pip

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

# Install dependencies
pip install -r requirements.txt

Configuration

1. Copy the example configuration:

   cp examples/config.example.yaml config.yaml
   

2. Edit config.yaml with your MUD server details:

   mud:
     host: "your-mud-server.com"
     port: 4000
     username: "your_username"
     password: "your_password"
   

Usage

# Run the AI player
python -m src.main

# Run with custom config
python -m src.main --config custom_config.yaml

# Run tests
pytest tests/ -v

# Run with coverage
pytest --cov=src --cov-report=html

Project Structure

mud-ai-player/
├── src/                    # Source code
│   ├── core/              # Core components
│   ├── modules/           # Specialized modules
│   ├── utils/             # Utilities
│   └── config/            # Configuration management
├── data/                  # Persistent storage
│   ├── maps/             # World maps (SQLite + Memvid)
│   ├── characters/       # Character saves
│   └── logs/             # Game logs
├── tests/                # Test suite
├── docs/                 # Documentation
└── examples/             # Example configurations

Development

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Run tests with watch
pytest-watch

Documentation

See the docs/ directory for detailed documentation:

• Architecture
• Configuration Guide
• Development Guide
• API Reference

License

MIT License

Contributing

Contributions are welcome! Please read the development guide before submitting PRs.

Disclaimer

This is an educational project. Please respect the rules and terms of service of any MUD you connect to. Some MUDs prohibit automated players.