Skip to content

AI Players Guide

Overview

AI Players are autonomous LLM-powered agents that play MAID as virtual players. Unlike NPCs — which are world-owned characters driven by the NPC autonomy system — AI Players connect through virtual sessions and interact with the game exactly as human players do: they read room descriptions, type commands, fight monsters, and chat with other players.

Key features:

  • Autonomous Gameplay - AI Players explore, fight, trade, and socialize without human intervention
  • Three-Layer Cognitive Architecture - Fast reactive reflexes, routine action planning, and deep strategic reasoning
  • Personality System - Big Five personality traits mapped to gameplay behaviors with ready-made presets
  • Memory & Learning - Episodic, semantic, and procedural memory systems that persist across sessions
  • Cost Control - Tiered model usage, token budgets, and burst/sustained rate limits keep costs predictable
  • Observability - Every decision is logged and inspectable via thought traces and decision logs
  • Bug Filing - AI Players can detect and report game issues they encounter during play

AI Players vs NPCs

NPCs are world entities managed by the NPC autonomy system and DialogueComponent. AI Players are full session participants — they log in, receive game output, and issue commands through the same pipeline as human players. They occupy player slots, not NPC slots.

Quick Start

1. Enable AI Players

Set the following environment variables (or add to your .env file):

MAID_AI_PLAYERS__ENABLED=true
MAID_AI_PLAYERS__MAX_AGENTS=5

2. Configure an LLM Provider

AI Players need at least one LLM provider. The cheapest option uses Chat Jimmy (free tier):

MAID_AI_PLAYERS__CHEAP_MODEL_PROVIDER=chatjimmy
MAID_AI_PLAYERS__CHEAP_MODEL_NAME=llama3.1-8B

For higher-quality reasoning, configure an expensive tier provider:

MAID_AI_PLAYERS__EXPENSIVE_MODEL_PROVIDER=anthropic
MAID_AI_PLAYERS__EXPENSIVE_MODEL_NAME=claude-sonnet-4
MAID_AI__ANTHROPIC_API_KEY=sk-ant-...

3. Spawn an AI Player

Auto-spawn on server start:

MAID_AI_PLAYERS__AUTO_SPAWN_ON_START=true
MAID_AI_PLAYERS__AUTO_SPAWN_COUNT=3

Spawn via admin command in-game:

@ai spawn "Aldric" --preset explorer
@ai spawn "Brunhilde" --preset warrior

Spawn programmatically:

from maid_engine.ai_players.config import AIPlayerConfig
from maid_engine.ai_players.manager import AIPlayerManager

config = AIPlayerConfig(
    name="Aldric",
    personality_preset="explorer",
)
player = await manager.spawn(config)

How It Works

AI Players use a three-layer hybrid control architecture inspired by robotics research. Each layer runs concurrently — the fast reactive layer never waits for the slow deliberative layer:

┌───────────────────────────────────────────────────────────┐
│                        AIPlayer                           │
│                                                           │
│  Layer 3: DELIBERATIVE (async, expensive LLM)             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  Goal Generation · Strategic Reflection · Planning  │  │
│  │  Memory Consolidation · Session Reviews             │  │
│  └───────────────────────────┬─────────────────────────┘  │
│                              │ updates plans/goals        │
│  Layer 2: EXECUTIVE (1–3s cadence, cheap LLM)             │
│  ┌───────────────────────────▼─────────────────────────┐  │
│  │  Perception · Memory Encoding · Plan Sequencing     │  │
│  │  Action Selection · Replanning · Task Tracking      │  │
│  └───────────────────────────┬─────────────────────────┘  │
│                              │ provides next action       │
│  Layer 1: REACTIVE (every tick, zero LLM, <10ms)          │
│  ┌───────────────────────────▼─────────────────────────┐  │
│  │  Combat FSM · Survival Reflexes · Flee-on-Death     │  │
│  │  Heal-on-Critical · Social Reflex · Idle Emotes     │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              World Model & Memory                   │  │
│  │  (Map Graph, Inventory, Entity Tracker, Memories)   │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘
Layer Speed LLM Usage Purpose
Reactive Every tick None Instant combat/survival responses. Suppresses higher layers when triggered.
Executive 1–3 seconds Cheap model Routine action selection, observation parsing, plan execution.
Deliberative Minutes Expensive model Strategic planning, goal generation, memory consolidation, reflection.

Configuration

Key environment variables for getting started:

