# Configuration Guide

This guide covers all configuration options for the MUD AI Player.

## Configuration File

The main configuration file is `config.yaml`. An example is provided in `examples/config.example.yaml`.

## Configuration Sections

### MUD Connection Settings

```yaml
mud:
  host: "192.168.0.63"          # MUD server hostname or IP
  port: 6666                     # MUD server port
  mud_type: "dead_souls"         # Parser type: dead_souls, aardwolf, etc.
  username: "your_username"      # Login username
  password: "your_password"      # Login password
  keep_alive_interval: 60        # Seconds between keep-alive commands
  keep_alive_command: ""         # Command to send for keep-alive (empty = no-op)
```

### Character Settings

```yaml
character:
  name: "AIPlayer"               # Character name
  preferred_class: "warrior"     # warrior, mage, cleric, rogue
  preferred_race: "human"        # human, elf, dwarf, etc.
  play_style: "balanced"         # aggressive, cautious, balanced
```

### AI Engine Settings

```yaml
ai:
  engine: "hybrid"               # rule_based, llm, hybrid
  llm_model: "llama3.2"          # LLM model name
  decision_delay_ms: [200, 2000] # Min/max reaction time in milliseconds
  exploration_strategy: "depth_first"  # depth_first, breadth_first
  
  llm:
    enabled: true                # Enable/disable LLM features
    base_url: "http://localhost:11434"  # Ollama/OpenAI-compatible endpoint
    model: "llama3.2"            # Model to use
    temperature: 0.3             # Creativity vs consistency (0.0-1.0)
    max_tokens: 512              # Max response length
    timeout_seconds: 30.0        # Request timeout
    max_retries: 2               # Retry attempts on failure
    system_prompt: "You are an AI playing a text-based MUD game..."
    memory_db_path: "data/llm_memory.db"  # Long-term memory storage
```

### Mapper Settings

```yaml
mapper:
  active_storage:
    db_path: "data/maps/active/world.db"
    graph_cache_size: 10000
  
  historical_storage:
    archive_dir: "data/maps/archive"
    snapshot_triggers:
      room_count: 500            # Trigger snapshot every N rooms
      session_end: true          # Snapshot on disconnect
      time_interval_hours: 24    # Periodic snapshots
    compression:
      fps: 30
      codec: "h264"
  
  semantic_search:
    model: "all-MiniLM-L6-v2"    # Sentence transformer model
    top_k: 5                     # Number of search results
    similarity_threshold: 0.7    # Minimum similarity score
```

### Behavior Simulation

```yaml
behavior:
  reaction_time_min_ms: 200      # Minimum delay between actions
  reaction_time_max_ms: 2000     # Maximum delay between actions
  pause_probability: 0.05        # Chance to pause briefly (5%)
  typo_probability: 0.0          # Chance to make typos (0% = disabled)
```

### Logging

```yaml
logging:
  level: "DEBUG"                 # DEBUG, INFO, WARNING, ERROR
  file: "data/logs/game.log"     # Log file path
  console: true                  # Also log to console
  max_file_size_mb: 10           # Rotate when file reaches this size
  backup_count: 5                # Number of backup files to keep
```

### Web Monitoring Dashboard

```yaml
monitoring:
  enabled: true                  # Enable/disable web dashboard
  host: "127.0.0.1"             # Bind address
  port: 8080                     # Port for dashboard
```

## Environment Variables

You can override any configuration value using environment variables:

```bash
export MUD_HOST="your-mud-server.com"
export MUD_PORT=4000
export MUD_USERNAME="player"
export MUD_PASSWORD="secret"
```

## Multiple Configurations

To use different configurations for different MUDs:

```bash
# For Dead Souls MUD
python -m src.main --config config_dead_souls.yaml

# For Aardwolf MUD
python -m src.main --config config_aardwolf.yaml
```

## Security Notes

⚠️ **Important**: The `config.yaml` file contains sensitive credentials. It is automatically excluded from Git via `.gitignore`.

Never commit your `config.yaml` to version control. Always use the example file as a template.

## Configuration Validation

The configuration is validated at startup using Pydantic models. If a required field is missing or invalid, the application will exit with a clear error message.

## Troubleshooting

### Connection Issues
- Verify `host` and `port` are correct
- Check firewall rules
- Ensure `mud_type` matches your MUD

### LLM Not Working
- Verify Ollama is running: `curl http://localhost:11434/api/tags`
- Check `ai.llm.enabled` is set to `true`
- Ensure the model is installed: `ollama pull llama3.2`

### Mapper Not Saving
- Check that `data/maps/` directory exists and is writable
- Verify disk space is available
- Check file permissions