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)
135 lines
3.4 KiB
Markdown
135 lines
3.4 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
# Install Poetry if not already installed
|
|
pip install poetry
|
|
|
|
# Install dependencies
|
|
poetry install
|
|
|
|
# Activate virtual environment
|
|
poetry shell
|
|
```
|
|
|
|
### Using pip
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
cp examples/config.example.yaml config.yaml
|
|
```
|
|
|
|
2. Edit `config.yaml` with your MUD server details:
|
|
```yaml
|
|
mud:
|
|
host: "your-mud-server.com"
|
|
port: 4000
|
|
username: "your_username"
|
|
password: "your_password"
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](docs/architecture.md)
|
|
- [Configuration Guide](docs/configuration.md)
|
|
- [Development Guide](docs/development.md)
|
|
- [API Reference](docs/api_reference.md)
|
|
|
|
## 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.
|