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

- Admin Commands – Switch between private, public, or mixed mode: - Admin Commands (mode 1): Players use `@ai <message>` to talk to the AI. Only the sender sees the reply. - Admin Commands (mode 2): Every public chat message is treated as conversation with the AI. The AI replies publicly to everyone. Context is globally shared. - Admin Commands (mode 3): `@ai` triggers private conversation, while normal chat triggers public AI replies. Private and public contexts are kept separate. - Admin Commands – In public/mixed modes, the AI sees who said what via `[PlayerName]: message` format. It can address players by name naturally. - Admin Commands – The AI automatically replies in the same language the player used (Chinese, English, etc.). - Admin Commands – The AI is instructed never to use Markdown, code blocks, or special formatting, keeping output clean for the in-game chat. - Admin Commands – All HTTP requests run on background threads; the server main thread is never blocked. - Admin Commands – Auto-clears conversation history after a configurable interval or manually via commands. - Admin Commands – 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

- Public mode: Start your message with `@ai`. Example: `@ai How do I craft a furnace?` - Public mode: `@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.) |