AI Chat Setup Guide

The AI Chat module brings your fake players to life — they hold real conversations with players and with each other, powered by an LLM you provide. This guide walks through setup from zero.

Read this first: The AI Chat module is currently in BETA. You are responsible for any LLM provider bills you incur. Set a spending limit on your provider account or API key before enabling. We cannot guarantee any specific bill amount — that depends entirely on your settings and server activity.

Quick Start

If you've used an LLM API before, the short version:

1. Pick a provider: OpenAI, Gemini, Anthropic, or local Ollama

2. Generate an API key

3. Edit plugins/HalosPlayerSpoofer/ai-chat.yml:

   • Set enabled: true

   • Set provider-type to your provider

   • Paste your API key into api-key

   • Set model-name to your provider's exact API identifier (see Step 3)

4. /halos reload or restart the server

5. Watch fake players start chatting in-game within a few minutes

If anything fails, see Troubleshooting.

Step 1: Choose a Provider

Provider	Cost	Quality	Setup difficulty
Google Gemini	Free tier available	Excellent	Easy
OpenAI	Pay-per-use	Excellent	Easy
Anthropic	Pay-per-use	Excellent	Easy
Ollama (local)	Free	Variable	Advanced

For most server owners, Gemini is the cheapest entry point because of its generous free tier. OpenAI is the most reliable and widely tested. Ollama is the only option if you want zero LLM costs, but requires you to run a local model on your own hardware.

Step 2: Get Your API Key

Generate a key from your chosen provider:

• Gemini: https://aistudio.google.com/apikey

• OpenAI: https://platform.openai.com/api-keys

• Anthropic: https://console.anthropic.com/settings/keys

• Ollama: No key needed — set base-url to your local Ollama endpoint instead

Set a spending limit immediately after generating your key. All three commercial providers let you cap monthly spend on the account or key. Do this BEFORE pasting the key into the config. If you don't, a misconfiguration could cost you hundreds of dollars before you notice.

Step 3: Configure the Module

Open plugins/HalosPlayerSpoofer/ai-chat.yml and edit the top section:

enabled: true

llm-provider:
  provider-type: GEMINI       # OPEN_AI | OLLAMA | ANTHROPIC | GEMINI
  api-key: YOUR_KEY_HERE
  model-name: gemini-2.5-flash
  base-url: none              # only used for OLLAMA

Valid model names per provider

Model names must be your provider's exact API identifier. Using marketing names like "GPT-4" or "Gemini 2.5 Flash" (with spaces and capitals) will fail with an Illegal character in path error. Use the exact lowercase, hyphen-separated identifier below.

OpenAI:

• gpt-4.1-mini — recommended for cost/quality balance

• gpt-4.1

• gpt-4o

• gpt-4o-mini

Gemini:

• gemini-2.5-flash — recommended (free tier eligible)

• gemini-2.0-flash

• gemini-1.5-flash

• gemini-1.5-pro

Anthropic:

• claude-haiku-4-5-20251001

• claude-sonnet-4-6

• claude-opus-4-6

Ollama:

• Whatever model name you have installed locally (e.g. llama3.2, mistral)

• Set base-url to your Ollama endpoint, e.g. http://localhost:11434

Step 4: Set the Activity Level

These three settings control how often AI chat fires — which directly controls your LLM costs:

chatter-chance: 0.75      # 75% of new fake players become chatters
max-chatters: 10          # cap on simultaneous chatting fakes
min-real-players: 1       # don't run AI chat until N real players are online

Setting	Effect on cost	Recommended starting value
Higher chatter-chance	More fakes will chat	Start at 0.5
Higher max-chatters	More LLM calls in parallel	Start at 5, raise once stable
Higher min-real-players	Less time chat is active	1-3 for cost control

Cost-control tip: Set min-real-players: 3 or higher to prevent AI chat from running on an empty server. There's no point spending API tokens when no real players are watching.

Step 5: Test It

1. Save the config

2. In-game, run /halos reload or restart the server

3. Have at least min-real-players real players online

4. Wait for fake players to spawn (depends on your Fluctuation settings)

5. Watch chat — you should see fakes talking within a minute or two

If nothing shows up after ~3 minutes, jump to Troubleshooting.

