AstroChatBot Documentation

Requirements: Paper, Purpur, or Folia server running Minecraft 1.20+. Java 21+.

Default English-only setup

Three categories: home, claim, spawn. Each has keywords and a response.

enabled: true
prefix: "&7[Bot] "
default-language: en
chat-cooldown-seconds: 30  # global per-player rate-limit on triggers

categories:
  home:
    cooldown-seconds: 60
    keywords:
      - "how do i set home"
      - "how to set home"
      - "set home"
      - "/sethome"
    responses:
      en:
        - "&7You can set a home with &f/sethome <name>&7. Teleport back with &f/home <name>&7."
  claim:
    cooldown-seconds: 60
    keywords:
      - "how to claim"
      - "how do i claim"
      - "claim land"
    responses:
      en:
        - "&7Hold a golden shovel and right-click two corners to claim. Type &f/claim help&7 for more."
  spawn:
    cooldown-seconds: 30
    keywords:
      - "where is spawn"
      - "back to spawn"
      - "go to spawn"
    responses:
      en:
        - "&7Use &f/spawn&7 to teleport to spawn."

Bilingual (English + Dutch)

Detect player language via PlaceholderAPI and respond accordingly.

enabled: true
prefix: "&7[Bot] "
default-language: en
detect-language-placeholder: "%astroworld_player_lang%"

categories:
  home:
    keywords:
      - "how do i set home"
      - "hoe stel ik thuis in"
      - "set home"
      - "thuis maken"
    responses:
      en:
        - "&7Set a home with &f/sethome <name>&7."
      nl:
        - "&7Stel een thuis in met &f/sethome <naam>&7."

Server-specific rules bot

Reply to common rule questions to deflect staff load.

enabled: true
prefix: "&c[Rules] "
chat-cooldown-seconds: 60

categories:
  pvp-rules:
    keywords:
      - "is pvp allowed"
      - "pvp rules"
      - "can i pvp here"
    responses:
      en:
        - "&7PvP is enabled in &c/warp arena&7 only. Outside arena, PvP is disabled."
  griefing:
    keywords:
      - "griefing rules"
      - "can i grief"
      - "is griefing allowed"
    responses:
      en:
        - "&7Griefing is &cnever allowed&7. Report to /helpop or open a ticket on Discord."

Randomized responses (anti-stale)

Multiple response variants per keyword to avoid feeling robotic.

enabled: true
randomize-responses: true

categories:
  spawn:
    keywords:
      - "where is spawn"
    responses:
      en:
        - "&7Use &f/spawn&7 to teleport to spawn."
        - "&7Type &f/spawn&7 and you will be there."
        - "&7You can run &f/spawn&7 anytime to head to spawn."

Config location

Reduce 'how do I claim' staff requests

Scenario: Your GriefPrevention claim system is intuitive but new players still ask in chat 5x per hour.

1. Set up the 'claim' category with keywords like 'how to claim', 'claim land', 'how do i claim'.
2. Configure cooldown to 120s so the bot does not respond more than once every 2 minutes (avoid spam).
3. Include a link to your wiki: '&7Hold a gold shovel, right-click 2 corners. Full guide: &fastroworldmc.com/wiki/claims'.
4. Track impact: count 'how to claim' questions in chat logs before/after deploying.

Self-service rule clarifications

Scenario: Players keep asking 'is X allowed' and tying up staff. You want the bot to answer the common ones.

1. Create categories for the top 10 rule questions: pvp, griefing, swearing, advertising, alts, hacks, x-ray, IRL trading, doxxing, NSFW.
2. Each category has its keywords and a clear answer.
3. Bot replies inline in chat so other players also see the rule clarification.

Multi-language community support

Scenario: 30% of your player base speaks Dutch. They are not always answered in time.

1. Set up keywords in both English and Dutch in the same category.
2. Provide responses in both 'en' and 'nl' under each category.
3. Set detect-language-placeholder to a PAPI placeholder that resolves to 'en' or 'nl' (e.g., your custom Astroworld language preference plugin).
4. Bot replies in the player's preferred language.

New-player onboarding sequence

Scenario: Walk a new player through the first hour with chat tips.

1. Configure first-join-tip category that triggers on any join from a player with 0 playtime.
2. Bot sends 3 tips spaced 30 seconds apart: 'Set a home', 'Claim your land', 'Join the Discord'.
3. Pair with AstroJoinLeave first-join-title for a strong opening sequence.

Reduce 'where is the shop' / 'where is x' questions

Scenario: Players ask for warp directions constantly.

1. Create one category per common warp: shop, mine, pvp-arena, hub, spawn, nether.
2. Keywords include both 'where is X' and 'how to get to X'.
3. Responses give the exact command and a one-line context.

default

Regular player — bot responds to their messages

# No explicit nodes needed for the default group

vip

Same as default, plus vip-only categories

/lp group vip permission set astrochatbot.category.vip true

staff

Bot ignores their chat (ignore-staff:true) and they can /chatbot toggle / reload

/lp group staff permission set astrochatbot.bypass true
/lp group staff permission set astrochatbot.admin true
/lp group staff permission set astrochatbot.toggle true
/lp group staff permission set astrochatbot.reload true

Tip: Use LuckPerms to manage permissions per player or group.

PlaceholderAPI

Responses can include any PAPI placeholder. %player%, %server_name%, %online%, %custom_papi% all work. Language detection placeholder must be a registered PAPI extension.

