{"id":50307331,"url":"https://github.com/deseven/mod-playerbots-characters","last_synced_at":"2026-05-28T17:30:55.687Z","repository":{"id":352742418,"uuid":"1215096318","full_name":"deseven/mod-playerbots-characters","owner":"deseven","description":"A character-focused LLM integration for AzerothCore/Playerbots","archived":false,"fork":false,"pushed_at":"2026-05-26T23:32:59.000Z","size":2302,"stargazers_count":16,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-27T01:15:54.685Z","etag":null,"topics":["azerothcore-module","llm","playerbots","roleplaying"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deseven.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T13:29:12.000Z","updated_at":"2026-05-26T23:19:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/deseven/mod-playerbots-characters","commit_stats":null,"previous_names":["deseven/mod-playerbots-characters"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/deseven/mod-playerbots-characters","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deseven%2Fmod-playerbots-characters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deseven%2Fmod-playerbots-characters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deseven%2Fmod-playerbots-characters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deseven%2Fmod-playerbots-characters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deseven","download_url":"https://codeload.github.com/deseven/mod-playerbots-characters/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deseven%2Fmod-playerbots-characters/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33619965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azerothcore-module","llm","playerbots","roleplaying"],"created_at":"2026-05-28T17:30:51.589Z","updated_at":"2026-05-28T17:30:55.676Z","avatar_url":"https://github.com/deseven.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Playerbots Characters (PBC)\n\nThis is an [AzerothCore](https://www.azerothcore.org) module built around [mod-playerbots](https://github.com/mod-playerbots/mod-playerbots), breathing new life into bots by turning them into true in-game characters — companions with pre-defined personalities, memory, and relationships. Heavily inspired by [mod-ollama-chat](https://github.com/DustinHendrickson/mod-ollama-chat), but taking a different, more complex approach — focusing on the roleplaying experience rather than emulating real WoW players.\n\nThink old Bioware games with companions — that's the core idea. The intended use is a fresh start at low rates with a full party of altbots playing alongside you, developing their own stories as you progress through the game together.\n\n\u003e [!IMPORTANT]\n\u003e The module is currently in active development and things could be changing rapidly. Before updating your copy, it's highly recommended to do a database backup, read the changes and notes in [the Releases](https://github.com/deseven/mod-playerbots-characters/releases) and check your server logs after running the newer version. There should be no hard incompatibilities, but new config variables are getting added, existing ones change their defaults, old routines get replaced and so on.\n\n\n## How It Works\n\nThis module extends the bots provided by `mod-playerbots` into full characters — giving them a voice, memories, relationships, and the ability to react to events and converse with companions. The bot logic (combat, movement, questing) remains entirely untouched; this module only adds the personality layer on top.\n\nCharacters react to in-game events (chat, item pickups, duels, level-ups, boss kills, quests) based on configurable reply chances. When a character rolls to respond, a prompt is built from its character card, chat history, relationships, live context, and the event itself — then sent to a compatible LLM API, and the response is spoken by the character in-game.\n\nOver time, chat history grows. When it reaches the configured token limit, a condensation process extracts discrete narrator-style memories with importance scores from the history, then clears all history. These memories are selected by importance at prompt-build time within a token budget, keeping the in-memory context bounded while preserving what matters. This way, characters gradually develop lasting memories and personality traits.\n\nRelationships are tracked between characters and real players, as well as other characters. When a name is mentioned enough times in a character's history, a relationship update is triggered — generating or updating a brief description of how the character feels about that person. These are included in future prompts, giving characters continuity with their companions.\n\n\n## Installation\n\nSince mod-playerbots is an obvious hard requirement, follow their [Installation Guide](https://github.com/mod-playerbots/mod-playerbots/wiki/Installation-Guide) until you have a working acore installation with playerbots enabled.\n\nThere are three ways to obtain the module sources:\n\n### Method 1: Specific release tag (recommended)\n\nClone a specific tagged release:\n\n```sh\ncd modules\ngit clone --depth 1 --branch \u003ctag_name\u003e git@github.com:deseven/mod-playerbots-characters.git\n```\n\nWhen you want to upgrade to a newer release tag:\n\n```sh\ncd modules/mod-playerbots-characters\ngit fetch --tags\ngit checkout \u003cnew_tag_name\u003e\n```\n\nA list of all available tags can be found on the [Releases](https://github.com/deseven/mod-playerbots-characters/releases) page.\n\n### Method 2: Source code archive\n\nDownload a `.zip` or `.tar.gz` source archive from the [Releases](https://github.com/deseven/mod-playerbots-characters/releases) page and extract it into the `modules` directory. The extracted folder must be named `mod-playerbots-characters`.\n\n### Method 3: Latest (bleeding edge)\n\nClone the repository normally to get the latest changes:\n\n```sh\ncd modules\ngit clone git@github.com:deseven/mod-playerbots-characters.git\n```\n\nThis gives you the most recent commits from the `main` branch. You can `git pull` at any time to update.\n\nAfter obtaining the sources using any of the methods above, rebuild the server normally.\n\n\u003e [!NOTE]\n\u003e The module includes bundled copies of [nlohmann/json](https://github.com/nlohmann/json) in `deps/nlohmann/json.hpp` and [yhirose/cpp-httplib](https://github.com/yhirose/cpp-httplib) in `deps/yhirose/cpp-httplib/httplib.h`, so no external libraries are required.\n\nIf [mod_weather_vibe](https://github.com/hermensbas/mod_weather_vibe) is also installed, weather states from it will be included in the character's scene description.\n\n\n## Configuration\n\nCopy `env/dist/etc/modules/playerbots_characters.conf.dist` as `env/dist/etc/modules/playerbots_characters.conf` and adjust it as needed.\n\n\n### Model Connection Setup\n\nThe module supports two API formats, controlled by `PBC.APIType`:\n\n- **`openai`** (default) — OpenAI-compatible `/chat/completions` endpoint. The module appends `/chat/completions` to `PBC.BaseUrl` and sends the API key via `Authorization: Bearer` header.\n- **`anthropic`** — Anthropic Messages API `/messages` endpoint. The module appends `/messages` to `PBC.BaseUrl` and sends the API key via `x-api-key` header with the `anthropic-version: 2023-06-01` header.\n\nYou need to configure at least `PBC.BaseUrl`, `PBC.Model` and `PBC.ApiKey` before the module can generate responses. The relevant config options are in the **API CONNECTION** and **MODEL PARAMETERS** sections of the config file. After configuring, you can use `.chars api-test` to quickly verify that the connection is working (or `.chars alt-api-test` for the alternative model).\n\n\u003e [!IMPORTANT]\n\u003e Due to the complexity and length of the prompts, locally-run models on average home hardware will generally struggle and produce low-quality output as context grows. A cloud-based model with a large context window is recommended. Make sure to also adjust `PBC.MaxHistoryCtx` accordingly — a good starting point is around 25% of the model's total context window. Aim for at least 32k in general, anything less could lead to poor efficiency of character relationship tracking and memory extraction.\n\nChoosing the right model can be tricky. Two tested configurations are listed below.\n\n#### DeepSeek\n\n| Setting | Value |\n|---|---|\n| `PBC.APIType` | `openai` |\n| `PBC.BaseUrl` | `https://api.deepseek.com/v1` |\n| `PBC.Model` | `deepseek-chat` |\n| `PBC.Temperature` | `1.6` |\n| `PBC.MaxHistoryCtx` | `32768` |\n| `PBC.MaxMemoriesCtx` | `8192` |\n| `PBC.ModelExtraParameters` | `'frequency_penalty':0.5,'presence_penalty':0.2` |\n| `PBC.ApiKey` | your API key from [DeepSeek platform](https://platform.deepseek.com/) |\n\nDeepSeek offers a reasonable cost/capabilities compromise and can be considered the cheapest viable option. The `frequency_penalty` and `presence_penalty` extra parameters help reduce repetitive output. Expect to spend under $0.5 for several hours of play.\n\n#### GLM (Zhipu AI)\n\n| Setting | Value |\n|---|---|\n| `PBC.APIType` | `openai` |\n| `PBC.BaseUrl` | `https://api.z.ai/api/paas/v4` |\n| `PBC.Model` | `glm-5.1` |\n| `PBC.Temperature` | `1.0` |\n| `PBC.MaxHistoryCtx` | `32768` |\n| `PBC.MaxMemoriesCtx` | `8192` |\n| `PBC.ModelExtraParameters` | `'thinking':{'type':'disabled'}` |\n| `PBC.ApiKey` | your API key from [Z.ai](https://z.ai/manage-apikey/apikey-list) |\n\nGLM 5.1 has a built-in \"thinking\" mode that would reach `PBC.MaxResponseLength` very fast — disabling it via `ModelExtraParameters` is required for this case, unless you lift the limit. The model handles the required tasks impressively well, though the cost adds up fairly quickly. Expect to spend around $2 per long game session with a full party.\n\n#### Other Models\n\nAny OpenAI-compatible API should work with `PBC.APIType = openai` — just set `PBC.BaseUrl` to the endpoint (the module appends `/chat/completions` automatically), `PBC.Model` to the model identifier, and `PBC.ApiKey` to your bearer token. If the endpoint doesn't require authentication (e.g. a local Ollama or LM Studio instance), leave `PBC.ApiKey` empty.\n\nUse `PBC.ModelExtraParameters` to inject provider-specific JSON into the request body — this works the same way for both `openai` and `anthropic` API types. Make sure to use parameter names that are valid for your chosen API type (e.g. `top_p` and `top_k` for Anthropic, `frequency_penalty` and `presence_penalty` for OpenAI-compatible providers). Single quotes are used instead of double quotes and are automatically replaced at runtime:\n\n```\nPBC.ModelExtraParameters = 'frequency_penalty':0.5,'presence_penalty':0.2\n```\n\nbecomes `\"frequency_penalty\":0.5,\"presence_penalty\":0.2` in the request.\n\nWhen switching providers, pay attention to `PBC.Temperature` — acceptable ranges vary between models. Check the provider's documentation for the recommended value.\n\n### Alternative Model\n\nCondensation and relationship updates are critical — their output becomes permanent parts of the character's context. The `ALTERNATIVE API` config section lets you route these tasks to a more capable model while keeping the main chat on a cheaper/faster one. Parameters follow the same format as the main model, prefixed with `AltModel`.\n\n### HTTP Server \u0026 Web App\n\n![PBC Web App](https://d7.wtf/s/pbc-web.png)\n\nThe module can optionally run a built-in HTTP/WS server with a web frontend, providing an interface for managing the characters, as well as an API for external tools and integrations. The web interface supports viewing and editing chat history, relationships and memories. This is disabled by default and could be enabled in the config, read the `HTTP SERVER` section and follow the comments there.\n\n\u003e [!NOTE]\n\u003e If you plan to use the web app for a considerable amount of time without touching the game, it's also recommended to set `PreventAFKLogout` to `2` in your `worldserver.conf`.\n\n### Playerbots Adjustments\n\nRecommended adjustments to the playerbots config (`playerbots.conf`), to make bots less talkative in order to not interfere with the new character logic:\n\n| Setting | Value | Purpose |\n|---|---|---|\n| `AiPlayerbot.EnableBroadcasts` | 0 | Disables loot / quest / kill broadcasts |\n| `AiPlayerbot.RandomBotTalk` | 0 | Disables random talking in say / yell / general channels |\n| `AiPlayerbot.RandomBotEmote` | 0 | Disables random emoting |\n| `AiPlayerbot.RandomBotSuggestDungeons` | 0 | Disables dungeon suggestions in chat |\n| `AiPlayerbot.EnableGreet` | 0 | Disables greeting when invited |\n| `AiPlayerbot.GuildFeedback` | 0 | Disables guild event chatting |\n| `AiPlayerbot.RandomBotSayWithoutMaster` | 0 | Disables bots talking without a master |\n| `AiPlayerbot.RPWarningCooldown` | 999999 | Increases delay between \"missing reagents\" messages and such |\n| `AiPlayerbot.EnableAutoTradeOnItemMention` | 0 | Disables automatic trades and item listings on item mention (from [mod-playerbots@8caf37a](https://github.com/mod-playerbots/mod-playerbots/commit/8caf37af97b74545f8fa65172095803466ad8a06)) |\n\n\n## Usage\n\nStart the server, set up some altbots for yourself or invite existing random bots, then write cards for them as you see fit. See `characters/Example.card.txt` for an example of how to write a character card. The character name in the filename must match the in-game character name exactly to be picked up. It is recommended to write cards in second person (using \"you/your\"), because default prompts and request structure follow this format.\n\nStart playing, chat with your characters, discuss anything you like, build relationships and enjoy the game.\n\n\u003e [!NOTE]\n\u003e Depending on the model you are using, your mileage may vary. Do regular backups with `modules/mod-playerbots-characters/tools/pbc_backup.sh` and adjust things as needed either in the database (followed by `.chars reload` command) or via the included web app. There are also two helper tools (`pbc_info.sh` and `pbc_history.sh`) which might help with tracking what's going on. You can also steer the narration a bit by using `.chars narrate` and `.chars narrate-party` commands. Check out [available commands](docs/COMMANDS.md) for more info.\n\n### Web App\n\nIf you have the HTTP server configured, you can use `.chars web` command to get a one-time password that you can then use to authorize in the web app.\n\n## Debugging\n\nTwo config options control debug output:\n\n- `PBC.DebugEnabled` — enables general debug logging (event dispatching, roll chances, etc.)\n- `PBC.DebugShowFullRequest` — when enabled alongside `DebugEnabled`, logs the full request body and response body for every LLM API call. Useful for diagnosing issues with non-standard API providers where the response format may differ from OpenAI's.\n\n\n## Additional Documentation\n\n- [Events](docs/EVENTS.md) — list of in-game events characters can react to\n- [Commands](docs/COMMANDS.md) — available in-game and console commands\n- [Prompts](docs/PROMPTS.md) — prompt templates, customization and template variables\n- [API Reference](docs/API.md) — HTTP API and WebSocket documentation\n- [Frontend](frontend/README.md) — web interface build and development\n\n\n## Support \u0026 Contributing\n\nContributions are welcome — feel free to open a pull request. If you need help or found a bug, [open an issue](https://github.com/deseven/mod-playerbots-characters/issues/new).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeseven%2Fmod-playerbots-characters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeseven%2Fmod-playerbots-characters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeseven%2Fmod-playerbots-characters/lists"}