Personalities

Halos ships with 6 built-in personalities. Each fake player that becomes a chatter is randomly assigned one:

Personality	Vibe
Eli	Dry humor, slightly grumpy, gives practical tips
Casey	Friendly, witty, asks occasional follow-up questions
Nia	Warm, mentions her pets casually
Milo	Lowercase only, chill, sleepy vibe
Bex	Enthusiastic builder, lots of punctuation!!!
Toby	Friendly, occasional small typos

You can edit any of them — or add new ones — under prompt-config.personalities in ai-chat.yml. Each personality has two prompts:

• decision-prompt-template — used when the agent is deciding whether to respond to a player's message

• idle-prompt-template — used when the agent decides to start a random chat during a quiet period

Adding a Custom Personality

Copy an existing personality block and rename the key. Example — adding a new personality called kira:

prompt-config:
  personalities:
    kira:
      decision-prompt-template: |
        You are chatting in a public Minecraft server as '{agentName}'.
        Persona: Kira — competitive PvPer, brags about kills, friendly rivalry.
        Style rules:
        - short, confident replies.
        - occasional trash-talk in a friendly way.
        Behavior rules:
        - Avoid echo-chamber behavior: do NOT mindlessly agree, mirror, or repeat.
        - If message mentions your name, respond with high likelihood.
        - Output MUST be strict JSON only:
          {"respond":true|false,"recipient":"<optional username>","message":"<chat message if respond>"}
        - If respond=false, message must be "".
        - recipient should usually be the sender '{fromUser}' if replying.
      idle-prompt-template: |
        You are chatting in a public Minecraft server as '{agentName}'.
        Persona: Kira — competitive PvPer.
        We are in a lull. Write one short PvP-related chat line.
        Output MUST be strict JSON only:
          {"respond":true,"recipient":"","message":"..."}

Prompt rules: Both templates MUST end with the JSON output instruction. Halos parses the agent's response as strict JSON — free-form text will fail.

Cost Management

This is the most-asked-about topic. Here's what actually drives your bill:

Bigger cost drivers:

• High chatter-chance (more fakes are chatting)

• High max-chatters (more parallel API calls)

• High max-context-events (more tokens per call)

• Low min-real-players (chat running with no audience)

• Low quiet-period-for-idle-ms (more idle chats happening)

Smaller cost drivers (worth tuning second):

• Cheaper model (gpt-4o-mini, gemini-2.5-flash, claude-haiku-4-5)

• Higher cooldown settings (less frequent messages)

• Lower p-idle-chatter (less random chatting when no players)

Sample monthly cost estimates

Profile	Setup	Estimated monthly cost
Hobby server	5 fakes, gpt-4o-mini, 8h/day active	~$3-8/mo
Mid-size server	10 fakes, gpt-4o-mini, 24/7	~$15-30/mo
Large network	25+ fakes, gpt-4.1, 24/7	$50+/mo

These are rough estimates. Always set a hard spending limit with your provider before enabling.

Advanced Tuning

The agent-config section is for fine-tuning behavior. Defaults work for most servers. Touch these only if you have a specific reason.

Cooldowns & Timing

Setting	What it does	Default
engagement-ttl-ms	How long an agent stays engaged with a player after being mentioned	180000 (3 min)
global-speak-cooldown-ms	Cooldown between chats by any agent	3000
per-recipient-cooldown-ms	Per-agent and per-engagement cooldown between chats	3000
quiet-period-for-idle-ms	Quiet time before an agent might initiate idle chat	18000 (18s)
min-idle-speak-gap-ms	Minimum delay between random idle messages	35000 (35s)
min-response-delay-ms	Minimum delay before agent responds to a player	5000 (5s)
max-response-delay-ms	Maximum delay before agent responds	10000 (10s)
tick-interval-ms	How often agents are evaluated	5000
echo-suppress-window-ms	Window to ignore duplicate chat messages	25000

Response Probabilities

Setting	What it does	Default
p-reply-when-mentioned	Probability of replying when mentioned by name	0.85
p-reply-when-engaged	Probability of replying when in active engagement	0.65
p-reply-random-when-idle	Probability of replying to a random chat when idle	0.08
p-idle-chatter	Probability an idle agent submits a random chat per tick	0.05

