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)
4.5 KiB
4.5 KiB
MUD AI Player - Architecture
Overview
The MUD AI Player is designed with a modular architecture that separates concerns into specialized components. This document describes the high-level architecture and design decisions.
System Architecture
┌─────────────────────────────────────────────────────────┐
│ Main Application │
│ (main.py) │
└────────────────────┬────────────────────────────────────┘
│
┌────────────┴────────────┐
│ │
┌───────▼────────┐ ┌────────▼────────┐
│ Core Layer │ │ Modules Layer │
│ │ │ │
│ - Telnet │ │ - Character │
│ - Parsers │ │ - Mapper │
│ - Game State │ │ - Decision │
└────────┬───────┘ │ - Quest │
│ │ - Progression │
│ └────────┬────────┘
│ │
└───────────┬───────────┘
│
┌──────────▼──────────┐
│ Storage Layer │
│ │
│ - SQLite (Active) │
│ - Memvid (Archive) │
│ - FAISS (Search) │
└─────────────────────┘
Core Components
Telnet Client
- Asynchronous connection to MUD server
- Handles reconnection and error recovery
- Rate limiting for commands
Parsers
- ANSI Parser: Strips/interprets color codes
- Text Parser: Extracts structured data from MUD output
- Pattern matching for rooms, NPCs, items, status
Game State
- Central state management
- Character, room, inventory, quests
- Event system for state changes
Specialized Modules
Auto-Mapper (Hybrid Storage)
Layer 1: Active Storage
- SQLite database for real-time data
- NetworkX graph in memory
- <5ms insert latency
- Fast pathfinding
Layer 2: Historical Storage
- Memvid encoding (QR-in-MP4)
- 50-100x compression
- Periodic snapshots
- Long-term archival
Layer 3: Semantic Search
- FAISS vector search
- Sentence transformers
- Natural language queries
Decision Engine
- Goal-based AI
- State machine for behaviors
- Pluggable architecture (rule-based vs LLM)
Combat AI
- Target selection
- Skill rotation
- Flee logic
- Health management
Data Flow
MUD Server
↓
Telnet Client
↓
ANSI Parser → Text Parser
↓
Game State Update
↓
Decision Engine
↓
Action Selection
↓
Command Execution
↓
MUD Server
Design Patterns
Strategy Pattern
- AI engine (rule-based vs LLM)
- Exploration strategy (DFS vs BFS)
- Combat strategy (aggressive vs cautious)
Observer Pattern
- Game state changes trigger module updates
- Event-driven architecture
Repository Pattern
- Active storage for real-time data
- Historical storage for archival
- Abstraction over storage details
Performance Considerations
- Async/Await: All I/O operations are non-blocking
- In-Memory Graph: Fast pathfinding without DB queries
- Lazy Loading: Historical data loaded on demand
- Connection Pooling: Reuse database connections
Extensibility
The architecture is designed for easy extension:
- New Modules: Add to
src/modules/ - New Parsers: Extend
TextParserfor MUD-specific patterns - New AI Engines: Implement
DecisionEngineinterface - New Storage: Implement storage interface
Security & Safety
- Credentials in config.yaml (gitignored)
- Rate limiting to avoid server bans
- Human behavior simulation
- Graceful error handling
Future Enhancements
- Multi-character support
- Web dashboard for monitoring
- Plugin system for custom behaviors
- Distributed mapping (share maps between instances)