
地毯 GUI
一个用于Carpet及支持的Carpet附加组件的图形化工作区。
查看大图Carpet GUI
English(Selected)
浏览规则。整理预设。
面向 Carpet 及受支持的 Carpet 附加模组的图形化工作区。
安装 · 快速开始 · 规则组 · 常见问题 · Rules API · 报告问题
Carpet GUI 将规则浏览、编辑和配置管理整合到一个游戏内工作区中。 无需记住命令即可查找规则,将相关规则收集到可复用的组中, 并在将已提交的值保存到服务器之前进行检查。
功能
| 你可以做什么 | |
|---|---|
| 🔎 查找规则 | 浏览模组页面或全部规则;搜索 ID、名称和描述,包括已索引的英文和中文翻译。 |
| 🗂️ 整理工作区 | 打开多个标签页,折叠分类,按分类或收藏过滤,按名称或值排序。 |
| 🎛️ 可视化编辑 | 使用开关、选项列表和值字段;在允许时重置规则或保存持久默认值。 |
| ⭐ 保留收藏 | 跨会话保存常用规则。 |
| 🌳 构建规则组 | 将相关规则整理到文件夹中,暂存值,并创建带消息的本地提交。 |
| 🕘 查看历史 | 点击提交以查看其作者、时间和规则差异;将鼠标悬停在规则上可查看已观察到的服务器变更(如有)。 |
| 📦 分享预设 | 将已提交的值导出为 JSON,并导入到另一个工作区。 |
| ✅ 审核应用 | 将实时值与已提交的目标进行比较,选择要应用的规则,并了解规则无法应用的原因。 |
| 🌍 分离环境 | 为每个世界或多玩家服务器保持独立的组和提交历史。 |
| ⚙️ 浏览游戏规则 | 在受支持的 Minecraft 26.x 构建上查看和编辑原版游戏规则,受服务器权限限制。 |
环境要求
依赖项
| 依赖项 | 要求 | 是否必需 |
|---|---|---|
| Fabric Loader | 0.19.5 或更新版本 |
必需 |
| Fabric API | 适用于你的 Minecraft 版本 | 必需 |
| Carpet | 适用于你的 Minecraft 版本的兼容构建 | 必需 |
| TCDCommons | 适用于你的 Minecraft 版本的兼容 Fabric 构建 | 必需 |
| Mod Menu | 适用于你的 Minecraft 版本 | 推荐 |
在客户端安装相关的 Carpet 模组,以使其规则定义可用。 服务器端规则编辑还需要在服务器上安装这些模组。
Minecraft 和 Java 版本
当前构建配置启用了以下目标。 请选择适用于你的 Minecraft 版本的 Carpet GUI JAR。
| Minecraft 构建目标 | 最低 Java 版本 |
|---|---|
1.21.1、1.21.3、1.21.4、1.21.5、1.21.8、1.21.10、1.21.11 |
Java 21 |
26.1.2、26.2、26.3 |
Java 25 |
1.21.1 构建还声明了 Minecraft 1.21 兼容性。
有关启用的构建目标,请参阅 settings.json;
有关每个目标的依赖要求,请参阅 versions/。
客户端和服务器安装
| 能力 | 仅客户端 | 客户端和服务器 |
|---|---|---|
| 规则浏览器、搜索、收藏和本地组 | 可用 | 可用 |
| 普通编辑和设置默认值 | 在允许时使用 Carpet 命令 | 在支持时使用服务器确认的请求 |
| 本地提交和预设导入/导出 | 可用 | 可用 |
| 同步的已保存配置状态 | 需要服务器支持 | 可用 |
| 观察到的玩家规则变更历史 | 需要服务器支持 | 在连接期间可用 |
| 已验证的组推送完成 | 需要服务器支持 | 在所有请求的更改成功后确认 |
[!NOTE] 在单人游戏中,Carpet GUI 也会在集成服务器上运行,因此无需单独安装服务器端。
安装
- 为你的 Minecraft 版本安装 Fabric Loader。
- 选择匹配的 Carpet GUI、Fabric API、Carpet 和 TCDCommons JAR。如果你想要 Mod Menu 的快捷方式,请添加 Mod Menu。
- 将 JAR 放入游戏实例的
mods文件夹。 - 对于多人游戏中的已确认编辑、同步配置和已验证组推送,还请在服务器上安装匹配的 Carpet GUI 和依赖构建。Mod Menu 仅在客户端需要。
- 启动 Minecraft 并加入世界或服务器。
在 Releases 中查找已发布的构建, 或查看 GitHub Actions 以获取可用的开发构建产物。
快速开始
- 在游戏中按 F9,或通过 Mod Menu 打开 Carpet GUI。 你可以在 选项 → 控制 中更改按键绑定。
- 打开模组页面或 全部规则。
- 搜索规则,展开其分类, 并将鼠标悬停在规则上以阅读其描述和可用历史。
- 使用规则的开关、选项列表或值字段进行编辑。 当你想将受支持的规则保存为持久服务器默认值时,请使用 设置默认值。
- 打开 规则组 将规则收集到可复用的配置中。
[!NOTE] 普通规则编辑会影响当前运行的世界或服务器。本地提交会将值记录到你的工作区中;它不会将它们保存为服务器默认值。若要请求持久默认值,请使用 设置默认值,或审核并确认组 推送。
工作区页面
| 页面 | 用途 |
|---|---|
| 主页 | 开始浏览工作区并打开规则页面。 |
| 全部规则 / 模组页面 | 浏览和编辑规则,调整搜索和过滤器,管理收藏。 |
| 规则组 | 管理组成员资格,暂存和提交值,查看历史,导入或导出预设。 |
| 应用预览 | 在应用所选规则之前,将组的已提交目标与当前服务器值进行对比审核。 |
规则组和预设
整理组
使用 + 新建组 创建组,然后使用 管理规则 选择其成员。成员资格和暂存值是分开的:将规则添加到组中不会自动暂存或提交它。
在组名中使用 / 创建文件夹,例如 survival/mob-farms。组显示在 origin 根目录下,长名称可通过水平滚动访问。
origin
├── survival
│ └── mob-farms
├── creative
│ └── testing
└── shared-settings
记录并应用值
选择规则和值 → status → add → commit → push → Review → Apply selected
| 操作 | 作用 |
|---|---|
| status | 显示相对于组最新已提交快照的更改,并分别列出已暂存和未暂存的更改。 |
| add | 将组的当前值和成员移除暂存,以供下一次提交使用。 |
| commit | 创建带有消息、作者和时间戳的本地快照。 |
| push | 打开最新已提交值的预览,以保存为服务器默认值。 |
| Apply selected | 在审核后请求所选的持久默认值更改。已验证完成需要服务器支持。 |
阅读应用预览
箭头表示 当前运行值 → 已提交的目标默认值。 它不会比较两个提交。
| 预览 | 含义 |
|---|---|
false → true |
该规则当前以 false 运行;应用会请求将 true 作为其保存的默认值。 |
true → true |
运行时值已匹配;确认仍会请求将 true 保存为默认值。 |
| 规则不可用或不允许 | 预览会解释该规则无法应用的原因。 |
例如,在提交规则之前将其编辑为 true 可能会产生 true → true,
因为普通编辑已经更改了实时值。
要查看 提交之间 的更改,
请点击右侧历史面板中的提交。
取消勾选规则可跳过它们。 刷新预览 会再次捕获当前服务器值; 在组或服务器值更改后使用它。 仅应用组的一部分会使整个提交保持待处理状态。 已验证的推送只有在快照中的每个目标都成功后才会标记为完成。
分享 JSON 预设
- 暂存并提交你想要分享的值。
- 点击 导出 HEAD。这会导出最新的已提交快照,未提交的编辑不会包含在文件中。
- 将导出的 JSON 文件复制到接收游戏实例的
config/carpet-gui/presets/目录中。 - 打开 规则组 → 导入预设,然后选择文件或输入其文件名(包括
.json)。 - 审核导入组的目标并确认适用的规则。
预设包含组名、标签和规则值。 它们不包含服务器地址、作者身份、本地提交历史和推送状态。 导入会创建一个本地组,并在任何服务器应用之前打开预览。
服务器功能与权限
在双方都安装了匹配的 Carpet GUI 构建时, 编辑可以获得服务器确认的成功或拒绝, 已保存配置可以同步, 组应用可以被验证。
将鼠标悬停在规则上可查看观察到的玩家更改:玩家名称、
旧值 → 新值 以及格式为 [YYYY/MM/DD hh:mm:ss] 的时间戳。
较新的更改会先显示。
此历史记录涵盖当前连接,并非永久审计日志。
Carpet GUI 遵循 Carpet 的权限、值验证和锁定规则。安装它不会授予额外访问权限。 如果编辑不可用, 请检查规则的提示信息以及服务器的权限和配置。
批量应用不是原子性的: 某些规则可能会在其他规则失败之前成功。 成功的更改不会自动回滚, 失败或不完整的推送会保持待处理状态。
数据位置
| 数据 | 位置 |
|---|---|
| 单人游戏组和历史 | <save-root>/carpet-gui/rule-groups.json |
| 多人游戏组和历史 | <game-instance-root>/carpet-gui/Multiplayergames_<address>_<hash>/rule-groups.json |
| 离线工作区 | <game-instance-root>/config/carpet-gui/offline/rule-groups.json |
| 共享预设 | <game-instance-root>/config/carpet-gui/presets/ |
| 共享收藏 | <game-instance-root>/config/carpet-gui/favorites.txt |
每个世界或服务器都有自己独立的组、暂存状态和提交历史。
预设和收藏在游戏实例内共享。
多人游戏工作区数据位于 config 旁边的 carpet-gui 中;
单人游戏数据随存档一起移动。
常见问题
我需要在服务器上安装 Carpet GUI 吗?
浏览、收藏、本地提交和预设文件在客户端即可使用。 当服务器允许时,普通编辑可以使用 Carpet 命令。 在双方安装匹配的构建,以获得服务器确认的编辑、 同步的已保存配置、观察到的更改历史 和已验证的组推送。
为什么预览显示 true → true?
它比较的是当前运行时值与已提交的目标。
如果两者都为 true,则运行时值无需更改,
但所选规则仍会提交以保存为默认值。
右侧提交详情则会显示历史差异。
为什么缺少某个附加模组或规则?
请检查相关附加模组是否已安装在客户端,以及其规则定义是否可用。 共享另一个模组的设置管理器的附加模组可能需要显式的 Rules API 集成才能以自身身份显示。 同时清除任何搜索、分类或收藏过滤器。
为什么我的导出遗漏了最新编辑?
导出 HEAD 导出的是已提交的值。 在再次导出之前,请暂存并提交你的最新更改。
为什么某个提交仍在等待推送?
如果仅选择了部分目标、某个操作失败,或服务器无法确认完成,提交会保持待处理状态。 请检查预览中的原因和反馈消息。 在更改组、服务器值或权限后再次尝试之前,请刷新预览。
为什么我的组在另一个世界或服务器上不同?
组属于当前活动环境。 使用 JSON 预设在不同环境之间复制已提交的值。 如果存在较旧的全局组,工作区可以提供 复制旧版组,以将副本迁移到当前环境。
面向附加模组开发者:Rules API
使用 CarpetModRulesApi 为你的附加模组提供自身身份,并将其注册的 Carpet 规则与其页面关联。当你的附加模组共享另一个模组的设置管理器(例如 /carpet)时,这一点尤其有用。
针对你的目标 Minecraft 版本对应的 Carpet GUI 构建进行编译。你的规则仍必须正常注册到 Carpet;此 API 将现有规则暴露给 GUI,而不是注册新规则。
1. 提供你的模组信息和规则
以下示例适用于规则注册在 Carpet 共享设置管理器中的附加模组。请将模组 ID、显示名称和规则名称替换为你自己的。
package com.example.addon.compat;
import carpet.CarpetServer;
import carpet.api.settings.CarpetRule;
import carpet.api.settings.SettingsManager;
import io.github.piscescup.fabricmc.carpetgui.api.CarpetModRulesApi;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.Set;
public final class ExampleRulesProvider implements CarpetModRulesApi {
private static final Set<String> RULE_NAMES = Set.of("exampleRule", "anotherExampleRule");
@Override
public String carpetModId() {
return "example_addon";
}
@Override
public String carpetFancyName() {
return "Example Addon";
}
@Override
public Collection<CarpetRule<?>> asCarpetRules() {
SettingsManager manager = CarpetServer.settingsManager;
if (manager == null) return List.of();
Collection<CarpetRule<?>> rules = new ArrayList<>();
for (String name : RULE_NAMES) {
CarpetRule<?> rule = manager.getCarpetRule(name);
if (rule != null) rules.add(rule);
}
return rules;
}
}
carpetModId()必须返回你实际安装的 Fabric 模组 ID,而不是设置管理器的命令名称。carpetFancyName()提供人类可读的页面名称。asCarpetRules()必须返回你的附加模组拥有的实时注册的CarpetRule<?>实例。不要返回规则名称字符串、复制的规则或其他附加模组的规则。- 当你的管理器尚未就绪时,返回空集合;永远不要返回
null。提供程序可能会在世界加载之前被查询。
2. 注册提供程序
将此片段合并到你的附加模组的 fabric.mod.json 中,保留其现有的入口点和依赖项:
{
"entrypoints": {
"carpet-gui-mods": [
"com.example.addon.compat.ExampleRulesProvider"
]
},
"depends": {
"carpet-gui": "*"
}
}
此示例将 Carpet GUI 设为必需依赖项。 如果你想要可选集成,请确保在 Carpet GUI 不存在时不加载提供程序。
或者,已注册的 CarpetExtension 可以直接实现 CarpetModRulesApi。
它不需要同时提供 carpet-gui-mods 入口点。每个模组 ID 仅注册一个提供程序。
专用设置管理器
如果你有自己的设置管理器,
请返回其注册的规则,而不是读取 CarpetServer.settingsManager。
如果你的附加模组拥有整个管理器,
你可以实现 CarpetModInfoApi 并覆盖 getSettingsManagerIds():
@Override
public Set<String> getSettingsManagerIds() {
return Set.of("exampleManager");
}
该值必须与 SettingsManager.identifier() 匹配。
不要认领整个共享管理器:将此方法保留为其空默认值,并使用 asCarpetRules() 仅标识你自己的规则。
翻译
默认情况下,翻译从你的模组的 assets/<namespace>/lang/<language>.json 资源中读取。
使用 Carpet 的原始键,并以实际设置管理器标识符作为前缀。
例如,对于 /carpet 中的规则:
{
"carpet.rule.exampleRule.desc": "Controls the example behavior.",
"carpet.rule.exampleRule.extra.0": "Additional details about this rule.",
"carpet.category.example": "Example"
}
如果你的附加模组使用不同的资源布局,或已通过 CarpetExtension.canHasTranslations 提供翻译,请覆盖 getTranslations(String language)。
返回 Carpet 翻译键到文本的映射,而不更改 Carpet 的全局语言状态。
打开你的附加模组页面
从仅客户端代码中,使用 CarpetGuiScreens 创建以你的附加模组为中心的屏幕,
例如从 Mod Menu 配置屏幕工厂中:
return parent -> CarpetGuiScreens.create(parent, "example_addon");
导入 io.github.piscescup.fabricmc.carpetgui.modmenu.CarpetGuiScreens 并传入你的 Fabric 模组 ID。
从源码构建
使用 JDK 25 和包含的 Gradle wrapper。 主源节点由 versions/mainProject 选择;settings.json 选择活动的 Minecraft 目标。 预处理器从共享源树提供特定版本的源文件。
构建单个目标:
./gradlew :26.2:build
构建所有启用的目标并将其模组 JAR 收集到 build/release/:
./gradlew buildAndGather
为每个启用的目标运行检查:
./gradlew checkAllVersions
在 Windows PowerShell 上,使用 .\gradlew.bat 代替 ./gradlew。各个目标的输出位于 versions/<version>/build/libs/。本地构建默认使用 -SNAPSHOT 后缀;传递 -Prelease=true 以使用发布命名。
致谢
特别感谢 TheCSDev 提供的 Better Statistics Screen,它启发了 Carpet GUI 的 UI 设计,以及 TCDCommons,这个驱动此工作区的 GUI 框架。
还要感谢 Fabric、Carpet 和 Mod Menu 的开发者和维护者,为本项目提供了平台、规则系统和集成工具。ReplayMod Preprocessor 和 Fallen-Breath 的分支 使共享的多版本源树成为可能。
感谢所有测试该模组、报告错误、提出改进建议或贡献代码和翻译的人。
反馈与贡献
欢迎通过 Issues 和 Pull Requests 提交错误报告和贡献。对于错误报告,请包含你的 Minecraft 和 Carpet GUI 版本、相关依赖和附加模组版本、服务器上是否安装了 Carpet GUI,以及重现步骤。截图或相关日志摘录有助于解决界面和兼容性问题。
致谢与许可
Carpet GUI 构建于 Fabric、Carpet 和 TCDCommons 之上,并可选集成 Mod Menu。多版本构建使用 ReplayMod Preprocessor 和 Fallen-Breath 的分支。
本项目的许可证为 GNU Lesser General Public License v3.0。
正在加载版本记录…


正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。