# MUD AI Player - Implementation Roadmap

This document outlines the tasks required to build a complete, autonomous AI player for LPMUDs.

## 🟢 Phase 1: Core Connectivity & Basic Setup (Current Status)

- [x] **Telnet Client**: Basic connection and disconnection handling.
- [x] **Configuration**: YAML-based config for credentials and server info.
- [x] **Automatic Login**: 
  - [x] Username/Password automtation.
  - [x] "Take over existing session" handling.
- [x] **KeepAlive Manager**: Prevent idle disconnects.
- [ ] **Logging**: 
  - [x] Setup basic logging.
  - [ ] Implement strict `game.log` rotation and archiving structure.

## 🟡 Phase 2: Perception (Parsing & Sensing)

The bot needs to "see" the world effectively.

- [ ] **ANSI Parsing**:
  - [ ] Refine `ANSIParser` to fully strip color codes for logic but preserve them for UI if needed.
  - [ ] Detect prompt lines vs. content lines.
- [ ] **Status Parsing (Vitals)**:
  - [ ] Implement regex to capture HP/MP/SP from prompt (e.g., `hp: 350/350`).
  - [ ] Update `GameState.character` with real-time stats.
- [ ] **Room Parsing (Vision)**:
  - [ ] Identify Room Title (usually colored/bold).
  - [ ] Identify Room Description (multiline text).
  - [ ] Identify Exits (e.g., `[ Exits: n s w ]`).
  - [ ] Identify NPCs/Mobs/Items in the room.
- [ ] **Inventory & Equipment**:
  - [ ] Implement `inv` command parser.
  - [ ] Implement `eq` command parser.

## 🟠 Phase 3: World Modeling (Mapping)

The bot needs to know where it is and where it has been.

- [ ] **Room Hashing**:
  - [ ] Create unique hash for rooms based on Title + Description + Exits (to handle non-unique IDs).
- [ ] **Graph Database**:
  - [ ] Integrate `NetworkX` or SQLite for storing the world map.
  - [ ] Store nodes (Rooms) and edges (Exits).
- [ ] **Pathfinding**:
  - [ ] Implement A* algorithm to find shortest path between known rooms.
  - [ ] Implement "Breadth-First Search" (BFS) for exploration mode.

## 🔴 Phase 4: Decision Engine (The Brain)

The bot needs to decide what to do next.

- [ ] **Action Queue System**:
  - [ ] Priority queue for actions (e.g., `HEAL` > `ATTACK` > `LOOT` > `MOVE`).
- [ ] **Behavior Trees / State Machine**:
  - [ ] **IdleState**: Heal, Buff, Check Inventory.
  - [ ] **ExploreState**: Pick unknown exit, Move.
  - [ ] **CombatState**:
    - [ ] Auto-target hostile mobs.
    - [ ] Execute combat rotation (skills/spells).
    - [ ] Flee trigger (if HP < Threshold).
  - [ ] **LootState**: reliable looting of corpses.
- [ ] **LLM Integration (Optional/Hybrid)**:
  - [ ] Use LLM for "roleplay" responses to other players.
  - [ ] Use LLM for "quest parsing" (understanding vague instructions).

## 🔵 Phase 5: Humanization

Make the bot undetectable and less robotic.

- [ ] **Reaction Time Jitter**:
  - [ ] Randomize delays between commands (e.g., 200ms - 1500ms).
- [ ] **Typo Generator**:
  - [ ] Occasionally misspell commands and correct them (optional).
- [ ] **Schedule System**:
  - [ ] Define "active hours" and "sleep hours".

## 🟣 Phase 6: Testing & Metrics

- [ ] **Unit Tests**: Coverage for parsers (critical).
- [ ] **Integration Tests**: Mock MUD server for offline testing.
- [ ] **Performance Profiling**: Ensure graph traversal doesn't lag the bot.