Artificial Intelligence

Asteroid can let fake players hold real conversations in chat, with your real players and with each other, through AI language models accessed via OpenRouter.

This is optional and off by default. It is the one feature that needs an external account and an API key.

ai:
  enabled: false
  apiKey: "api-key-here"

Setup

1. Create an account at https://openrouter.ai/.

2. Go to https://openrouter.ai/settings/keys and click Create API Key.

3. Paste the key into ai.apiKey.

4. Set ai.enabled to true and reload.

OpenRouter offers both free and paid models. Free models are good enough for most servers.

Chat delivery

ai:
  chat:
    way: "normal"
    broadcast_format: "{playerDisplayName}: {message}"

Setting	What it does
chat.way	normal sends messages through the regular chat system. broadcast sends them as broadcasts instead, which helps if a chat plugin blocks or reformats the fake's messages.
chat.broadcast_format	The format used when way is broadcast. Supports PlaceholderAPI. Built-in: {playerName}, {playerDisplayName}, {message}.

Player-to-AI conversations

Lets real players talk to fake players by chatting near them.

ai:
  basic:
    delay: "{random[2,5]}"
    answer_in_same_world: false
    playerToAI:
      enabled: true
      response_chance: 5

Setting	What it does
basic.delay	Seconds the AI waits before replying, to simulate typing.
basic.answer_in_same_world	If true, fakes only reply to players in the same world.
playerToAI.enabled	Turns player-to-AI conversations on or off.
playerToAI.response_chance	Percent chance a fake replies to any given real chat message. Low values make fakes seem busy and less suspicious.

AI-to-AI conversations (beta)

Fake players can start conversations with each other, creating background chatter.

ai:
  basic:
    AItoAI:
      enabled: false
      chance: 20
      response_chance: 70
      initiation: "Initiate a brief Minecraft conversation with {selectedTarget}..."

Setting	What it does
AItoAI.enabled	Turns fake-to-fake conversations on or off.
AItoAI.chance	Percent chance a fake starts talking to another fake.
AItoAI.response_chance	Percent chance the other fake replies.
AItoAI.initiation	The prompt used to start the conversation. {selectedTarget} is the other player's name.

You can also start an AI conversation on a timer using the {initAIConv} scheduler function.

Advanced behavior

The ai.advanced section shapes how the AI writes. Most servers can leave these at their defaults.

The system prompt

advanced.rule is the core instruction sent to the model. It defines the personality and the strict rules that keep replies looking like a real player: short, lowercase, casual, and never revealing that it is an AI. Placeholders inside it: {listener} (the fake's name), {sender} (the real player), and {personality}, {speaking_style}, {description} from the AI config files.

Timeouts and length

Setting	What it does
timeouts.receiver	Cooldown before a fake can be talked to again after a conversation.
timeouts.sender	Same cooldown, for the fake that started the conversation.
timeouts.conversation	If nobody speaks for this long, the conversation ends.
addRuleReminder and reminder	Periodically re-send the rules during long chats to keep replies in character.
maxResponses	The conversation ends after this many AI replies.

Safety filter

safeguards.stop_on_breach stops a conversation immediately if a reply contains banned content, like admitting it is an AI. safeguards.conditions is a list of regex patterns that trigger this.

Text cleanup

Setting	What it does
nameThreshold	How closely an AI-mentioned name must match a real name to count. 0.0 matches anything, 1.0 is exact only, 0.5 catches typos.
removeNonASCII	Strips emojis and non-English characters. Recommended on.
forceNoPunctuation	Removes punctuation so messages look more like player chat.
forceOnlySmallLetters	Converts replies to lowercase.
closeOnNewPlayerMentioned	Ends the conversation if the AI mentions a different player.

Model settings

advanced:
  openrouter:
    referer: "asteroid"
    ai_model: "deepseek/deepseek-r1-0528:free"
    responseType: "temperature"
    frequencyPenalty: 2.0
    presencePenalty: 1.5
    temperature: 0.2
    topp: 0.15

Setting	What it does
referer	The HTTP referer header sent to OpenRouter. Can be anything.
ai_model	Which model to use. Browse options at https://openrouter.ai/models. Free option: deepseek/deepseek-r1-0528:free.
responseType	temperature controls randomness directly. topp uses nucleus sampling. Most people use temperature.
frequencyPenalty	Higher reduces repeated words. Range -2.0 to 2.0.
presencePenalty	Higher encourages topic changes. Range -2.0 to 2.0.
temperature	0.0 is robotic, 1.0 balanced, 2.0 very random. 0.2 keeps replies focused.
topp	Only used when responseType is topp. Lower is more focused.