GamesAI Plugin/Mod QQ Group: 849544707 — Join us to discuss issues, share feedback, and exchange prompt, skills, tools configurations!
Welcome to GamesAI for Fabric! This mod brings AI assistants into Minecraft — ask questions, manage data, and configure AI backends right from the game.
Due to the author's limited energy, we will not support versions below 1.21 or non-Fabric loaders.
Table of Contents (click to expand)
Installation
Prerequisites
- Minecraft 1.21+ (or Fabric-compatible version — see Version Compatibility)
- Fabric Loader ≥ 0.16.10
- Fabric API (latest for your MC version)
- Java 21 or newer
Steps
- Download the latest
.jar from Modrinth
- Place it in your
.minecraft/mods/ folder
- Launch the game with Fabric Loader
- A default config file is generated at
config/games_ai/config.json on first run
- Edit the config with your API credentials, then reload with
/gamesai reload
Alternatively, download the .jar from GitHub Releases and place it in your .minecraft/mods/ folder the same way.
Usage
Ask Commands
| Command |
Description |
/ask <content> |
Ask AI using the default model |
/ask -m <model> <content> |
Ask AI using a specific model profile |
/ask -n <content> |
Ask AI without conversation history |
/ask -n -m <model> <content> |
Specific model, no history |
Only short flags (-m, -n) are supported. Long forms (--model, --no-history) are not available to avoid duplication in Minecraft's built-in command suggestions.
Management Commands
General
| Command |
Permission |
Description |
/gamesai help |
Everyone |
Show context-sensitive help |
/gamesai reload |
Owner (Lv4) |
Reload config, tools, and translations |
History
| Command |
Permission |
Description |
/gamesai history clear |
Everyone |
Clear your own conversation history |
/gamesai history clearall |
Owner (Lv4) |
Clear all players' history |
Config
| Command |
Permission |
Description |
/gamesai config lang <lang> |
Owner (Lv4) |
Set server language (en_us / zh_cn) |
/gamesai config defaultAi <aiID> |
Owner (Lv4) |
Set default AI model |
/gamesai config maxHistory <value> |
Owner (Lv4) |
Set max conversation rounds (≥ 1) |
Data
| 指令 |
权限 |
描述 |
/gamesai data write <key> <value> |
Owner (Lv4) |
将数据写入数据库(覆盖现有值) |
/gamesai data add <key> <value> |
Owner (Lv4) |
向数据库追加数据 |
/gamesai data del <key> |
Owner (Lv4) |
从数据库中删除一条记录 |
/gamesai data read <key> |
Owner (Lv4) |
通过键读取值 |
/gamesai data list |
Owner (Lv4) |
列出所有键值对 |
/gamesai data list keys |
Owner (Lv4) |
列出所有键 |
客户端指令
| 指令 |
描述 |
/c-ask <content> |
从客户端侧向 AI 提问(无需服务器命令权限) |
/c-ask -m <model> <content> |
使用指定模型在客户端侧提问 |
/c-ask -n <content> |
无历史记录地在客户端侧提问 |
/c-ask -n -m <model> <content> |
无历史记录、使用指定模型在客户端侧提问 |
游戏内配置界面
按 F6(默认)打开可视化配置界面
- 常规设置 — 使用滑块、文本字段和循环按钮编辑
prefix、max_history、lang、default_ai
- AI 配置文件 — 使用可视化编辑器添加、编辑或删除 AI 后端配置
- 更改会保存至
config.json 并立即生效
若要重新绑定配置界面的按键:选项 → 控制 → 按键绑定 → 杂项 → 打开 GamesAI 配置
配置
首次运行时,会在以下位置创建默认配置文件:
.minecraft/config/games_ai/config.json
默认结构
{
"prefix": "[GamesAI]",
"max_history": 10,
"lang": "en_us",
"all_ai": {
"example_ai": {
"prompt": "You are a helpful assistant in Minecraft.",
"ai_name": "[GamesAI]",
"base_url": "<Your Base URL>",
"ai_model": "<Your AI Model>",
"api_key": "<Your API Key>",
"extra_body": {}
}
},
"default_ai": "example_ai"
}
1. prefix
| 属性 |
值 |
| 类型 |
String |
| 默认值 |
[GamesAI] |
用作回复前缀的插件名称。可包含 Minecraft 格式化代码。
2. max_history
每个玩家在每个模型上保留的最大对话轮数。设置为 0 以禁用历史记录。历史记录存储在内存中,并在服务器重启时清除。
3. lang
| 属性 |
值 |
| 类型 |
String |
| 默认值 |
en_us |
| 可选值 |
en_us, zh_cn |
服务器范围的显示语言。更改后需执行 /gamesai reload 生效。
4. all_ai
所有 AI 配置条目。每个条目是一个字典(键为内部 AI_ID):
| 字段 |
描述 |
| prompt |
此 AI 的系统提示词。使用 > filename.md 可从 config/games_ai/prompt/ 加载文件。 |
| ai_name |
聊天中显示的 AI 名称(可包含 Minecraft 格式化代码)。 |
| base_url |
API 端点 URL(例如 https://api.openai.com/v1)。 |
| ai_model |
模型名称(例如 gpt-4o、deepseek-chat)。 |
| api_key |
API 认证密钥。 |
| extra_body |
传递给 API 的其他参数(例如 DeepSeek 的 {"thinking": {"type": "enabled"}})。默认值:{}。 |
多配置文件示例
{
"all_ai": {
"gpt4o": {
"prompt": "You are a Minecraft expert.",
"ai_name": "[GPT-4o]",
"base_url": "https://api.openai.com/v1",
"ai_model": "gpt-4o",
"api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"extra_body": {}
},
"deepseek": {
"prompt": "You are a helpful Minecraft assistant.",
"ai_name": "[DeepSeek]",
"base_url": "https://api.deepseek.com",
"ai_model": "deepseek-chat",
"api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"extra_body": {}
},
"local_llama": {
"prompt": "You are a friendly Minecraft assistant.",
"ai_name": "[Llama3]",
"base_url": "http://localhost:11434/v1",
"ai_model": "llama3",
"api_key": "ollama",
"extra_body": {}
}
},
"default_ai": "gpt4o"
}
对于 Ollama / 本地模型,请将 api_key 设置为 "ollama" 作为占位符。
5. default_ai
当玩家仅使用 /ask 时使用的模型。必须是 all_ai 中的某个键。
prompt 文件引用
您可以不将长提示词嵌入 config.json,而是引用外部文件:
- 将提示词文件放置在
config/games_ai/prompt/ 中(例如 my_prompt.md)
- 在 AI 配置文件中设置
"prompt": "> my_prompt.md"
模组会在请求时自动读取文件内容。支持任何文本文件格式(.md、.txt 等)。
数据库系统
GamesAI 包含一个基于 SQLite 的公共数据库,位于 config/games_ai/database/database.db。
| 指令 |
描述 |
/gamesai data write <key> <value> |
写入键值对(覆盖现有值) |
/gamesai data add <key> <value> |
向现有键追加值(自动创建) |
/gamesai data del <key> |
删除一条记录 |
/gamesai data read <key> |
通过键读取值 |
/gamesai data list |
列出所有键值对 |
/gamesai data list keys |
列出所有键 |
AI 也可以通过内置工具(ai_read_data、ai_write_data、ai_add_data、ai_del_data)读写数据库。
AI 工具
AI 可以调用函数来与 Minecraft 和数据库进行交互。
内置工具
| 工具 |
参数 |
描述 |
get_online_players |
无 |
获取当前在线玩家列表 |
get_whitelist_name |
无 |
获取服务器白名单 |
add_to_whitelist |
player |
将玩家添加到白名单 |
remove_from_whitelist |
player |
从白名单中移除玩家 |
search_minecraft_wiki |
query |
搜索 Minecraft Wiki |
calculator |
expression |
计算数学表达式 |
item_calculator |
expression, single_limit |
使用 Minecraft 单位(组/潜影盒)计算物品数量 |
ai_read_data |
key |
读取数据库条目 |
ai_read_all_keys |
无 |
获取所有数据库键名 |
ai_read_all_data |
无 |
读取所有数据库条目 |
ai_write_data |
key, value |
写入数据库(覆盖) |
ai_add_data |
key, value |
追加数据到数据库 |
ai_del_data |
key |
删除数据库条目 |
read_skills |
skills |
读取技能文件 |
setting_timer |
duration |
等待 N 秒后继续执行 |
reload_plugin |
无 |
执行 /gamesai reload |
通过 Groovy 创建自定义工具
你可以通过编写 Groovy 脚本来扩展 AI 的功能:
- 将
.groovy 文件放置在 config/games_ai/tools/ 目录下
- 使用
@RegisterTool 注解方法:
import java.util.function.Consumer;
import io.github.pengzixuan30.gamesai.tools.GamesAIToolsRegister;
@GamesAIToolsRegister.RegisterTool(
name = "my_custom_tool",
description = "Does something useful",
parameters = """
{
"type": "object",
"properties": {
"param": {
"type": "string",
"description": "The value to process"
}
},
"required": ["param"]
}
"""
)
String myCustomTool(Consumer<String> feedback, String aiName, String param) {
feedback.accept("Executing custom tool...")
return "Result: ${param} processed"
}
工具方法的签名必须将 Consumer<String> feedback 作为第一个参数,String aiName 作为第二个参数,之后是 parameters JSON 模式中声明的任何自定义参数。
- 使用
/gamesai reload 重新加载 —— 工具会自动被发现和注册。
技能 (Skills)
技能是 Markdown 文件,用于向 AI 提供特定领域的知识和指令。AI 可以通过 read_skills 工具来读取它们。
添加技能
- 将
.md 文件放置在 config/games_ai/skills/ 目录下
- 在
config/games_ai/skills/skills.json 中进行注册:
[
{
"skills": "my_guide.md",
"summary": "A guide for building redstone machines"
}
]
- 使用
/gamesai reload 重新加载
已注册的技能会出现在 AI 的系统提示词中,以便它知道有哪些可用知识。
热重载 (Hot Reload)
GamesAI 提供了热重载机制,允许你在不重启服务器的情况下应用配置、工具、技能和翻译的更改。
触发热重载
可以通过以下方式触发热重载:
| 方法 |
描述 |
/gamesai reload |
由管理员(Lv4)运行,以重新加载所有配置、工具、技能和翻译。 |
/gamesai config lang <lang> |
立即应用语言更改。 |
/gamesai config defaultAi <aiID> |
立即应用默认模型更改。 |
/gamesai config maxHistory <value> |
立即应用历史记录长度更改。 |
AI 工具 reload_plugin |
AI 在修改工具代码或技能文件后调用,以立即应用更改。 |
| 游戏内配置界面 (F6) |
点击“保存”会将更改写入 config.json 并立即生效。 |
热重载期间发生什么
执行热重载时,模组会按顺序执行以下步骤:
- 重新读取配置文件 (
config/games_ai/config.json) —— 应用对 prefix、max_history、lang、all_ai、default_ai 等的所有更改。
- 重新加载翻译 —— 应用所选的
lang (en_us / zh_cn),无需重启。
- 重新加载技能 (
config/games_ai/skills/skills.json) —— 刷新技能索引;AI 系统提示词中的可用技能列表同步更新。
- 重新加载自定义工具 (
config/games_ai/tools/*.groovy) —— 在不重启服务器的情况下热加载自定义 Groovy 工具代码。
热重载不会清除玩家的聊天历史。历史记录存储在内存中,仅在服务器重启时清除。
项目结构
src/
├── main/java/io/github/pengzixuan30/gamesai/
│ ├── GamesAI.java # 模组入口 — 初始化与配置加载
│ ├── command/
│ │ └── GamesAICommands.java # 命令注册与执行
│ ├── config/
│ │ ├── GamesAIConfig.java # 配置数据模型(AI 配置文件、extra_body)
│ │ └── GamesAIConfigManager.java # 配置文件读写(JSON,UTF-8)
│ ├── database/
│ │ └── GamesAIDatabase.java # SQLite 公共数据库
│ ├── help/
│ │ └── GamesAIHelp.java # 上下文敏感帮助系统
│ ├── openai/
│ │ └── GamesAIRequestAI.java # OpenAI API 客户端及响应处理
│ ├── tools/
│ │ ├── GamesAIToolsRegister.java # 工具注解扫描器
│ │ ├── GamesAIBuiltinTools.java # 内置工具实现
│ │ └── GamesAIExternalToolsLoader.java # Groovy 工具加载器
│ └── translations/
│ └── GamesAITranslations.java # 国际化翻译引擎
├── main/resources/
│ ├── fabric.mod.json # Fabric 模组元数据
│ └── assets/games_ai/lang/ # 翻译文件(en_us, zh_cn)
├── client/java/io/github/pengzixuan30/gamesai/client/
│ ├── GamesAIClient.java # 客户端入口 — 按键绑定、/c-ask
│ └── screen/
│ ├── GamesAIConfigScreen.java # 主配置界面
│ ├── GeneralConfigEditScreen.java # 常规设置编辑器
│ ├── AiProfileConfigEditScreen.java # AI 配置文件列表编辑器
│ └── AiProfileDetailConfigEditScreen.java # AI 配置文件详情编辑器
├── build.gradle
├── gradle.properties
└── settings.gradle
架构
flowchart LR
Config[json] -->|load| Manager[GamesAIConfigManager]
Manager --> Model[GamesAIConfig]
Model --> Main[GamesAI]
Main --> Cmd[GamesAICommands]
Cmd -->|/ask| API[GamesAIRequestAI]
API -->|HTTP| OpenAI[OpenAI API]
Main --> History[(allHistory)]
History --> API
API --> History
API -->|response| Cmd
Cmd -->|sendMessage| Player[Minecraft Player]
Main --> DB[(GamesAIDatabase)]
DB --> API
Main --> Tools[GamesAIToolsRegister]
Tools --> API
GUI[Config Screen] --> Manager
| Class |
Responsibility |
GamesAI |
模组生命周期、配置、allHistory CRUD、safeTrimHistory、调试模式、提示词解析 |
GamesAICommands |
命令树(/ask, /gamesai),使用 CompletableFuture 进行异步分发 |
GamesAIConfig |
数据模型:prefix、max_history、lang、all_ai 配置文件(含 extra_body)、default_ai |
GamesAIConfigManager |
GSON 序列化,文件 I/O 至 config/games_ai/config.json(UTF-8) |
GamesAIDatabase |
用于公共数据的 SQLite 键值存储 |
GamesAIHelp |
上下文敏感帮助:/gamesai → 顶级菜单,/gamesai config → 仅子命令 |
GamesAIRequestAI |
OpenAI SDK 客户端,构建消息(system → history → user),管理历史记录 |
GamesAITranslations |
国际化引擎:从 assets/games_ai/lang/ 加载 JSON,UTF-8,支持实时重载 |
GamesAIToolsRegister |
@RegisterTool 注解扫描器,用于内置工具和 Groovy 工具 |
GamesAIBuiltinTools |
15+ 个内置 AI 函数(wiki、计算器、白名单、数据库、技能) |
GamesAIExternalToolsLoader |
从 config/games_ai/tools/*.groovy 加载 Groovy 脚本 |
GamesAIClient |
客户端入口:F6 热键用于配置 GUI,/c-ask 命令 |
Config Screens |
游戏内可视化配置编辑器,支持撤销/保存、滑块、循环按钮 |
构建
前置条件
- JDK 21(或更高版本)
- Gradle Wrapper(已包含 — 请使用
gradlew / gradlew.bat)
构建
git clone https://github.com/PengZixuan30/GamesAI.git
cd GamesAI
./gradlew build
编译后的 .jar 文件位于:build/libs/games_ai-*.jar
开发环境
./gradlew runClient # 启动带有该模组的 Minecraft 客户端
./gradlew runServer # 启动本地测试服务器
故障排除
/ask 返回错误
| Error |
Likely Cause |
Fix |
| 401 |
API 密钥无效 |
检查 AI 配置文件中的 api_key |
| 404 |
Base URL 错误或模型名称错误 |
验证 base_url 和 ai_model |
| 429 |
速率限制 |
等待并重试;降低请求频率 |
| Timeout |
服务器不可达 |
检查网络和 base_url |
| Empty reply |
模型未返回任何内容 |
检查提示词和模型兼容性 |
AI 工具无法工作
- 确保工具已正确注册:在服务器日志中查找
[GamesAIToolsRegister] Registered tool: ...
- 对于自定义 Groovy 工具,请检查
config/games_ai/tools/ 中是否存在语法错误
- 启用调试模式:
/gamesai debug 以查看完整的提示词和工具调用结果
配置界面问题
- 按 F6 打开(在“控制”→“杂项”中检查按键绑定)
- 在 GUI 中对配置所做的更改仅在单击“Save”(保存)时才会保存
- 使用“Undo”(撤销)恢复到上次保存的状态
更新日志
Version 0.2.0
? 亮点
- ?️ 客户端配置界面 — 一个可视化的游戏内配置 GUI(按 F6)。
- ? 客户端命令
/c-ask — 无需服务器命令权限即可从客户端询问 AI。
- ?️ 数据库、外部提示词、技能 & 自定义工具 — SQLite 公共数据库、
> file.md 提示词引用、技能系统以及 Groovy 自定义工具。
- ? 无历史记录模式 —
/ask -n 在不使用对话历史的情况下询问 AI(与 MCDReforged 版本保持一致)。
- ?️ AI 工具调用 — AI 现在可以调用内置和自定义工具来与 Minecraft 和数据库交互。
- ⚙️
extra_body 配置 — 向 API 传递特定提供商的额外参数,以获得更大的灵活性。
1. 客户端配置界面
按 F6(默认)打开可视化配置界面。使用滑块、文本字段和循环按钮编辑常规设置和 AI 配置文件 — 更改将保存到 config.json 并立即生效。参见 In-Game Config Screen。
2. 客户端命令 /c-ask
新的客户端 /c-ask 命令允许玩家从客户端向 AI 提问,而无需服务器命令权限。它支持与 /ask 相同的 -m(模型)和 -n(无历史记录)标志。请参阅 Client Commands。
3. 数据库、外部提示词、技能与自定义工具
-
公共数据库 — 由 AI 工具和命令访问的 SQLite 键值存储。参见 数据库系统。
-
外部提示文件 — 通过 > filename 引用外部 .md 文件作为系统提示。参见 提示文件参考。
-
技能 — 为 AI 提供领域特定知识的 Markdown 文件。参见 技能。
-
自定义工具 — 通过 Groovy 脚本扩展 AI 功能。参见 通过 Groovy 使用自定义工具。
4. /ask 无历史记录模式
使用 /ask -n <内容> 向 AI 提问,不使用对话历史(与 MCDReforged 版本的 !!ask -n 对齐)。参见 Ask Commands。
5. AI 工具调用
AI 现在可以调用内置工具(Minecraft Wiki 搜索、计算器、白名单、数据库、技能等)以及自定义 Groovy 工具,以在 Minecraft 中执行操作。详见 AI Tools。
6. extra_body 配置
每个 AI 配置文件现在都支持 extra_body 字段,用于传递特定于提供程序的额外参数(例如 DeepSeek 的 {"thinking": {"type": "enabled"}})。参见 4. all_ai。
版本兼容性
| Minecraft |
Fabric 加载器 (最低版本) |
Yarn 映射 (最低版本) |
Fabric API (最低版本) |
| 26.2 |
0.18.4 |
- |
0.152.1+26.2 |
| 26.1.2 |
0.18.4 |
- |
0.145.4+26.1.2 |
| 26.1.1 |
0.18.4 |
- |
0.145.2+26.1.1 |
| 26.1 |
0.18.4 |
- |
0.144.0+26.1 |
| 1.21.11 |
0.17.3 |
1.21.11+build.6 |
0.139.4+1.21.11 |
| 1.21.10 |
0.17.0 |
1.21.10+build.3 |
0.134.1+1.21.10 |
| 1.21.9 |
0.17.0 |
1.21.9+build.1 |
0.133.14+1.21.9 |
| 1.21.8 |
0.16.13 |
1.21.8+build.1 |
0.129.0+1.21.8 |
| 1.21.7 |
0.16.13 |
1.21.7+build.8 |
0.128.1+1.21.7 |
| 1.21.6 |
0.16.13 |
1.21.6+build.1 |
0.127.0+1.21.6 |
| 1.21.5 |
0.16.10 |
1.21.5+build.1 |
0.119.5+1.21.5 |
| 1.21.4 |
0.16.9 |
1.21.4+build.8 |
0.110.5+1.21.4 |
| 1.21.3 |
0.16.7 |
1.21.3+build.2 |
0.106.1+1.21.3 |
| 1.21.2 |
0.16.7 |
1.21.2+build.1 |
0.106.1+1.21.2 |
| 1.21.1 |
0.15.11 |
1.21.1+build.3 |
0.102.0+1.21.1 |
| 1.21 |
0.15.11 |
1.21+build.9 |
0.100.1+1.21 |
由于作者精力有限,我们将不再支持 1.21 以下版本或非 Fabric 加载器。
致谢与免责声明
所有由 AI(大型语言模型)生成的内容与本模组无关。
因自定义工具产生的任何后果与本模组无关。
赞助者与贡献者
赞助地址:爱发电
赞助 GamesAI 的开发者将出现在下方的赞助者列表中(目前暂无赞助者):
许可证
- 源代码采用 MIT 许可证授权——详情请参阅 LICENSE 文件。
- 标志及视觉素材为专有财产,版权归 冬天衣服不错 所有。您可以出于个人非商业目的查看和分享这些素材,但任何修改或商业用途均需事先获得书面许可。
GamesAI Plugin/Mod QQ Group: 849544707 — Join us to discuss issues, share feedback, and exchange prompt, skills, tools configurations!
Welcome to GamesAI for Fabric! This mod brings AI assistants into Minecraft — ask questions, manage data, and configure AI backends right from the game.
Due to the author's limited energy, we will not support versions below 1.21 or non-Fabric loaders.
Table of Contents (click to expand)
Installation
Prerequisites
- Minecraft 1.21+ (or Fabric-compatible version — see Version Compatibility)
- Fabric Loader ≥ 0.16.10
- Fabric API (latest for your MC version)
- Java 21 or newer
Steps
- Download the latest
.jar from Modrinth
- Place it in your
.minecraft/mods/ folder
- Launch the game with Fabric Loader
- A default config file is generated at
config/games_ai/config.json on first run
- Edit the config with your API credentials, then reload with
/gamesai reload
Alternatively, download the .jar from GitHub Releases and place it in your .minecraft/mods/ folder the same way.
Usage
Ask Commands
| Command |
Description |
/ask <content> |
Ask AI using the default model |
/ask -m <model> <content> |
Ask AI using a specific model profile |
/ask -n <content> |
Ask AI without conversation history |
/ask -n -m <model> <content> |
Specific model, no history |
Only short flags (-m, -n) are supported. Long forms (--model, --no-history) are not available to avoid duplication in Minecraft's built-in command suggestions.
Management Commands
General
| Command |
Permission |
Description |
/gamesai help |
Everyone |
Show context-sensitive help |
/gamesai reload |
Owner (Lv4) |
Reload config, tools, and translations |
History
| Command |
Permission |
Description |
/gamesai history clear |
Everyone |
Clear your own conversation history |
/gamesai history clearall |
Owner (Lv4) |
Clear all players' history |
Config
| Command |
Permission |
Description |
/gamesai config lang <lang> |
Owner (Lv4) |
Set server language (en_us / zh_cn) |
/gamesai config defaultAi <aiID> |
Owner (Lv4) |
Set default AI model |
/gamesai config maxHistory <value> |
Owner (Lv4) |
Set max conversation rounds (≥ 1) |
Data
| Command |
Permission |
Description |
/gamesai data write <key> <value> |
Owner (Lv4) |
Write data to database (overwrite) |
/gamesai data add <key> <value> |
Owner (Lv4) |
Append data to database |
/gamesai data del <key> |
Owner (Lv4) |
Delete an entry from database |
/gamesai data read <key> |
Owner (Lv4) |
Read value by key |
/gamesai data list |
Owner (Lv4) |
List all key-value pairs |
/gamesai data list keys |
Owner (Lv4) |
List all keys |
Client Commands
| Command |
Description |
/c-ask <content> |
Ask AI from the client side (no server command permission needed) |
/c-ask -m <model> <content> |
Client-side ask with specific model |
/c-ask -n <content> |
Client-side ask without history |
/c-ask -n -m <model> <content> |
Client-side ask, specific model, no history |
In-Game Config Screen
Press F6 (default) to open the visual configuration screen
- General Settings — Edit
prefix, max_history, lang, default_ai with sliders, text fields, and cycle buttons
- AI Profiles — Add, edit, or delete AI backend configurations with a visual editor
- Changes are saved to
config.json and applied immediately
To rebind the config screen key: Options → Controls → Key Binds → Miscellaneous → Open GamesAI Config
Configuration
On first run, a default config is created at:
.minecraft/config/games_ai/config.json
Default Structure
{
"prefix": "[GamesAI]",
"max_history": 10,
"lang": "en_us",
"all_ai": {
"example_ai": {
"prompt": "You are a helpful assistant in Minecraft.",
"ai_name": "[GamesAI]",
"base_url": "<Your Base URL>",
"ai_model": "<Your AI Model>",
"api_key": "<Your API Key>",
"extra_body": {}
}
},
"default_ai": "example_ai"
}
1. prefix
| Property |
Value |
| Type |
String |
| Default |
[GamesAI] |
The plugin name used as a prefix in replies. May include Minecraft formatting codes.
2. max_history
| Property |
Value |
| Type |
int |
| Default |
10 |
The maximum number of conversation turns retained per player per model. Set to 0 to disable history. History is stored in memory and cleared on server restart.
3. lang
| Property |
Value |
| Type |
String |
| Default |
en_us |
| Options |
en_us, zh_cn |
Server-wide display language. Changes take effect after /gamesai reload.
4. all_ai
All AI configuration entries. Each entry is a dictionary (the key is the internal AI_ID):
| Field |
Description |
| prompt |
System prompt for this AI. Use > filename.md to load from config/games_ai/prompt/. |
| ai_name |
Display name shown in chat (may include Minecraft formatting codes). |
| base_url |
API endpoint URL (e.g., https://api.openai.com/v1). |
| ai_model |
Model name (e.g., gpt-4o, deepseek-chat). |
| api_key |
API authentication key. |
| extra_body |
Additional parameters passed to the API (e.g., {"thinking": {"type": "enabled"}} for DeepSeek). Default: {}. |
Multi-Profile Example
{
"all_ai": {
"gpt4o": {
"prompt": "You are a Minecraft expert.",
"ai_name": "[GPT-4o]",
"base_url": "https://api.openai.com/v1",
"ai_model": "gpt-4o",
"api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"extra_body": {}
},
"deepseek": {
"prompt": "You are a helpful Minecraft assistant.",
"ai_name": "[DeepSeek]",
"base_url": "https://api.deepseek.com",
"ai_model": "deepseek-chat",
"api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"extra_body": {}
},
"local_llama": {
"prompt": "You are a friendly Minecraft assistant.",
"ai_name": "[Llama3]",
"base_url": "http://localhost:11434/v1",
"ai_model": "llama3",
"api_key": "ollama",
"extra_body": {}
}
},
"default_ai": "gpt4o"
}
For Ollama / local models, set api_key to "ollama" as a placeholder.
5. default_ai
| Property |
Value |
| Type |
String |
The model used when a player simply uses /ask. Must be one of the keys in all_ai.
prompt File Reference
Instead of embedding long prompts in config.json, you can reference external files:
- Place your prompt file in
config/games_ai/prompt/ (e.g., my_prompt.md)
- Set
"prompt": "> my_prompt.md" in the AI profile
The mod automatically reads the file contents at request time. Any text file format (.md, .txt, etc.) is supported.
Database System
GamesAI includes a SQLite-based public database at config/games_ai/database/database.db.
| Command |
Description |
/gamesai data write <key> <value> |
Write a key-value pair (overwrites existing) |
/gamesai data add <key> <value> |
Append value to an existing key (auto-creates) |
/gamesai data del <key> |
Delete an entry |
/gamesai data read <key> |
Read a value by key |
/gamesai data list |
List all key-value pairs |
/gamesai data list keys |
List all keys |
The AI can also read and write the database through built-in tools (ai_read_data, ai_write_data, ai_add_data, ai_del_data).
AI Tools
The AI can call functions to interact with Minecraft and the database.
Built-in Tools
| Tool |
Parameters |
Description |
get_online_players |
none |
Get the current online player list |
get_whitelist_name |
none |
Get the server whitelist |
add_to_whitelist |
player |
Add a player to the whitelist |
remove_from_whitelist |
player |
Remove a player from the whitelist |
search_minecraft_wiki |
query |
Search the Minecraft Wiki |
calculator |
expression |
Evaluate a mathematical expression |
item_calculator |
expression, single_limit |
Calculate item counts with Minecraft units (stacks/shulkers) |
ai_read_data |
key |
Read a database entry |
ai_read_all_keys |
none |
Get all database keys |
ai_read_all_data |
none |
Read all database entries |
ai_write_data |
key, value |
Write to database (overwrite) |
ai_add_data |
key, value |
Append to database |
ai_del_data |
key |
Delete a database entry |
read_skills |
skills |
Read a skill file |
setting_timer |
duration |
Wait for N seconds before continuing |
reload_plugin |
none |
Execute /gamesai reload |
Custom Tools via Groovy
You can extend AI capabilities by writing Groovy scripts:
- Place
.groovy files in config/games_ai/tools/
- Annotate methods with
@RegisterTool:
import java.util.function.Consumer;
import io.github.pengzixuan30.gamesai.tools.GamesAIToolsRegister;
@GamesAIToolsRegister.RegisterTool(
name = "my_custom_tool",
description = "Does something useful",
parameters = """
{
"type": "object",
"properties": {
"param": {
"type": "string",
"description": "The value to process"
}
},
"required": ["param"]
}
"""
)
String myCustomTool(Consumer<String> feedback, String aiName, String param) {
feedback.accept("Executing custom tool...")
return "Result: ${param} processed"
}
The tool method signature must place Consumer<String> feedback as the first parameter and String aiName as the second, followed by any custom parameters declared in the parameters JSON schema.
- Reload with
/gamesai reload — tools are discovered and registered automatically.
Skills
Skills are Markdown files that provide the AI with domain-specific knowledge and instructions. The AI can read them via the read_skills tool.
Adding Skills
- Place
.md files in config/games_ai/skills/
- Register them in
config/games_ai/skills/skills.json:
[
{
"skills": "my_guide.md",
"summary": "A guide for building redstone machines"
}
]
- Reload with
/gamesai reload
Registered skills appear in the AI's system prompt so it knows what knowledge is available.
Hot Reload
GamesAI provides a hot-reload mechanism that lets you apply configuration, tool, skill, and translation changes without restarting the server.
Triggering a Hot Reload
Hot reload can be triggered in the following ways:
| Method |
Description |
/gamesai reload |
Run by an admin (Lv4) to reload all configuration, tools, skills, and translations. |
/gamesai config lang <lang> |
Applies the language change immediately. |
/gamesai config defaultAi <aiID> |
Applies the default model change immediately. |
/gamesai config maxHistory <value> |
Applies the history length change immediately. |
AI tool reload_plugin |
Called by the AI after modifying tool code or skill files to apply changes immediately. |
| In-game config screen (F6) |
Clicking "Save" writes changes to config.json and applies them immediately. |
What Happens During a Hot Reload
When a hot reload is performed, the mod executes the following steps in order:
- Re-read the configuration file (
config/games_ai/config.json) — Applies all changes to prefix, max_history, lang, all_ai, default_ai, etc.
- Reload translations — Applies the selected
lang (en_us / zh_cn) without restarting.
- Reload Skills (
config/games_ai/skills/skills.json) — Refreshes the skill index; the available skills list in the AI's system prompt is updated synchronously.
- Reload custom tools (
config/games_ai/tools/*.groovy) — Hot-loads custom Groovy tool code without restarting the server.
Hot reload does not clear players' chat history. History is stored in memory and is only cleared on server restart.
Project Structure
src/
├── main/java/io/github/pengzixuan30/gamesai/
│ ├── GamesAI.java # Mod entry point — init & config loading
│ ├── command/
│ │ └── GamesAICommands.java # Command registration & execution
│ ├── config/
│ │ ├── GamesAIConfig.java # Config data model (AI profiles, extra_body)
│ │ └── GamesAIConfigManager.java # Config file read/write (JSON, UTF-8)
│ ├── database/
│ │ └── GamesAIDatabase.java # SQLite public database
│ ├── help/
│ │ └── GamesAIHelp.java # Context-sensitive help system
│ ├── openai/
│ │ └── GamesAIRequestAI.java # OpenAI API client & response handling
│ ├── tools/
│ │ ├── GamesAIToolsRegister.java # Tool annotation scanner
│ │ ├── GamesAIBuiltinTools.java # Built-in tool implementations
│ │ └── GamesAIExternalToolsLoader.java # Groovy tool loader
│ └── translations/
│ └── GamesAITranslations.java # I18n translation engine
├── main/resources/
│ ├── fabric.mod.json # Fabric mod metadata
│ └── assets/games_ai/lang/ # Translation files (en_us, zh_cn)
├── client/java/io/github/pengzixuan30/gamesai/client/
│ ├── GamesAIClient.java # Client entry — key binding, /c-ask
│ └── screen/
│ ├── GamesAIConfigScreen.java # Main config screen
│ ├── GeneralConfigEditScreen.java # General settings editor
│ ├── AiProfileConfigEditScreen.java # AI profile list editor
│ └── AiProfileDetailConfigEditScreen.java # AI profile detail editor
├── build.gradle
├── gradle.properties
└── settings.gradle
Architecture
flowchart LR
Config[json] -->|load| Manager[GamesAIConfigManager]
Manager --> Model[GamesAIConfig]
Model --> Main[GamesAI]
Main --> Cmd[GamesAICommands]
Cmd -->|/ask| API[GamesAIRequestAI]
API -->|HTTP| OpenAI[OpenAI API]
Main --> History[(allHistory)]
History --> API
API --> History
API -->|response| Cmd
Cmd -->|sendMessage| Player[Minecraft Player]
Main --> DB[(GamesAIDatabase)]
DB --> API
Main --> Tools[GamesAIToolsRegister]
Tools --> API
GUI[Config Screen] --> Manager
| Class |
Responsibility |
GamesAI |
Mod lifecycle, config, allHistory CRUD, safeTrimHistory, debug mode, prompt resolution |
GamesAICommands |
Command tree (/ask, /gamesai), async dispatch with CompletableFuture |
GamesAIConfig |
Data model: prefix, max_history, lang, all_ai profiles (with extra_body), default_ai |
GamesAIConfigManager |
GSON serialization, file I/O to config/games_ai/config.json (UTF-8) |
GamesAIDatabase |
SQLite key-value store for public data |
GamesAIHelp |
Context-sensitive help: /gamesai → top-level, /gamesai config → subcommands only |
GamesAIRequestAI |
OpenAI SDK client, builds messages (system → history → user), manages history |
GamesAITranslations |
I18n engine: loads JSON from assets/games_ai/lang/, UTF-8, live reload |
GamesAIToolsRegister |
@RegisterTool annotation scanner for built-in & Groovy tools |
GamesAIBuiltinTools |
15+ built-in AI functions (wiki, calculator, whitelist, database, skills) |
GamesAIExternalToolsLoader |
Groovy script loader from config/games_ai/tools/*.groovy |
GamesAIClient |
Client-side entry: F6 hotkey for config GUI, /c-ask command |
Config Screens |
In-game visual config editor with undo/save, sliders, cycle buttons |
Building
Prerequisites
- JDK 21 (or newer)
- Gradle Wrapper (included — use
gradlew / gradlew.bat)
Build
git clone https://github.com/PengZixuan30/GamesAI.git
cd GamesAI
./gradlew build
The compiled .jar will be at: build/libs/games_ai-*.jar
Dev Environment
./gradlew runClient # Launch Minecraft client with the mod
./gradlew runServer # Launch a local test server
Troubleshooting
/ask Returns Errors
| Error |
Likely Cause |
Fix |
| 401 |
Invalid API key |
Check api_key in the AI profile |
| 404 |
Wrong base URL or model name |
Verify base_url and ai_model |
| 429 |
Rate limited |
Wait and retry; reduce request frequency |
| Timeout |
Server unreachable |
Check network and base_url |
| Empty reply |
Model returned nothing |
Check prompt and model compatibility |
AI Tools Not Working
- Ensure tools are properly registered: check server log for
[GamesAIToolsRegister] Registered tool: ...
- For custom Groovy tools, check
config/games_ai/tools/ for syntax errors
- Enable debug mode:
/gamesai debug to see full prompts and tool call results
Config Screen Issues
- Press F6 to open (check key binding in Controls → Miscellaneous)
- Config changes in the GUI are saved only when you click "Save"
- Use "Undo" to revert to the last saved state
What's New
Version 0.2.0
? Highlights
- ?️ Client-side config screen — A visual in-game configuration GUI (press F6).
- ? Client command
/c-ask — Ask AI from the client without server command permissions.
- ?️ Database, external prompts, skills & custom tools — SQLite public database,
> file.md prompt references, a skills system, and Groovy custom tools.
- ? No-history mode —
/ask -n asks AI without conversation history (aligned with the MCDReforged version).
- ?️ AI tool calling — The AI can now call built-in and custom tools to interact with Minecraft and the database.
- ⚙️
extra_body config — Pass extra provider-specific parameters to the API for more flexibility.
1. Client-side Config Screen
Press F6 (default) to open the visual configuration screen. Edit general settings and AI profiles with sliders, text fields, and cycle buttons — changes are saved to config.json and applied immediately. See In-Game Config Screen.
2. Client Command /c-ask
The new client-side /c-ask command lets players ask AI from the client without needing server command permissions. It supports -m (model) and -n (no-history) flags, just like /ask. See Client Commands.
3. Database, External Prompts, Skills, and Custom Tools
- Public database — SQLite key-value store accessible by AI tools and commands. See Database System.
- External prompt files — Reference external
.md files as system prompts via > filename. See prompt File Reference.
- Skills — Markdown files that give the AI domain-specific knowledge. See Skills.
- Custom tools — Extend AI capabilities with Groovy scripts. See Custom Tools via Groovy.
4. /ask No-History Mode
Use /ask -n <content> to ask AI without using conversation history (aligned with the MCDReforged version's !!ask -n). See Ask Commands.
5. AI Tool Calling
The AI can now call built-in tools (Minecraft Wiki search, calculator, whitelist, database, skills, etc.) and custom Groovy tools to perform actions in Minecraft. See AI Tools.
6. extra_body Config
Each AI profile now supports an extra_body field for passing extra provider-specific parameters (e.g. DeepSeek's {"thinking": {"type": "enabled"}}). See 4. all_ai.
Version Compatibility
| Minecraft |
Fabric Loader (min) |
Yarn Mappings (min) |
Fabric API (min) |
| 26.2 |
0.18.4 |
- |
0.152.1+26.2 |
| 26.1.2 |
0.18.4 |
- |
0.145.4+26.1.2 |
| 26.1.1 |
0.18.4 |
- |
0.145.2+26.1.1 |
| 26.1 |
0.18.4 |
- |
0.144.0+26.1 |
| 1.21.11 |
0.17.3 |
1.21.11+build.6 |
0.139.4+1.21.11 |
| 1.21.10 |
0.17.0 |
1.21.10+build.3 |
0.134.1+1.21.10 |
| 1.21.9 |
0.17.0 |
1.21.9+build.1 |
0.133.14+1.21.9 |
| 1.21.8 |
0.16.13 |
1.21.8+build.1 |
0.129.0+1.21.8 |
| 1.21.7 |
0.16.13 |
1.21.7+build.8 |
0.128.1+1.21.7 |
| 1.21.6 |
0.16.13 |
1.21.6+build.1 |
0.127.0+1.21.6 |
| 1.21.5 |
0.16.10 |
1.21.5+build.1 |
0.119.5+1.21.5 |
| 1.21.4 |
0.16.9 |
1.21.4+build.8 |
0.110.5+1.21.4 |
| 1.21.3 |
0.16.7 |
1.21.3+build.2 |
0.106.1+1.21.3 |
| 1.21.2 |
0.16.7 |
1.21.2+build.1 |
0.106.1+1.21.2 |
| 1.21.1 |
0.15.11 |
1.21.1+build.3 |
0.102.0+1.21.1 |
| 1.21 |
0.15.11 |
1.21+build.9 |
0.100.1+1.21 |
Due to the author's limited energy, we will not support versions below 1.21 or non-Fabric loaders.
Acknowledgements & Disclaimer
- DA100 — Logo design for this mod
- FabricMC — Modding framework
- openai/openai-java — Official OpenAI Java library
- Minecraft is a trademark of Mojang / Microsoft. This mod is not affiliated with Mojang.
All content generated by AI (LLM) models is unrelated to this mod.
All consequences arising from custom tools are unrelated to this mod.
Sponsorship & Contributors
Sponsorship address: Afdian
Those who sponsor GamesAI will appear in the following sponsor list (currently no sponsors):
| # |
Sponsor |
Amount |
Date |
| - |
- |
- |
- |
License
- Source code is licensed under the MIT License — see the LICENSE file for details.
- Logo and visual assets are proprietary and all rights reserved by 冬天衣服不错. You may view and share them for personal, non‑commercial use, but any modification or commercial use requires prior written permission.
评论 0
登录后参与评分
还没有评论,来抢沙发吧