GamesAI

模组

· 作者 PengZixuan

此 Minecraft 模组允许你在服务器和游戏中使用 AI。

0 本站下载 0 关注 更新于 3 个月前

最新 0.2.0-Fabric-26.2 · 26.2 · Fabric

一键开服(送7天)

GamesAI for Fabric

English | 简体中文

Report an Issue | Share an Idea | Join QQ Group

Go to MCDReforged Version

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

  1. Download the latest .jar from Modrinth
  2. Place it in your .minecraft/mods/ folder
  3. Launch the game with Fabric Loader
  4. A default config file is generated at config/games_ai/config.json on first run
  5. 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

属性 值
类型 int
默认值 10

每个玩家在每个模型上保留的最大对话轮数。设置为 0 以禁用历史记录。历史记录存储在内存中,并在服务器重启时清除。


3. lang

属性 值
类型 String
默认值 en_us
可选值 en_us, zh_cn

服务器范围的显示语言。更改后需执行 /gamesai reload 生效。


4. all_ai

属性 值
类型 dict

所有 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

属性 值
类型 String

当玩家仅使用 /ask 时使用的模型。必须是 all_ai 中的某个键。


prompt 文件引用

您可以不将长提示词嵌入 config.json,而是引用外部文件:

  1. 将提示词文件放置在 config/games_ai/prompt/ 中(例如 my_prompt.md)
  2. 在 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 的功能:

  1. 将 .groovy 文件放置在 config/games_ai/tools/ 目录下
  2. 使用 @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 模式中声明的任何自定义参数。

  1. 使用 /gamesai reload 重新加载 —— 工具会自动被发现和注册。

技能 (Skills)

技能是 Markdown 文件,用于向 AI 提供特定领域的知识和指令。AI 可以通过 read_skills 工具来读取它们。

添加技能

  1. 将 .md 文件放置在 config/games_ai/skills/ 目录下
  2. 在 config/games_ai/skills/skills.json 中进行注册:
[
  {
    "skills": "my_guide.md",
    "summary": "A guide for building redstone machines"
  }
]
  1. 使用 /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 并立即生效。

热重载期间发生什么

执行热重载时,模组会按顺序执行以下步骤:

  1. 重新读取配置文件 (config/games_ai/config.json) —— 应用对 prefix、max_history、lang、all_ai、default_ai 等的所有更改。
  2. 重新加载翻译 —— 应用所选的 lang (en_us / zh_cn),无需重启。
  3. 重新加载技能 (config/games_ai/skills/skills.json) —— 刷新技能索引;AI 系统提示词中的可用技能列表同步更新。
  4. 重新加载自定义工具 (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 加载器。


致谢与免责声明

  • DA100 — 为本模组设计的标志
  • FabricMC — 模组开发框架
  • openai/openai-java — OpenAI 官方 Java 库
  • Minecraft 是 Mojang / Microsoft 的商标。本模组与 Mojang 无关。

所有由 AI(大型语言模型)生成的内容与本模组无关。

因自定义工具产生的任何后果与本模组无关。


赞助者与贡献者

赞助地址:爱发电

赞助 GamesAI 的开发者将出现在下方的赞助者列表中(目前暂无赞助者):

# 赞助者 金额 日期
- - - -

许可证

  • 源代码采用 MIT 许可证授权——详情请参阅 LICENSE 文件。
  • 标志及视觉素材为专有财产,版权归 冬天衣服不错 所有。您可以出于个人非商业目的查看和分享这些素材,但任何修改或商业用途均需事先获得书面许可。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源