AIPLAYER/README.md

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 with configurable embedding models (MiniLM, MPNet, Gemma)
• 📊 Progression Optimizer: Finds optimal grinding spots and equipment upgrades
• 🧠 LLM Integration: Context-aware responses to players using local LLMs (Ollama)
• 🌐 Web Dashboard: Real-time monitoring dashboard with WebSocket updates
• 👤 Human Behavior: Simulates realistic reaction times and behavior patterns

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
  • LLM Integration: Ollama/OpenAI-compatible LLM client with memory
  • Web Dashboard: FastAPI-based monitoring with WebSocket support

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 (~7,500 lines)
│   ├── core/              # Core components
│   │   ├── telnet_client.py    # Async telnet connection
│   │   ├── game_state.py       # Game state management
│   │   ├── ansi_parser.py      # ANSI color code parsing
│   │   └── parsers/            # MUD-specific parsers
│   ├── modules/           # Specialized modules
│   │   ├── mapper/             # World mapping (SQLite + Memvid)
│   │   ├── decision/           # AI decision engine
│   │   ├── llm/                # LLM integration
│   │   ├── character/          # Character creation
│   │   ├── quest/              # Quest management
│   │   ├── progression/        # Grinding optimizer
│   │   └── web/                # Monitoring dashboard
│   ├── utils/             # Utilities
│   └── config/            # Configuration management
├── data/                  # Persistent storage
│   ├── maps/             # World maps (SQLite + Memvid)
│   ├── characters/       # Character saves
│   └── logs/             # Game logs
├── tests/                # Test suite (17 files, ~2,500 lines)
├── docs/                 # Documentation
│   ├── architecture.md   # System architecture
│   ├── configuration.md  # Configuration guide
│   ├── development.md    # Development guide
│   └── api_reference.md  # API reference

Web Dashboard

The AI player includes a real-time web dashboard for monitoring:

monitoring:
  enabled: true
  host: "127.0.0.1"
  port: 8080

🎮 Autonomous Mode

Modalità completamente autonoma dove il bot esplora, impara e cresce da solo guidato dall'LLM:

# Avvia esplorazione autonoma per 60 minuti
python -m src.autonomous_mode --duration 60

# Con config personalizzata
python -m src.autonomous_mode --config my_config.yaml --duration 120

Caratteristiche:

• 🤖 LLM-First: L'LLM prende tutte le decisioni strategiche
• 🗺️ Auto-Mapping: Esplora e mappa automaticamente il mondo
• 🧠 Learning: Memorizza stanze pericolose, NPC utili, pattern
• 📊 Session Logging: Salva tutto in data/autonomous_sessions/
• 🎯 Goal Dinamici: Obiettivi di esplorazione e crescita
• 🛡️ Safety First: Override automatico se HP critici

Esempio di output:

🚀 Avviata sessione autonoma: session_20240209_143022
🧠 Decisione LLM: [explore] north
   Ragionamento: Uscita non esplorata, pericolo basso
🔍 Scoperta: [room] Village Square: You are standing in...
📄 Log completo: data/autonomous_sessions/session_20240209_143022.json

Configurable Embedding Models

Choose the best embedding model for semantic room search:

mapper:
  semantic_search:
    # Available models:
    # - "sentence-transformers/all-MiniLM-L6-v2" (fast, 22MB) - default
    # - "sentence-transformers/all-mpnet-base-v2" (better quality, 418MB)
    # - "google/embeddinggemma-300m" (state-of-the-art, ~300MB)
    model: "google/embeddinggemma-300m"

Model	Size	Speed	Quality	Use Case
all-MiniLM-L6-v2	22MB	⭐⭐⭐⭐⭐	⭐⭐⭐	Low resource, fast queries
all-mpnet-base-v2	418MB	⭐⭐⭐	⭐⭐⭐⭐	Better accuracy, balanced
google/embeddinggemma-300m	~300MB	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	Best quality, requires transformers>=4.40

Access the dashboard at http://127.0.0.1:8080

Features:

• Real-time character vitals (HP/MP/SP)
• Current room information with NPCs and items
• Active goals and AI state
• Map statistics (rooms discovered, exits mapped)
• Event log with game events
• WebSocket updates (no page refresh needed)

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.