UO Agents — Autonomous NPCs & Adventurer Bots for Ultima Online

AI-driven agents for Ultima Online that perceive the game world, make decisions, and act autonomously. NPCs chat and wander with personality. PC (Player Character) agents fight monsters, loot corpses, craft items, trade, and socialize — all configured via YAML archetype files.

Built on a Soul/Mind/Body/Senses architecture inspired by the Stanford Generative Agents paper, with rule-based combat (no LLM latency in fights) and LLM-powered social interaction.

Architecture

coordinator/
  agents/base.py        # Agent dataclass — memory, perception, thinking
  senses/world_state.py # WorldState, Mobile, CombatState, InventorySnapshot
  body/
    combat.py           # Rule-based combat (personality-driven flee/heal)
    navigation.py       # Named-location travel + pathfinding
    looting.py          # Corpse/item looting with greed-based radius
    crafting.py         # Gathering + crafting sessions (mining, smithing)
    trading.py          # Buy/sell at NPC vendors
  mind/
    drives.py           # Drive evaluator (survival, wealth, power, social, exploration)
    goals.py            # Goal manager with drive-based prioritization
    planner.py          # Rule-based plans (grind loops, travel, rest)
    llm_planner.py      # Periodic LLM strategic re-evaluation (~60s)
  actions/executor.py   # LLM output → game commands
  llm/client.py         # Ollama HTTP client
  main.py               # Coordinator — TCP server, tick loop, PC/NPC branching
scripts/
  agent_bridge.py       # ClassicAssist macro — bridges game ↔ coordinator
config/
  archetypes/           # PC agent YAML configs
    warrior.yaml        # Aldric — brave melee fighter, flee@15%
    crafter.yaml        # Brunhild — miner/smith, wealth-focused, flee@40%
    explorer.yaml       # Finn — cartographer, exploration-focused, flee@30%
    socializer.yaml     # Rosalind — bard/gossip, tavern-lover, flee@50%
config.yaml             # NPC agents, locations, LLM settings

How It Works

NPCs (blacksmith, tavern keeper, etc.) use a simple loop: perceive → LLM thinks → act (SAY/MOVE/WAIT/EMOTE).

PC agents use a priority chain — no LLM in the combat loop:

1. Combat (rule-based) — attack, heal, flee based on personality traits
2. Loot — grab nearby corpses/items
3. Social (LLM) — respond to chat from players
4. Crafting/Trading — gather materials, craft items, buy supplies
5. Goal pursuit (planner) — grind loops, travel, rest
6. LLM re-evaluation (~60s) — strategic goal generation
7. Idle — wait

Combat decisions are 100% deterministic given the same world state and personality. A warrior with bravery: 0.8 flees at 15% health; a socializer with bravery: 0.2 flees at 50%.

Quick Start

Prerequisites

• Python 3.10+
• Ollama for LLM inference
• ClassicUO + ClassicAssist for the game bridge
• A ServUO server (or any UO shard)

Setup

# Clone
git clone https://github.com/hbbtstar/uo_agents.git
cd uo_agents

# Virtual environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Pull an LLM model
ollama pull qwen2.5:3b-instruct

# Run tests (no game connection needed)
python test_standalone.py
python test_world_state.py
python test_combat.py
python test_navigation.py
python test_archetypes.py

Run the Coordinator

# Test mode (simulated game states)
python coordinator/main.py --test

# Live mode (listens on port 9999 for bridge connections)
python coordinator/main.py

Connect a Bridge

1. Open ClassicAssist in ClassicUO
2. Create a new Python macro
3. Paste the contents of scripts/agent_bridge.py
4. Edit AGENT_NAME to match a configured agent
5. Run the macro

Adding a PC Agent

Create a YAML file in config/archetypes/:

name: "YourAgent"
agent_type: "pc"
archetype: "warrior"

personality: |
  You are YourAgent, a bold warrior...

personality_traits:
  bravery: 0.8      # 0=coward, 1=fearless
  greed: 0.6        # 0=generous, 1=greedy
  sociability: 0.4   # 0=loner, 1=social butterfly
  aggression: 0.7    # 0=passive, 1=attacks on sight
  loyalty: 0.7       # 0=treacherous, 1=loyal

drive_weights:
  survival: 1.0
  wealth: 0.7
  power: 0.8
  social: 0.3
  exploration: 0.5

combat:
  style: "melee"
  flee_health_pct: 0.15

goals:
  - "Grow stronger through combat"
  - "Accumulate gold from monster loot"

home_location: "britain_bank"

The coordinator auto-loads all config/archetypes/*.yaml on startup.

Tests

test_standalone.py   — NPC + PC agent behavior (mock LLM)
test_world_state.py  — WorldState parsing, edge cases
test_combat.py       — Combat decisions, personality effects
test_navigation.py   — Navigator, LootController, Planner, grind loop
test_archetypes.py   — Archetype loading, drive differences, crafting/trading

License

This project is provided as-is for educational and hobby purposes.