角色扮演机器人AI模块

Installation

Since mod-playerbots is an obvious hard requirement, follow their Installation Guide until you have a working acore installation with playerbots enabled.

There are three ways to obtain the module sources:

Model Connection Setup

The module supports two API formats, controlled by PBC.APIType:

• openai (default) — OpenAI-compatible /chat/completions endpoint. The module appends /chat/completions to PBC.BaseUrl and sends the API key via Authorization: Bearer header.
• 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.

You 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).

[!IMPORTANT] 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.

Choosing the right model can be tricky. Two tested configurations are listed below.

DeepSeek

DeepSeek 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.

GLM (Zhipu AI)

GLM 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.

Other Models

Any 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.

Use 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:

PBC.ModelExtraParameters = 'frequency_penalty':0.5,'presence_penalty':0.2

becomes "frequency_penalty":0.5,"presence_penalty":0.2 in the request.

When switching providers, pay attention to PBC.Temperature — acceptable ranges vary between models. Check the provider's documentation for the recommended value.

Usage

Start 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.

Start playing, chat with your characters, discuss anything you like, build relationships and enjoy the game.

[!NOTE] 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 for more info.

Configuration

Copy env/dist/etc/modules/playerbots_characters.conf.dist as env/dist/etc/modules/playerbots_characters.conf and adjust it as needed.

Alternative Model

Condensation 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.