moonwell-core/modules/mod-playerbots-ai/README.md

MoonWell Playerbots AI

This module sends a local /say or public-channel message to the LLM only when a real player mentions the complete name of an online bot. A channel bot must be a channel member; a /say bot must be within the server's normal listening range. HTTP work runs outside the AzerothCore world thread.

Alice AI LLM Flash can classify direct natural-language requests into a small allowlisted set of native playerbots commands. The server validates the command again and executes it only against the addressed bot; existing playerbots ownership and group security checks still apply.

The routing prompt covers party movement and combat, LFG, combat/non-combat strategies, spells, RTI/RTSC, focus healing, loot lists, inventory operations, quests, pets, talents, glyphs, maintenance, and information commands documented in the upstream Playerbot Commands wiki. Administrative, console, account, debug/cheat, and destructive destroy/drop/mail commands are intentionally not executable through the LLM.

Common Russian movement/combat phrases use a deterministic fast path. Other requests first pass through a command-only classifier; ordinary conversation is then sent separately to the roleplay prompt. While AI routing is enabled, the legacy public-channel parser is bypassed and setup-modules.sh also forces AiPlayerbot.RandomBotTalk = 0. RandomBotTalk consumes incoming chat packets inside each bot, so bypassing only the parser does not prevent its delayed stock replies. Whisper, party, raid, and guild command hooks remain unchanged.

Recognized commands produce a gender-aware local-chat acknowledgement (Понял команду. or Поняла команду.) before they are handed to the native playerbots command handler. Bot and player gender are also included in the LLM context for pronoun, past-tense verb, and adjective agreement. Russian requests to show bags or inventory use the native inv command; open items is reserved for actually opening container items.

Trade and quest requests have deterministic link-preserving routes before the LLM classifier:

• дай/передай [item] -> t [item]; начни обмен -> t
• покажи задания -> quests all; completed/incomplete filters are supported
• покажи прогресс [quest] -> q [quest]
• прими [quest] / прими все задания -> accept [quest] / accept *
• поделись [quest] -> share [quest]
• выбери [item] в награду -> r [item]
• сдай готовое задание -> talk
• откажись от [quest] -> drop [quest] only with an explicit quest link

These routes preserve the original WoW hyperlink byte-for-byte. The local playerbots trade action continues processing after it creates the trade, so one t [item] command both initiates the exchange and places the requested item in the trade window.

The bundled playerbots-ai bridge uses the Yandex AI Studio OpenAI-compatible Chat Completions API and defaults to Alice AI LLM Flash.

Configuration

Set these values in the repository .env:

ACORE_PLAYERBOTS_AI_ENABLED=1
ACORE_PLAYERBOTS_AI_COMMANDS_ENABLED=1
YANDEX_AI_API_KEY=<service-account API key>
YANDEX_AI_FOLDER_ID=<Yandex Cloud folder ID>

Until the subscription system exists, public access is controlled by one explicit switch:

ACORE_PLAYERBOTS_AI_AVAILABLE_FOR_ALL=1

1 allows every player to reach the bridge. 0 denies LLM access to everyone without spending tokens. When subscriptions are implemented, their entitlement check will be added to the disabled branch instead of using a temporary manual account list.

The command classifier has a persistent SQLite cache in the playerbots-ai-cache Docker volume. The key excludes the addressed bot name, so repeated phrases such as “покажи инвентарь” are shared across players and bots. Both commands and “ordinary chat, not a command” decisions are cached. The cache does not store roleplay responses or conversation history. Obvious social phrases such as greetings, “как дела?” and “расскажи о себе” skip the command classifier entirely: they still receive an Alice roleplay reply, but do not pay the roughly 800-token command-catalog prompt first.

PLAYERBOTS_AI_CLASSIFIER_CACHE_ENABLED=1
PLAYERBOTS_AI_CLASSIFIER_CACHE_TTL_SECONDS=604800
PLAYERBOTS_AI_CLASSIFIER_CACHE_MAX_ENTRIES=10000

Changing the classifier prompt automatically creates a new cache namespace. Old rows expire normally, and the oldest rows are removed at the size limit.

The default model URI is:

gpt://<YANDEX_AI_FOLDER_ID>/aliceai-llm-flash

Run ./start-server.sh or scripts/prod-deploy.sh. The deployment wrapper builds and starts the bridge before ac-worldserver.

Never commit a populated API key.

Full Yandex response JSON is logged by default by the bridge:

PLAYERBOTS_AI_LOG_API_RESPONSES=1

Use docker compose logs -f playerbots-ai to follow classifier and chat responses. Authentication headers and the API key are never logged.