AzerothAI/README.md

AzerothAI — Living Realm prototype

A working private web control plane for an AI-populated, self-hosted realm. The real player is the center of the experience: the Realm Director sets the tone, bot identities provide continuity, and the GM console lets the operator stage the world.

Boundary: AzerothCore handles movement, combat, inventory, progression, and game rules. AzerothAI owns identity, personality, high-level goals, memory, and relationships. No model gets GM access.

What runs today

• Dark navy/gold dashboard inspired by the supplied Living Realm mockup.
• Persistent bot creation, spawn, pause, resume, despawn, and retirement.
• Versioned recipes with per-bot snapshots; explicit recipe reapplication.
• Operator memories, generated observation memories, and directed relationships.
• Realm Director updates goals around a named player and focus zone.
• Manual decision loop: observe → assemble context → decide → validate → connector acknowledgment → memory/event.
• Reconnectable SSE event feed with sequence replay and a 500-event retention window.
• Deterministic personality simulator, Ollama provider, and OpenAI-compatible local model provider.
• GM terminal with history and simulated or confirmed live SOAP commands.
• Durable D1/SQLite state with optimistic revision checks and bounded operation leases.
• Modular TypeScript interfaces for additional game connectors and inference providers.
• Live World Monitor for Zaku, population bands, zones, Hardcore deaths, ALE pulse, and system health.
• Disposable playable realm profile for AzerothCore + Playerbots + ALE.
• Temporary Windows-PC/Ubuntu-VM lab profile with Windows-hosted Ollama/Qwen and migration export.

The default demo contains six sample identities and four recipes. It is not connected to an actual game server or LLM. Simulation acknowledgments do not mean a character was created in WoW.

Source layout

app/page.tsx                  Dashboard and all management views
app/globals.css               Navy/gold visual theme and responsive layout
app/api/state/route.ts        Persistent realm snapshot
app/api/actions/route.ts      Validated commands
app/api/events/route.ts       Reconnectable SSE batches
app/api/health/route.ts       Configuration availability (no secrets)
core/types.ts                 Game-neutral contracts and domain types
core/service.ts               Lifecycle, recipes, memory, director, audit
core/validation.ts            Zod input and decision validation
core/connectors/index.ts      Simulation and AzerothCore HTTP bridge adapters
core/llm/index.ts             Deterministic, Ollama, compatible providers
core/gm.ts                    Human-only allowlisted SOAP command channel
core/store.ts                 D1 repository and optimistic concurrency
core/seed.ts                  Explicit demo data
 db/schema.ts                 Drizzle schema
 drizzle/                    Generated schema migrations
 docs/CONNECTORS.md           Bridge contract and extension guide
 docs/OPERATIONS.md           Local setup, credentials, limitations
 tests/core.test.cjs          Core behavior and failure tests
 scripts/test-core.mjs        Compile/run tests
 deploy/playable/              Private playable-realm bootstrap
 deploy/pc-lab/                Temporary Windows + Ubuntu VM lab

Local quick start

Use Node 22.13+ and the pnpm version pinned in package.json. The project runs locally with Cloudflare's Worker emulator and SQLite; no paid cloud account or model is required for simulation.

corepack enable
pnpm install --frozen-lockfile
pnpm build
node --import ./scripts/sites-env.mjs ./node_modules/wrangler/bin/wrangler.js d1 execute DB --local --config dist/server/wrangler.json --persist-to .wrangler/state --file drizzle/0000_old_deathbird.sql
pnpm start

Open the loopback URL printed by Wrangler (normally http://127.0.0.1:8787). pnpm start is local, not a deployment. Preserve .wrangler/state for persistence. The managed Work environment uses its supervised preview instead.

For live integrations, copy .env.example to .dev.vars, populate the needed settings, and restart the local runtime. Do not commit that file. Hosted settings are supplied separately through the hosting platform. A cloud-hosted app cannot reach your home server's localhost.

Fastest path to a playable temporary lab

For a Windows gaming PC with an Ubuntu VM, use deploy/pc-lab/README.md. It keeps WoW and Qwen/Ollama on Windows while AzerothCore, Playerbots, ALE, MySQL, and AzerothAI run inside the VM.

For a dedicated Linux host, use deploy/playable/README.md.

Try the intended flow

1. Open Realm Director. Pick the experience, enter your character and zone, and apply your brief.
2. Create an offline bot with a recipe. Open its profile and spawn it in simulation.
3. Add a memory and a relationship. Run a decision and inspect the resulting intent.
4. Edit its recipe. Notice that the bot keeps its old snapshot until explicitly updated.
5. Open GM Console and try .announce Welcome to the realm!. The response is labeled simulated.
6. Watch Event Stream and reload the app to verify state persists.

Checks

node node_modules/typescript/bin/tsc --noEmit
node scripts/test-core.mjs
pnpm build

Integration status

The GM SOAP client is implemented against AzerothCore's documented remote-access protocol; live execution needs your server and credentials. The bot HTTP connector is an implemented client for our bridge contract, not an assertion that stock AzerothCore exposes those endpoints. A game-side adapter for your actual core/Playerbots branch still needs implementation and end-to-end testing.

AzerothCore version/client selection must be settled before that adapter is written; a Classic-style experience does not establish compatibility with the modern WoW Classic client. This prototype deliberately stores no client-version assumption in its domain model.

See operations for operational limits and connectors for API contracts.