LuckPerms

Use permissions to bypass the bot for staff (astrochatbot.bypass), prevent staff from triggering the bot when typing in chat. Also lets you scope categories per group (vip-only categories).

DiscordSRV

Bot responses fire in Minecraft chat and DiscordSRV picks them up like any chat message. To avoid duplicating, set 'discord-sync: false' in AstroChatBot config to skip bridge sending.

EssentialsX

Bot responses are normal chat messages. They go through your chat formatter and Essentials chat rules. Make sure the bot's username (default 'Bot' or your custom name) is whitelisted in Essentials anti-swear / anti-caps filters.

AstroSimpleAFK

Bot does not respond when the asking player is AFK (you can disable this filter with 'respond-to-afk: true'). Avoids triggering on stale chat from idle players.

Bot does not respond to any keywords

Cause: Plugin disabled, keyword matching is case-sensitive, or chat event being cancelled by another plugin.

Fix:

• Check 'enabled: true' in config.yml.
• Keywords are case-insensitive by default but exact-string. 'set home' will match 'set home' but not 'sethome'. Use multiple variants.
• Check if EssentialsX, Vault, or a chat-format plugin is cancelling AsyncPlayerChatEvent. Disable chat plugins one by one to isolate.
• Run /chatbot debug — bot will log every chat message and which category it matched.

Bot responds multiple times in a row to the same message

Cause: Two keywords in two different categories both matched the same message.

Fix:

• Set 'multi-match: false' to stop after the first category matches.
• Make keywords more specific to avoid overlap.
• Or accept multi-match if you want compound answers.

Cooldown not being respected — bot replies on every message

Cause: Cooldown is per-player-per-category but chat is from different players, or 'chat-cooldown-seconds' is set to 0.

Fix:

• Cooldown applies per (player, category). Different players can trigger the same category simultaneously.
• Set a higher 'chat-cooldown-seconds' for global per-player rate limit.
• Set category-specific cooldown-seconds for fine control.

Wrong language response in mixed-language servers

Cause: Language detection placeholder not returning a valid language code or missing language in responses.

Fix:

• Run /papi parse <player> %your_lang_placeholder% to check what value comes back.
• Ensure the language code exactly matches a key in responses (en, nl, de, es).
• If detection fails, falls back to default-language.

Bot responds to its own messages (infinite loop)

Cause: Another plugin is replaying chat messages, or the bot prefix matches another bot's keyword.

Fix:

• Bot ignores its own messages by default via the 'bot-message-tag' metadata.
• Ensure 'bot-prefix' is unique and not in any keyword list.
• Disable any chat-replay plugin during testing.

Does this use AI / GPT for responses?

No. AstroChatBot is rule-based: keyword matching with predefined responses. No external API calls, no per-message cost, no latency. We considered LLM integration but rejected it: too slow for chat, too costly for free hosting, and unreliable for rules questions.

Can I add my own keywords without editing config.yml on the server?

Not directly in this version. Future versions will support /chatbot add-keyword <category> <keyword> for in-game editing with astrochatbot.admin permission.

Does the bot work with custom chat plugins like venturechat?

Yes, as long as the chat plugin fires AsyncPlayerChatEvent (most do). If using a fully custom chat plugin that emits its own events, configure that plugin to also fire the standard event, or hook AstroChatBot directly to your custom event.

How many keywords can I have?

Tested with 200+ keywords across 30 categories. Performance is fine because matching is O(N) with N being the number of keywords. For 1000+ keywords, consider partitioning by chat channel or world.

Can the bot trigger on commands like '/help home' too?

Yes. Set 'listen-to-commands: true' in config.yml. The bot will then also see /commands as chat messages.

How does the language detection work?

We read a configurable PlaceholderAPI placeholder per player on each chat event. Returns 'en', 'nl', 'de', etc. Falls back to default-language if the placeholder is empty or returns an unknown language.

Can multiple players trigger the same category in the same minute?

Yes — cooldown is per-(player, category). Different players reset independently. If you want a global rate limit, set 'global-cooldown-seconds: 30'.

Will the bot respond to private messages (/msg)?

Not by default. AstroChatBot listens to public chat only. To respond to private messages, set 'listen-to-private: true' and the bot will trigger on /msg too.

What if a player asks 'how do i set home' AND 'how do i claim' in the same message?

With 'multi-match: false' (default), only the first category that matches fires. With 'multi-match: true', both categories trigger and the bot sends two responses.

Can responses include hex colors or gradients?

Yes. Standard Bukkit hex (&#FF1F00) works. MiniMessage gradients work on Paper 1.18+. The bot does NOT support clickable JSON components in 1.0 — coming in 2.0.

Does the bot trigger on staff chat too?

By default yes. Set 'ignore-staff: true' and add astrochatbot.bypass permission to staff group to silence the bot in staff-only chat.

How do I disable the bot temporarily without uninstalling?

Run /chatbot toggle. Bot stops responding until you run /chatbot toggle again. Useful during PvP events or scheduled maintenance.

Will it work on offline-mode servers?

Yes. The bot uses standard Bukkit player APIs that work in offline mode.

v1.0.02026-05-13

• Initial public release
• Keyword-matching chat bot
• Per-category cooldowns
• Multi-language responses with PlaceholderAPI detection
• /chatbot toggle / reload / debug commands
• astrochatbot.bypass and admin permissions
• Multi-match optional, randomized responses
• Vanish detection (does not respond to vanished players)