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
- Install Fabric for Minecraft 1.21.8.
- Download the mod
.jar file and place it into the mods/ folder.
- Launch the server or client. A default configuration file will be generated at
config/aichat.json.
- Edit
config/aichat.json and fill in your apiKey and (optionally) apiUrl. Save the file.
- 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.) |
