ServerChan
ServerChan 是一款友好的、基于 AI 的 Minecraft 服务器助手。它会监听聊天内容,响应游戏内事件,并在获得授权时执行命令。无论你是运行温馨的生存服还是繁忙的公共服,ServerChan 都能让对话保持活跃,而不会向玩家发送垃圾信息。
功能
- AI 聊天集成 - 使用兼容 OpenAI 的 API(OpenAI、Azure、本地大语言模型等)来驱动智能对话
- 智能回复系统 - 可选的意图检测器可决定何时由 AI 进行回复,避免垃圾信息
- 游戏事件感知 - 对玩家加入/离开、死亡及其他服务器事件做出反应
- 命令执行 - AI 可通过函数调用执行 Minecraft 命令(带有权限控制)
- 多加载器支持 - 适用于 Fabric、Forge、NeoForge 和 Spigot/Paper
- 多版本支持 - 兼容 Minecraft 1.12 - 1.21
- 完全可配置 - 自定义提示词、模型、回复行为等
- 国际化 - 内置 i18n 支持(英语、中文、日语)
演示
加载器兼容性矩阵
| Version |
Java |
Fabric |
Forge |
NeoForge |
Spigot/Paper |
| 1.12.x |
8 |
— |
❌ |
— |
✅ |
| 1.13.x |
8 |
— |
❌ |
— |
✅ |
| 1.14.x |
8 |
✅ |
❌ |
— |
✅ |
| 1.15.x |
8 |
✅ |
❌ |
— |
✅ |
| 1.16.x |
8 |
✅ |
✅ |
— |
✅ |
| 1.17.x |
16 |
✅ |
✅ |
— |
✅ |
| 1.18.x |
17 |
✅ |
✅ |
— |
✅ |
| 1.19.x |
17 |
✅ |
✅ |
— |
✅ |
| 1.20.x |
21 |
✅ |
✅ |
✅ |
✅ |
| 1.21.x |
21 |
✅ |
✅ |
✅ |
✅ |
— 表示该版本不存在此加载器(Fabric 从 1.14 开始,NeoForge 从 1.20 开始)。
安装
只需五个步骤,即可让你的服务器拥有爱聊天的伙伴:
- 从 Modrinth 或 CurseForge 下载与你的加载器匹配的 jar 文件
- 将其放入
mods/ 文件夹中(Spigot/Paper 则为 plugins/)
- 启动一次服务器以生成配置文件
- 添加你的 API 密钥并进行任何你想要的调整(请参阅 配置)
- 重启或执行
/reload 并开始聊天
配置
配置文件位于:
- Fabric/Forge/NeoForge:
config/serverchan.yaml
- Spigot:
plugins/ServerChan/config.yml
必填设置
| Option |
Description |
openaiApiKey |
你的 OpenAI API 密钥(或兼容提供商) |
openaiBaseUrl |
API 基础 URL(默认值:https://api.openai.com/v1)重要:必须包含 /v1 路径 |
可选设置
| Option |
Default |
Description |
model |
gpt-5.1 |
用于回复的模型 |
temperature |
1.0 |
回复随机性(0.0 - 2.0) |
contextSize |
20 |
保留在上下文中的消息数量 |
botColor |
b |
机器人聊天的 Minecraft 颜色代码 |
timeZone |
UTC |
消息时间戳的时区 |
locale |
en |
机器人消息的语言 |
意图检测器设置
意图检测器使用更小/更快的模型来决定 AI 是否应该回复。
| Option |
Default |
Description |
useIntentionChecker |
true |
启用智能回复过滤 |
intentionCheckerModel |
gpt-4o-mini |
用于意图检测的模型(个人推荐:通过 Cerebras 使用的 qwen3-235b-a22b-2507) |
responseProbabilityThreshold |
0.5 |
触发回复的最低概率 |
useFastPathIntentionChecker |
false |
提前开始生成回复 |
intentionCheckerApiKey |
(空) |
单独的 API 密钥(如果为空则使用主密钥) |
intentionCheckerBaseUrl |
(空) |
单独的基础 URL(如果为空则使用主 URL)。如果设置,必须包含 /v1 路径 |
事件设置
| Option |
Default |
Description |
enableGameEvents |
true |
对游戏事件做出反应 |
enableJoinLeaveEvents |
true |
对玩家加入/离开做出反应 |
enableDeathEvents |
true |
对玩家死亡做出反应 |
权限设置
| Option |
Default |
Description |
inheritCmdSourcePermission |
true |
AI 在执行命令时继承触发玩家的权限 |
自定义提示词
你可以自定义系统提示词,以匹配你服务器的风格:
intentionCheckingSystemMessage - 控制 AI 决定何时响应
responseGenerationSystemMessage - 控制 AI 的性格和行为
示例提示词
示例提示词文件位于 example/ 文件夹中,可帮助你快速上手。例如,example/OnlyMyRedstone-system-prompt.txt 包含了 OnlyMyRedstone 社区服务器使用的完整响应生成配置,而 example/OnlyMyRedstone-intention-checking.txt 展示了该服务器如何通过意图检查来限制响应频率。欢迎复制并修改这些文件以适应你自己的服务器——它们旨在供你自由调整使用。
命令
所有命令都需要操作者权限(等级 4)。
| 命令 |
描述 |
/serverchan reload |
重新加载配置 |
/serverchan reset |
清除消息上下文/记忆 |
/serverchan kill |
重置 OpenAI 客户端连接 |
/serverchan disable |
暂停 ServerChan 响应(不处理任何消息) |
/serverchan enable |
恢复 ServerChan 响应 |
工作原理
- 玩家在聊天中发送消息
- 意图检查器(如果启用)评估是否需要响应
- 如果需要响应,主模型生成回复
- AI 可选择通过函数调用执行命令
- 响应广播给所有玩家
AI 会保持对话上下文,并能在配置的上下文大小内引用之前的消息。
要求
- Minecraft Server 1.12 - 1.21(参见 兼容性矩阵)
- 以下加载器之一:Fabric、Forge、NeoForge 或 Spigot/Paper(可用性因版本而异)
- OpenAI API 密钥(或兼容提供商,如 Azure OpenAI、Ollama 等)
从源代码构建
# 克隆仓库
git clone https://github.com/himekifee/ServerChan.git
cd ServerChan
# 为特定 Minecraft 版本构建
./gradlew build -PmcVer=1.21
# 构建合并 jar(所有加载器打包在一起)
./gradlew build mergeJars -PmcVer=1.21
构建好的 jar 文件将位于 build/libs/ 目录中(合并 jar 则位于 build/forgix/)。
开发测试
对于本地开发,提供了一个测试脚本,它可以构建模组并启动实际的 Minecraft 服务器以验证其正确加载:
# 在所有平台上构建并测试(需要 Docker)
./dev-test.sh 1.21
# 仅构建,跳过服务器测试
./dev-test.sh --build-only 1.21
# 仅测试特定平台
./dev-test.sh --fabric 1.21
./dev-test.sh --forge 1.21
./dev-test.sh --neoforge 1.21
./dev-test.sh --paper 1.21
该脚本需要 Docker 才能运行服务器测试。
贡献
欢迎贡献!请随时提交问题和拉取请求;我们很乐意了解你是如何使用 ServerChan 的。
- Fork 仓库
- 创建功能分支 (
git checkout -b feature/amazing-feature)
- 提交更改 (
git commit -m 'Add amazing feature')
- 推送到分支 (
git push origin feature/amazing-feature)
- 打开 Pull Request
Discord
加入我们的 Discord 服务器,与社区交流、获取帮助,或分享你的 ServerChan 设置!
许可证
本项目遵循 GNU General Public License v3.0 许可协议 — 详情请参阅 LICENSE 文件。
致谢
Cerebras
本模组并非由 Cerebras 赞助,但我使用他们的推理 API 进行 CI 测试以及我自己服务器的意图检查模型——速度极快!在 20 条消息的上下文中,意图检查可在约 1 秒内完成,完整响应则在大约 2-5 秒内返回。与其他通常需要 20 多秒才能回复的大语言模型提供商相比,这几乎是即时的,因此 Cerebras 非常适合此类实时聊天应用。如果 Cerebras 团队有兴趣赞助 API 额度或提供其他形式的支持,欢迎 提交问题 ?
ServerChan
ServerChan is a friendly, AI-powered helper for Minecraft servers. It listens to chat, reacts to in-game events, and can even carry out commands when you give it permission. Whether you run a cozy SMP or a busy public server, ServerChan keeps conversations lively without spamming players.
Features
- AI Chat Integration - Uses OpenAI-compatible APIs (OpenAI, Azure, local LLMs, etc.) to power intelligent conversations
- Smart Response System - Optional intention checker determines when the AI should respond, avoiding spam
- Game Event Awareness - Reacts to player joins/leaves, deaths, and other server events
- Command Execution - AI can execute Minecraft commands via function calling (with permission controls)
- Multi-Loader Support - Works on Fabric, Forge, NeoForge, and Spigot/Paper
- Multi-Version Support - Compatible with Minecraft 1.12 - 1.21
- Fully Configurable - Customize prompts, models, response behavior, and more
- Internationalization - Built-in i18n support (English, Chinese, Japanese)
Demo
Loader Compatibility Matrix
| Version |
Java |
Fabric |
Forge |
NeoForge |
Spigot/Paper |
| 1.12.x |
8 |
— |
❌ |
— |
✅ |
| 1.13.x |
8 |
— |
❌ |
— |
✅ |
| 1.14.x |
8 |
✅ |
❌ |
— |
✅ |
| 1.15.x |
8 |
✅ |
❌ |
— |
✅ |
| 1.16.x |
8 |
✅ |
✅ |
— |
✅ |
| 1.17.x |
16 |
✅ |
✅ |
— |
✅ |
| 1.18.x |
17 |
✅ |
✅ |
— |
✅ |
| 1.19.x |
17 |
✅ |
✅ |
— |
✅ |
| 1.20.x |
21 |
✅ |
✅ |
✅ |
✅ |
| 1.21.x |
21 |
✅ |
✅ |
✅ |
✅ |
— means the loader didn't exist for that version (Fabric starts at 1.14, NeoForge at 1.20).
Installation
You're just five steps away from a chatty server buddy:
- Grab the jar that matches your loader from Modrinth or CurseForge
- Drop it into the
mods/ folder (or plugins/ for Spigot/Paper)
- Launch the server once so the config file appears
- Add your API key plus any tweaks you want (see Configuration)
- Restart or
/reload and start chatting
Configuration
The config file lives at:
- Fabric/Forge/NeoForge:
config/serverchan.yaml
- Spigot:
plugins/ServerChan/config.yml
Required Settings
| Option |
Description |
openaiApiKey |
Your OpenAI API key (or compatible provider) |
openaiBaseUrl |
API base URL (default: https://api.openai.com/v1) Important: Must include /v1 path |
Optional Settings
| Option |
Default |
Description |
model |
gpt-5.1 |
Model to use for responses |
temperature |
1.0 |
Response randomness (0.0 - 2.0) |
contextSize |
20 |
Number of messages to keep in context |
botColor |
b |
Minecraft color code for bot chat |
timeZone |
UTC |
Timezone for message timestamps |
locale |
en |
Language for bot messages |
Intention Checker Settings
The intention checker uses a smaller/faster model to decide if the AI should respond.
| Option |
Default |
Description |
useIntentionChecker |
true |
Enable smart response filtering |
intentionCheckerModel |
gpt-4o-mini |
Model for intention checking (personal rec: qwen3-235b-a22b-2507 via Cerebras) |
responseProbabilityThreshold |
0.5 |
Minimum probability to trigger response |
useFastPathIntentionChecker |
false |
Start response generation early |
intentionCheckerApiKey |
(empty) |
Separate API key (uses main key if empty) |
intentionCheckerBaseUrl |
(empty) |
Separate base URL (uses main URL if empty). Must include /v1 path if set |
Event Settings
| Option |
Default |
Description |
enableGameEvents |
true |
React to game events |
enableJoinLeaveEvents |
true |
React to player join/leave |
enableDeathEvents |
true |
React to player deaths |
Permission Settings
| Option |
Default |
Description |
inheritCmdSourcePermission |
true |
AI inherits triggering player's permissions for commands |
Custom Prompts
You can customize the system prompts to match the vibe of your server:
intentionCheckingSystemMessage - Controls when AI decides to respond
responseGenerationSystemMessage - Controls AI personality and behavior
Example Prompts
Sample prompt files live in the example/ folder to help you get started. For instance, example/OnlyMyRedstone-system-prompt.txt captures the full response-generation setup used on the OnlyMyRedstone community server, and example/OnlyMyRedstone-intention-checking.txt shows how that server throttles responses through intention checking. Feel free to duplicate and adapt these files for your own servers — they're meant to be remixed.
Commands
All commands require operator permissions (level 4).
| Command |
Description |
/serverchan reload |
Reload configuration |
/serverchan reset |
Clear message context/memory |
/serverchan kill |
Reset the OpenAI client connection |
/serverchan disable |
Pause ServerChan responses (no messages processed) |
/serverchan enable |
Resume ServerChan responses |
How It Works
- Player sends a message in chat
- Intention Checker (if enabled) evaluates if a response is appropriate
- If response is needed, the main model generates a reply
- The AI can optionally execute commands via function calling
- Response is broadcast to all players
The AI maintains conversation context and can reference previous messages within the configured context size.
Requirements
- Minecraft Server 1.12 - 1.21 (see compatibility matrix)
- One of: Fabric, Forge, NeoForge, or Spigot/Paper (availability varies by version)
- OpenAI API key (or compatible provider like Azure OpenAI, Ollama, etc.)
Building from Source
# Clone the repository
git clone https://github.com/himekifee/ServerChan.git
cd ServerChan
# Build for a specific Minecraft version
./gradlew build -PmcVer=1.21
# Build merged jar (all loaders in one)
./gradlew build mergeJars -PmcVer=1.21
Built jars will be in build/libs/ (or build/forgix/ for merged jars).
Development Testing
For local development, a test script is provided that builds the mod and spins up actual Minecraft servers to verify it loads correctly:
# Build and test on all platforms (requires Docker)
./dev-test.sh 1.21
# Build only, skip server tests
./dev-test.sh --build-only 1.21
# Test specific platform only
./dev-test.sh --fabric 1.21
./dev-test.sh --forge 1.21
./dev-test.sh --neoforge 1.21
./dev-test.sh --paper 1.21
The script requires Docker to run the server tests.
Contributing
Contributions are welcome! Please feel free to submit issues and pull requests; we love hearing how you're using ServerChan.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
Discord
Join our Discord server to chat with the community, get help, or share your ServerChan setup!
License
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
Acknowledgments
Cerebras
Not sponsored by Cerebras, but I use their inference API for CI testing and my own server's intention checker model — it's blazingly fast! With a context of 20 messages, intention checking finishes within ~1 second, and full responses come back in about 2-5 seconds. That's basically instant compared to other LLM providers that often need 20+ seconds to reply, making Cerebras a perfect fit for real-time chat applications like this. If anyone from Cerebras is interested in sponsoring API credits or any other form of support, feel free to open an issue ?
评论 0
登录后参与评分
还没有评论,来抢沙发吧