AIPLAYER/docs/configuration.md

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

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

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

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

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

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

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

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:

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:

# 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