Variable Type Default Description
MAID_AI_PLAYERS__ENABLED bool false Master switch for the AI Player system
MAID_AI_PLAYERS__MAX_AGENTS int 10 Maximum concurrent AI Players
MAID_AI_PLAYERS__CHEAP_MODEL_PROVIDER str chatjimmy LLM provider for routine operations
MAID_AI_PLAYERS__EXPENSIVE_MODEL_PROVIDER str anthropic LLM provider for strategic reasoning
MAID_AI_PLAYERS__GLOBAL_MAX_COST_PER_HOUR float 1.0 Maximum hourly spend across all agents (USD)
MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_HOUR float 0.10 Sustained hourly spend per agent (USD)
MAID_AI_PLAYERS__BUDGET_POLICY str enforce Budget enforcement: enforce, warn, or unlimited

For the complete configuration reference, see Configuration.

Personality System

Each AI Player has a personality defined by eight dimensions — five Big Five traits plus three game-specific extensions. These traits directly influence gameplay behavior:

Dimension Low (0.0) High (1.0)
Openness Sticks to known areas and proven tactics Explores unknown areas, tries new strategies
Conscientiousness Impulsive, acts on instinct Detailed plans, careful resource management
Extraversion Solo play, avoids social interaction Initiates conversations, joins groups, trades
Agreeableness Competitive, self-interested Helps others, shares resources, avoids conflict
Neuroticism Brave, takes risks, fights aggressively Cautious, heals early, avoids danger
Combat Aggression Defensive, retreats from fights Attacks first, pursues enemies
Curiosity Skips text, focuses on mechanics Reads descriptions, talks to NPCs
Patience Gets bored quickly, seeks variety Grinds willingly, farms resources

Personality Presets

Use presets for quick configuration instead of setting individual dimensions:

Preset Playstyle Key Traits
explorer Map completionist, lore reader High openness (0.9), curiosity (0.9), low combat aggression (0.3)
warrior Combat-focused, seeks fights High combat aggression (0.9), patience (0.7), low neuroticism (0.2)
social_butterfly Chats with everyone, group player High extraversion (0.95), agreeableness (0.9), low combat aggression (0.2)
merchant Trades, manages resources High conscientiousness (0.8), patience (0.8), low combat aggression (0.2)
cautious_scholar Slow, thorough, avoids danger High conscientiousness (0.9), curiosity (0.95), neuroticism (0.8)
berserker Reckless, aggressive, impatient Max combat aggression (1.0), low conscientiousness (0.1), patience (0.2)
balanced Default — all traits at 0.5 Even distribution across all dimensions 
from maid_engine.ai_players.config import AIPlayerConfig

# Use a preset
config = AIPlayerConfig(name="Aldric", personality_preset="explorer")

# Or customize individual traits
from maid_engine.ai_players.config import PersonalityDimensions

config = AIPlayerConfig(
    name="Brunhilde",
    personality=PersonalityDimensions(
        openness=0.5,
        conscientiousness=0.7,
        extraversion=0.3,
        agreeableness=0.4,
        neuroticism=0.2,
        combat_aggression=0.8,
        curiosity=0.6,
        patience=0.5,
    ),
)

What AI Players Can Do

  • Explore rooms and build a mental map of the world (stored in WorldModel)
  • Fight monsters using combat reflexes (Layer 1 FSM) and tactical decisions (Layer 2)
  • Manage health — heal when critical, flee when outmatched
  • Buy and sell items at shops, manage inventory
  • Talk to NPCs and other players, including AI-powered dialogue
  • Learn from experience — episodic memories, procedural command sequences, and reflective meta-insights persist across sessions
  • Set and pursue goals — hierarchical planning from session-level goals down to individual actions
  • File bug reports about game issues encountered during play (broken exits, missing items, etc.)
  • Share knowledge — agents can share discovered map data and learned facts through a shared knowledge pool

Limitations

Important Considerations

  • LLM provider required — At minimum, a cheap-tier LLM is needed for Layer 2 reasoning. Layer 1 (reactive) works without any LLM. Chat Jimmy provides a free option.
  • Cost scales with agent count — Each active agent makes LLM calls. Budget controls are essential for production deployments.
  • Not a replacement for NPCs — AI Players and NPCs are separate systems. NPCs use DialogueComponent and the NPC autonomy system; AI Players use virtual sessions and the cognitive architecture.
  • Quality depends on LLM capability — Cheap models handle routine actions well but may struggle with complex strategic reasoning. Use the expensive tier for deliberative operations.
  • Player slots — AI Players count against max_agents, not NPC limits. Plan server capacity accordingly.

Next Steps