Multi-Agent Coordination

Setting	What it does	Default
p-ignore-other-agents-base	Probability of ignoring another agent's chat when idle	0.75
p-ignore-other-agents-if-busy	Probability of ignoring other agents when engaged with a player	0.85
p-bypass-ignore-if-mentioned	Multiplier reducing ignore probability if mentioned	0.35
global-throttle-multiplier	Multiplier reducing reply probability when many agents are active	0.35

Focus System

Setting	What it does	Default
focus-ttl-ms	How long an agent focuses on a specific player	90000 (90s)
focus-boost-multiplier	Reply probability multiplier when sender is the focused player	5.0
focus-suppress-multiplier	Reply probability multiplier from others when agent has a focused user	0.4
focus-mention-bypass-multiplier	Reduction in focus suppression if agent is mentioned	0.65

Context

Setting	What it does	Default
max-history	Max history events kept internally per agent	200
max-context-events	Max events sent to the LLM per call (lower = cheaper)	60
debug-logging	Enable verbose decision logging — useful for tuning	false

Troubleshooting

"Illegal character in path at index N"

The model-name in your config has invalid characters (usually spaces). Provider model names must be exact API identifiers, not marketing names.

• ❌ Wrong: model-name: Gemini 2.5 Flash

• ✅ Right: model-name: gemini-2.5-flash

See Step 3 for the full list of valid names per provider.

Chat isn't appearing in-game

Check in this order:

1. Is enabled: true in ai-chat.yml?

2. Are there at least min-real-players real players online?

3. Are fake players actually spawning? (Check the Fluctuation module is working first)

4. Is your API key valid? Test it directly with your provider.

5. Check latest.log for errors — search for LLMAgent or RetryUtils.

6. Set debug-logging: true under agent-config to see what each agent is deciding.

"401 Unauthorized" or "Invalid API key"

Your API key is wrong, expired, or revoked. Generate a new one with your provider and paste it into api-key.

"429 Too Many Requests" / Rate limit errors

You're hitting your provider's rate limits. Either:

• Lower max-chatters so fewer parallel calls happen

• Raise the cooldown settings (global-speak-cooldown-ms, min-idle-speak-gap-ms)

• Upgrade your provider plan to a higher rate limit tier

Bill is higher than expected

1. Lower max-chatters

2. Lower chatter-chance

3. Raise min-real-players

4. Switch to a cheaper model (gpt-4o-mini or gemini-2.5-flash)

5. Set a hard spending limit on your provider account

6. Reduce max-context-events to send less context per call

Fakes are repeating themselves or echoing real players

• Raise echo-suppress-window-ms (default 25000)

• Review your personality prompts — make sure "Avoid echo-chamber behavior" rule is present

• Lower p-reply-when-engaged so agents don't pile onto every message

Fakes are too chatty / spamming

• Lower chatter-chance

• Lower p-idle-chatter and p-reply-random-when-idle

• Raise quiet-period-for-idle-ms and min-idle-speak-gap-ms

Fakes are too quiet / never chat

• Raise chatter-chance

• Raise p-reply-when-mentioned and p-reply-when-engaged

• Lower quiet-period-for-idle-ms

• Confirm fakes are actually being spawned by Fluctuation

FAQ

Q: Will real players know they're talking to AI? A: They shouldn't if your prompts are configured well. The default prompts explicitly tell agents not to behave like assistants. Test with friends before going live.

Q: Can I use multiple LLM providers at once? A: Not currently — one provider per server.

Q: What about NSFW or rule-breaking content? A: Your LLM provider handles content filtering. OpenAI and Anthropic block most disallowed content by default. Gemini is configurable. Your prompts also influence what gets generated.

Q: My fakes are speaking in non-English languages. A: Add an explicit language rule to the global-system-prompt, e.g. "Always respond in English."

Q: Can fakes mention other fakes by name? A: Yes — they're aware of other agents and can reference them. Tune p-ignore-other-agents-base to control how often this happens.

Q: Does AI chat work on Folia? A: Yes. All AI chat operations are async and Folia-compatible.

Support

Stuck? Open a ticket in our Discord: discord.gg/halosdev

Average response time: same day to 24 hours. We read every ticket.