地毯 GUI

地毯 GUI

一个用于Carpet及支持的Carpet附加组件的图形化工作区。

Carpet GUI


English(Selected)

浏览规则。整理预设。
面向 Carpet 及受支持的 Carpet 附加模组的图形化工作区。

Loader: Fabric Java: 21 / 25, depending on Minecraft version License: LGPL 3.0

安装 · 快速开始 · 规则组 · 常见问题 · 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 也会在集成服务器上运行,因此无需单独安装服务器端。

安装

  1. 为你的 Minecraft 版本安装 Fabric Loader。
  2. 选择匹配的 Carpet GUI、Fabric API、Carpet 和 TCDCommons JAR。如果你想要 Mod Menu 的快捷方式,请添加 Mod Menu。
  3. 将 JAR 放入游戏实例的 mods 文件夹。
  4. 对于多人游戏中的已确认编辑、同步配置和已验证组推送,还请在服务器上安装匹配的 Carpet GUI 和依赖构建。Mod Menu 仅在客户端需要。
  5. 启动 Minecraft 并加入世界或服务器。

在 Releases 中查找已发布的构建, 或查看 GitHub Actions 以获取可用的开发构建产物。

快速开始

  1. 在游戏中按 F9,或通过 Mod Menu 打开 Carpet GUI。 你可以在 选项 → 控制 中更改按键绑定。
  2. 打开模组页面或 全部规则。
  3. 搜索规则,展开其分类, 并将鼠标悬停在规则上以阅读其描述和可用历史。
  4. 使用规则的开关、选项列表或值字段进行编辑。 当你想将受支持的规则保存为持久服务器默认值时,请使用 设置默认值。
  5. 打开 规则组 将规则收集到可复用的配置中。

[!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 预设

  1. 暂存并提交你想要分享的值。
  2. 点击 导出 HEAD。这会导出最新的已提交快照,未提交的编辑不会包含在文件中。
  3. 将导出的 JSON 文件复制到接收游戏实例的 config/carpet-gui/presets/ 目录中。
  4. 打开 规则组 → 导入预设,然后选择文件或输入其文件名(包括 .json)。
  5. 审核导入组的目标并确认适用的规则。

预设包含组名、标签和规则值。 它们不包含服务器地址、作者身份、本地提交历史和推送状态。 导入会创建一个本地组,并在任何服务器应用之前打开预览。

服务器功能与权限

在双方都安装了匹配的 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。