truetype
f85c27a742
Phase 0 (housekeeping): - Add .gitignore to protect credentials and runtime files - Track all project source code, docs, and config Phase 1 (perception loop): - Implement pluggable parser architecture (BaseMudParser ABC + ParserFactory) - Add DeadSoulsParser with regex for HP/MP/SP prompt, room descriptions, exits (multiple formats), NPC/item detection, and combat events - Add OutputBuffer for accumulating text between prompts - Update GameState with SP support and update_from_prompt/room/combat methods - Rewire main loop to use parser + buffer for real-time game state updates - Add reconnection logic to TelnetClient (retry with backoff) - Remove old TextParser (replaced by pluggable system) - Add mud_type config field for selecting parser at runtime - Add comprehensive test suite (50 tests, all passing)
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
-
Copy the example configuration:
cp examples/config.example.yaml config.yaml -
Edit
config.yamlwith 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:
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.