# ALE Full-Control Bridge AzerothAI uses **ALE (AzerothCore Lua Engine / mod-ale)** as its privileged in-world control plane. Official documentation: https://www.azerothcore.org/eluna/index.html ALE is an AzerothCore-specific fork and is not guaranteed to be compatible with scripts written for the original Eluna engine. ## Architecture ```text ┌─────────────────────────┐ │ AzerothAI │ │ identity / world model │ └───────────┬─────────────┘ │ intents │ operator control │ ┌───────────────────┴───────────────────┐ │ │ SAFE GAME CONNECTOR ALE CONTROL PLANE normal AI decisions privileged operator lane │ │ │ authenticated queue │ │ └───────────────────┬───────────────────┘ │ ┌─────────▼─────────┐ │ AzerothCore + ALE │ │ worldserver │ └───────────────────┘ ``` A resident model never receives ALE credentials and cannot submit ALE commands. ## Why ALE The current ALE documentation exposes 30 game-side classes and seven Playerbots classes. It includes large surfaces such as Global, Player, Unit, Creature, GameObject, Map, WorldPacket and PlayerBotAI. Examples relevant to AzerothAI include: - global timed events and event registration - world/server/player/map/weather/auction hooks - server command execution - world/character/auth database access - spawning creatures and GameObjects - player inventory, money, quests, reputation, skills, spells and teleportation - Unit health, movement, combat, auras, factions and emotes - chat and packet access - Playerbot strategy/action control - Playerbot inventory/quest/world-object observation The full operator lane exists so AzerothAI does not need a new REST endpoint every time we want to use another documented ALE method. ## Two-way transport ALE has non-blocking HTTP requests, so the bridge is pull/push: ### ALE -> AzerothAI `ale/azerothai_bridge.lua` sends authoritative world events to: `POST /api/bridge/ale/event` Initial subscriptions include: - server startup/shutdown - weather - game-event start/stop - player login/logout - killed by creature - level changes - chat/whisper - zone/map changes - first login - combat enter/leave - repop/resurrect - achievement - quest acceptance A player-zone event automatically feeds the World Population Director. Additional ALE event hooks can be added locally or dynamically through the operator lane. ### AzerothAI -> ALE The ALE script polls: `GET /api/bridge/ale/poll` The server returns one authenticated Lua command chunk. The command executes inside ALE and reports completion to: `POST /api/bridge/ale/result` Commands and recent event telemetry are stored separately from the main realm-state JSON so frequent bridge polling does not fight with normal realm-state revisions. ## Operator API `POST /api/ale/operator` Requires: `Authorization: Bearer ` Supported request modes: ### AzerothCore command ```json {"kind":"command","command":"server info"} ``` Compiles to ALE `RunCommand`. ### Global ALE method ```json {"kind":"global","method":"SendWorldMessage","args":["The world is changing."]} ``` ### Player method ```json {"kind":"player","player":"Zaku","method":"GetHealth"} ``` Player inherits WorldObject and Unit methods, so this lane also covers inherited methods available to a Player. ### PlayerBotAI method ```json {"kind":"playerbotAI","player":"Zaku","method":"DoSpecificAction","args":["follow"]} ``` ### Raw ALE Lua ```json {"kind":"raw","source":"return GetPlayerCount()"} ``` Raw execution is the escape hatch for the complete documented ALE surface: Creature, GameObject, Map, Group, Guild, Item, WorldPacket, specialized Playerbots managers, new ALE methods added later, custom event registration, and multi-step operations. It is disabled unless: `ALE_RAW_EXEC_ENABLED=true` Raw mode is intended only for the private operator environment. ## Security boundary There are two separate credentials: - `ALE_BRIDGE_TOKEN`: known only by AzerothAI and the worldserver Lua bridge. - `ALE_OPERATOR_TOKEN`: protects the privileged operator API. The LLM/provider code knows neither token and has no route that accepts an ALE command. Raw Lua is intentionally not exposed through the ordinary `/api/actions` endpoint. ## Installation Build ALE in AzerothCore: ```bash cd /path/to/azerothcore/modules git clone https://github.com/azerothcore/mod-ale.git mod-ale ``` Re-run CMake and rebuild AzerothCore. Copy: `ale/azerothai_bridge.lua` into the server's `lua_scripts` directory. Add to the private worldserver configuration: ```ini AzerothAI.Url = "http://127.0.0.1:3000" AzerothAI.Token = "same-value-as-ALE_BRIDGE_TOKEN" AzerothAI.PollMs = "750" AzerothAI.ProtectedCharacter = "Zaku" ``` On AzerothAI configure: ```text ALE_BRIDGE_TOKEN= ALE_OPERATOR_TOKEN= ALE_RAW_EXEC_ENABLED=true ``` Use raw execution only when AzerothAI is deployed privately and the operator endpoint is not exposed without authentication. ## Zaku plot armor The ALE bridge installs damage modifiers for common player- and creature-originated damage paths. When the target name matches `AzerothAI.ProtectedCharacter`: ```text damage >= current health ↓ new damage = current health - 1 ↓ Zaku remains at 1 HP ``` This rule lives only in runtime infrastructure. Zaku's identity context, memories, and language-model prompt do not include the plot-armor setting. AzerothAI still treats any bridge report claiming Zaku died as a control-plane fault rather than writing a death record. ## What "full control" means The bridge provides an operator path to **everything exposed to Lua by the installed ALE build**. It does not magically expose private/internal C++ APIs that ALE itself does not bind. If we later need a core function that is not present in ALE, that specific function belongs in a small custom AzerothCore C++ module and can be attached to the same control plane. This keeps our architecture layered: 1. ALE first for documented live-world control. 2. AzerothCore commands where appropriate. 3. SQL only where a supported API is insufficient. 4. Custom C++ bindings only for genuinely unexposed core behavior.