💬︎ ChatBuddy – The Spontaneous AI Companion 💬︎

✔ Autonomous • ✔ Clickable Support • ✔ Multi-Personality • ✔ Zero Lag • ✔ Highly Configurable

MC Versions: 1.16 – 1.21+ • NSR-AI Core: v1.4+ • API Version: v3.0-pre+
Type: NSR-AI Plugin Integration • Developer: BlackForge

🌐︎ What is ChatBuddy?

ChatBuddy is an advanced integration for the NSR-AI ecosystem. Unlike traditional AI bots that only speak when spoken to via a command, ChatBuddy lives directly inside your server's chat stream. It is a fully autonomous, highly intelligent companion that organically participates in player conversations, reacts to game events, and breaks the ice when the server goes quiet.

Note: ChatBuddy requires the base NSR-AI plugin and the NSR-AI API v3.0-pre+ to function.

🚀︎ Why Choose ChatBuddy

• True Autonomy — Players don't need to use /ai to talk to it. ChatBuddy reads the chat natively and decides when to jump into the conversation based on probability and context.
• Unbelievably Human — Powered by the ultimate Gamer Prompt, ChatBuddy uses slang, cracks jokes, and stays in character. It is programmed to act like a real player, not a robot.
• Integrated Support — Found a bug? You can report it directly on GitHub or stay in-game and just ask Buddy for the link! Simply say: "Hey Buddy, I want to report a bug, give me the link" or similar phrasing mentioning "bug" or "error." If Buddy doesn't provide the link immediately, try asking more clearly, and he will generate a bold, blue clickable link in the chat for you.
• API Cost-Saving Wave System — If multiple players join around the same time, ChatBuddy intelligently batches them into a single greeting wave, saving you significant API token costs.
• Lightweight & Thread-Safe — Built with Spigot's Async thread pools, Atomic variables, and strict memory management. It will never lag your main server thread.

🛠︎ Core Features

🧠 Intelligent Conversational Triggers

• Fuzzy Keyword Detection: If players mention specific topics (like "diamonds", "help", or "lag"), ChatBuddy's chance to respond jumps dynamically. It includes an advanced Levenshtein Distance algorithm, meaning it will perfectly detect typos like "daimonds".
• Buddy Mentions: If a player casually types "Hey Buddy", "Buddy", or "CB" in the middle of a sentence, the AI detects it via smart regex boundaries and almost guarantees a response.
• Join Delay & Cooldown: Buddy waits 10 seconds for players to settle in before greeting them, and includes a 2-minute rejoin cooldown to prevent greeting spam from players with unstable connections.
• The "Icebreaker" (Inactivity Engine): If the server chat goes completely silent for a set amount of time (e.g., 10 minutes), ChatBuddy will automatically send a message to start a new conversation.
• Message Counter Guarantee: Configure ChatBuddy to guarantee a response exactly every X messages, ensuring the AI is perfectly active for your community.

🎭 Personality & Game Awareness

• Action/Event Hooking: ChatBuddy actively watches the server. It will comment on Player Deaths (with a witty remark based on how they died) and congratulate players on Achievements.
• Contextual Memory Buffer: It seamlessly reads the last 15 messages (customizable) before it speaks, ensuring it understands inside jokes, server lore, and the current mood of the players.
• Multi-Personality Engine: Combines a core "Gamer" foundation with a randomized list of traits from the config (e.g., "friendly", "salty survivor", "excited newbie") to keep interactions fresh.

⚙️ Backend Control

• Model & Provider Overrides: Force the AI to use specific providers like OpenAI or Claude, directly in the ChatBuddy config.
• Smart API Key Routing: It automatically attempts to use the personal API key of the player who triggered the conversation. If they don't have one, it falls back to the Server's Global Key.

📜︎ Commands & Permissions

Commands

/chatbuddy reload (Alias: /cb reload) — Hot-reloads the config.yml instantly.

Permissions

chatbuddy.admin — Required to use the reload command.

# ChatBuddy: Advanced Configuration

# --- 1. Probability Settings ---
base-chance: 0.2
mention-chance: 80.0
messages-until-reply: 8
min-players: 1
cooldown-seconds: 60

# --- 2. Fuzzy Keyword Boosts ---
keyword-boosts:
  diamonds: 50.0
  help: 60.0
  lag: 70.0
  admin: 90.0
fuzzy-sensitivity: 7

# --- 3. Personalities ---
personalities:
  - "You are a casual, laid-back Minecraft veteran who loves building and hates creepers. You joke around."
  - "You are an excited newer player who thinks everything is awesome. You use slang like 'bro', 'man', 'rip'."
  - "You are a slightly sarcastic survivor who has died too many times to lava. You are friendly but witty."
  - "You are a very friendly, supportive gamer who loves helping others out. You always try to be positive and hype up your fellow players."

# --- 4. Inactivity Trigger ---
inactivity:
  enabled: true
  minutes: 10
  chance: 100.0

# --- 5. API Key & Priority Logic ---
api-priority: "AUTO"
api-provider: "AUTO"
api-model: "AUTO"
silent-key-failure: true

# --- 6. Context ---
context-window: 15
broadcast-prefix: "&8[&bAI&8] &f"

Powering your world with smarter gameplay.
Developed by BlackForge Studio