Run LLM NPCs

Needs Testing

Language-model NPCs are turned off by default.

Switching them on can send your players' public chat to a third party. You should probably inform your players of this.

You will need an Anthropic API key, which is billed to you.

StoryForce accepts no liability for charges billed to your Anthropic account as a result of using this feature. You do so at your own risk.

What leaves your server

When a player speaks to a cast LLM NPC, their line goes to Anthropic's API with the NPC's persona and the conversation so far.

  • Bystander speech is captured too. sf_llmnpc_overhear defaults at 300 units. Ordinary public chat within that distance is folded into the remembered history of every LLM NPC in earshot, including ones the speaker was not addressing. Each NPC keeps at most 3 unanswered overheard lines. This makes no request by itself, but the lines can leave in a later one. Talk to an AI character lists the channels that are not overheard.

  • Saved personas can distil conversations to disk. sf_llmnpc_autosummary defaults at 1. For an NPC linked to a saved, writable persona, it sends a second request after 6 successful exchanges, 3 minutes idle or a change of conversation partner, then writes the result into a file named after that player's character.

  • The player is told none of this, and cannot opt out. An LLM NPC carries a purple * on its name, so a player who looks at one can tell it is AI-driven.

Turn it on

set sf_llmnpc        1
set sf_llmnpc_token  <your Anthropic API key>
set sf_llmnpc_model  claude-haiku-4-5
set sf_llmnpc_budget 200

  • sf_llmnpc_token belongs in the config file.

  • sf_llmnpc_model also accepts the shortnames opus and haiku.

  • sf_llmnpc_budget defaults to 0, and 0 means unlimited.

Set the caps

CvarDefaultWhat it bounds
sf_llmnpc_budget0Requests per map. 0 is unlimited. Clamped to 1,000,000
sf_llmnpc_maxtokens160Output tokens per reply, between 16 and 1024
sf_llmnpc_maxchars130Reply length in characters, between 20 and 149
sf_llmnpc_history12Remembered turns per NPC, up to 12
sf_llmnpc_cooldown3Seconds a player must wait between triggering a reply

The budget is the one that protects your costs.

The others shape a reply's size. It resets at each map change, and the automatic summaries count against it too. At most three LLM NPCs can be set.

These decide how far an NPC's attention reaches, which is a privacy setting as much as a play one:

CvarDefaultEffect
sf_llmnpc_range400Maximum distance in units at which a player can trigger a reply
sf_llmnpc_overhear300Distance within which chat is silently folded into cast NPCs' memory. 0 turns it off
sf_llmnpc_crosshair1An ordinary chat line routes to whichever LLM NPC is under your crosshair
sf_llmnpc_delay4Seconds between the player speaking and the NPC answering

sf_llmnpc_overhear 0 is the single change that most reduces what leaves your server, and it costs only ambient awareness. NPCs still answer anyone who speaks to them directly.

The memory files on disk

Personas and their memories live under llm/ in your server's game directory:

llm/llm_prompt.txt              the base system prompt sent with every request
llm/<persona>/persona.cfg       the NPC's own detail, instructions and general memory
llm/<persona>/<character>.cfg   one file per remembered player character

The character filename is lower-case, with each non-letter or digit replaced by _.

These files are player-derived data on your disk, so whatever policy you have about player data covers them.

A live cast keeps up to 4 loaded character memories in memory.

They are not covered by the database backup, so back the llm/ folder up yourself.

Things to note

  • Without libcurl on Linux, the NPCs are mute.