Little Whale AI

A lightweight, fully asynchronous Fabric mod that brings a friendly AI player named Little Whale into your Minecraft server. Powered by any OpenAI-compatible API, it can chat with players in private or public, understand context, and speak their language.

✨ Features

• 3 Chat Modes – Switch between private, public, or mixed mode:
  • Private (mode 1): Players use @ai <message> to talk to the AI. Only the sender sees the reply.
  • Public (mode 2): Every public chat message is treated as conversation with the AI. The AI replies publicly to everyone. Context is globally shared.
  • Mixed (mode 3): @ai triggers private conversation, while normal chat triggers public AI replies. Private and public contexts are kept separate.
• Player-aware AI – In public/mixed modes, the AI sees who said what via [PlayerName]: message format. It can address players by name naturally.
• Multilingual – The AI automatically replies in the same language the player used (Chinese, English, etc.).
• Plain Text Only – The AI is instructed never to use Markdown, code blocks, or special formatting, keeping output clean for the in-game chat.
• Safe & Non‑blocking – All HTTP requests run on background threads; the server main thread is never blocked.
• Context Management – Auto-clears conversation history after a configurable interval or manually via commands.
• Fully Configurable – Change the API endpoint, model, temperature, system prompt, prefix, and more through config/aichat.json.
• Admin Commands – Powerful /aichat commands to clear contexts, reload config, and view status.

📦 Installation

1. Install Fabric for Minecraft 1.21.8.
2. Download the mod .jar file and place it into the mods/ folder.
3. Launch the server or client. A default configuration file will be generated at config/aichat.json.
4. Edit config/aichat.json and fill in your apiKey and (optionally) apiUrl. Save the file.
5. Run /aichat reload (requires OP) or restart the server.

⚙️ Configuration (config/aichat.json)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| apiUrl | String | https://open.bigmodel.cn/api/paas/v4/chat/completions | API endpoint (OpenAI-compatible) |
| apiKey | String | "" | Your API key |
| systemPrompt | String | (multilingual, anti-prefix, plain‑text prompt) | System prompt that defines AI behavior |
| modelName | String | "general" | Model name to send to the API |
| temperature | Double | 0.7 | Creativity of responses (0.0–2.0) |
| autoClearContext | Boolean | true | Enable automatic context clearing |
| contextExpireSeconds | Integer | 300 | Seconds between auto‑clears |
| prefix | String | "<LittleWhale> " | Prefix added to every AI reply (supports color codes) |
| mode | Integer | 2 | Chat mode: 1 = private, 2 = public, 3 = mixed |

🎮 Usage

Chat Triggers

• Private / Mixed: Start your message with @ai. Example: @ai How do I craft a furnace?
• Clear private context: @ai clear (works in private/mixed mode)
• Public mode: Just talk in chat – every message triggers a public AI reply.

Admin Commands (requires OP, permission level 2)

| Command | Description |
|---------|-------------|
| /aichat clear | Clear your own private context (mode 1/3) |
| /aichat clear <player> | Clear the private context of a specific player |
| /aichat clearglobal | Clear the global public conversation context |
| /aichat clearall | Clear all contexts (private + global) |
| /aichat reload | Reload the configuration without restarting |
| /aichat info | Display current settings (API, model, mode, etc.) |