GUI API

GUI API — Fabric 1.21.8

一个 Fabric 模组，允许数据包通过 JSON 文件定义和打开箱子 GUI。
客户端无需安装模组。无需宏。除 Fabric API 外无其他外部依赖。

---

安装

1. 将 guiapi-1.0.4.jar 放入你的 mods/ 文件夹。
2. 将你的数据包放入 world/datapacks/。
3. 运行 /reload 或 /guiapi reload。

可选安装 Mod Menu 以便在游戏中查看已加载的 GUI 并进行可视化编辑！

---

命令

命令	描述
/guiapi	显示帮助（等同于 /guiapi help）
/guiapi open <id>	为自己打开一个 GUI
/guiapi open <id> <targets>	为目标玩家打开一个 GUI
/guiapi list	列出所有已加载的 GUI 定义
/guiapi reload	重新加载所有数据包资源（包括 GUI）
/guiapi var get <player> <key>	获取玩家的运行时变量
/guiapi var set <player> <key> <value>	设置玩家的运行时变量
/guiapi var clear <player>	清除玩家的所有运行时变量
/guiapi help	在游戏中显示命令和 JSON 字段参考

需要权限等级 2（OP），默认要求（可在 Mod Menu 中配置）。

---

文件位置

GUI 定义文件存放于：

data/<namespace>/gui/<name>.json

命令中使用的 GUI ID 为 <namespace>:<name> —— 与 gui/ 下的文件路径对应。

---

JSON 架构

顶层字段

字段	类型	默认值	描述
title	string	"GUI"	容器标题。支持 § 颜色代码和占位符。
rows	int 1–6	3	行数（每行 9 个槽位）。
tick_rate	int	0	自动刷新间隔（以 tick 为单位，例如 20 = 1 秒）。设为 0 可禁用。
close_on_move	boolean	false	若为 true，当玩家走远（> 1.5 格）时关闭界面。
filler	object	—	背景填充配置（见下文）。
on_open	action[]	[]	GUI 打开时执行的动作。
on_close	action[]	[]	GUI 关闭时执行的动作（任何原因）。
buttons	button[]	[]	按钮定义列表。

填充字段

物品栏中的任何空槽位都会自动填充此背景物品。

"filler": {
  "item": "minecraft:gray_stained_glass_pane",
  "name": " ",
  "glint": false,
  "hide_tooltip": true
}

按钮字段

字段	类型	默认值	描述
slot	int	0	从零开始的槽位索引（0–rows*9-1）。
page	int	0	此按钮所在的页面。
item	string	"minecraft:stone"	物品 ID。
name	string	""	显示名称。支持颜色代码和占位符。
lore	string[]	[]	Lore 文本行。支持占位符。
glint	boolean	false	应用附魔闪光效果。
amount	string	"1"	物品堆叠数量（支持 {var:counter} 等占位符）。
hide_tooltip	boolean	false	隐藏悬浮提示中的物品名称和 Lore。
hide_additional_tooltip	boolean	false	隐藏属性、附魔和杂乱信息。
custom_model_data	int 或 object	—	自定义模型数据组件（支持旧版 int 和 1.21.4+ 复合对象）。
item_model	string	—	自定义物品模型组件 ID（1.21.2+）。
click_type	string	"any"	触发动作的点击类型：any · left · right · shift
condition	object	—	可见性条件（见下文）。
actions	action[]	[close]	点击时按顺序执行的动作。支持 "delay": int（tick 数）。
toggle	object	—	开关定义 — 替换 item/actions（见下文）。

---

占位符

支持在 title、按钮 name、lore、message 值和 run_command 值中使用。

占位符	解析为
{player}	玩家的显示名称
{gui}	GUI ID（namespace:name）
{page}	当前页索引（从 0 开始）
{page1}	当前页索引（从 1 开始）
{pages}	总页数
{score:objective}	玩家在指定计分板目标中的分数
{var:key}	玩家的运行时变量 key（未设置则为空字符串）

---

动作类型

任何动作都可以通过在其 JSON 块中添加 "delay": int（以 tick 为单位）来延迟执行。

类型	value 格式	run_with	描述
run_command	命令字符串	player · console	运行命令。默认：player。支持占位符。
close	—	—	关闭 GUI。
refresh	—	—	动态刷新当前 GUI 物品栏（不关闭/闪烁）。
open_gui	namespace:name	—	关闭并打开另一个 GUI。
message	文本字符串	—	向玩家发送聊天消息。支持占位符。
action_bar	文本字符串	—	直接向玩家发送操作栏消息。
sound	sound.id 或 sound.id:volume:pitch	—	播放声音。音量/音调默认为 1.0。支持占位符。
set_score	objective:value	—	直接设置玩家的计分板目标分数（支持占位符）。
add_score	objective:value	—	直接增加玩家的计分板目标分数。
sub_score	objective:value	—	直接减少玩家的计分板目标分数。
take_item	itemId:amount	—	从玩家物品栏中扣除指定数量的物品。
add_effect	effect_id:duration:amplifier:particles	—	给予玩家状态效果（时长以秒为单位，粒子 true/false）。
remove_effect	effect_id	—	移除玩家身上的特定状态效果。
clear_effects	—	—	清除玩家身上的所有状态效果。
set_var	新值	—	设置一个运行时变量。需要 "var": "key"。
add_var	要加上的整数	—	为运行时变量添加一个整数。需要 "var": "key"。
sub_var	要减去的整数	—	从运行时变量中减去一个整数。需要 "var": "key"。
reset_var	—	—	删除单个运行时变量。需要 "var": "key"。
clear_vars	—	—	删除该玩家的所有运行时变量。
next_page	—	—	转到下一页。
prev_page	—	—	转到上一页。
goto_page	页索引（字符串）	—	跳转到指定页面。

---

条件类型

条件控制按钮的可见性。隐藏的按钮无法点击。

类型	value 格式	可见条件
has_tag	标签名称	玩家拥有该计分板标签
not_tag	标签名称	玩家没有该计分板标签
score_gt	"objective:threshold"	玩家的分数 > 阈值
score_lt	"objective:threshold"	玩家的分数 < 阈值
score_eq	"objective:value"	玩家的分数 == 值
var_eq	"key:value"	运行时变量 key 等于 value（字符串比较）
var_gt	"key:value"	运行时变量 key（int）> value
var_lt	"key:value"	运行时变量 key（int）< value
var_set	key	运行时变量 key 已设置（任意值）
has_item	"itemId:amount"	玩家物品栏中至少拥有 amount 个 itemId
not_item	"itemId:amount"	玩家物品栏中少于 amount 个 itemId
level_gt	value	玩家的经验等级 > 值
level_lt	value	玩家的经验等级 < 值
health_gt	value	玩家的当前生命值 > 值
health_lt	value	玩家的当前生命值 < 值
food_gt	value	玩家的饥饿值 > 值
food_lt	value	玩家的饥饿值 < 值

---

开关按钮

开关按钮根据玩家身上的计分板标签显示不同的物品/名称/Lore/动作。将 item 和 actions 字段替换为 toggle 对象。

字段	类型	默认值	描述
tag	string	""	存储开/关状态的计分板标签。
item_on / item_off	string	青绿/灰色染料	每个状态下显示的物品。
name_on / name_off	string	§a已启用 / §7已禁用	每个状态下的显示名称。
lore_on / lore_off	string[]	[]	每个状态下的 Lore。
glint_on / glint_off	boolean	false	每个状态下的闪光效果。
actions_on	action[]	[tag @s remove <tag>]	开启状态下点击时执行的动作（关闭开关）。
actions_off	action[]	[tag @s add <tag>]	关闭状态下点击时执行的动作（打开开关）。

开关动作也完全支持多动作引擎（在可视化编辑器中以 ; 分隔）。

---

客户端功能（可选）

在客户端安装此模组可解锁强大且精美优化的用户体验功能：

1. 游戏内 GUI 编辑器

• 打开 Mod Menu 配置界面即可看到已加载的 GUI 列表。
• 点击任意 GUI 即可打开 GUI 编辑器界面！
• 可视化编辑 GUI 的 title、rows、tick_rate、close_on_move 和背景 filler。
• 管理按钮列表、添加新按钮，并编辑槽位、物品、数量、闪光、Lore（使用 ; 分隔）、多个动作和开关属性。
• 点击 应用并返回 打开 GUI 保存加载界面，该界面会在服务器上找到目标数据包文件夹，安全地将 JSON 写入磁盘，并重新加载 API 定义。重新加入时不会丢失任何编辑！

2. 原生键位绑定

与 Minecraft 官方控制菜单（选项 > 控制 > 按键绑定 > GUI API）原生集成：

• 接受规则（打开 GUI）： 打开默认欢迎 GUI（默认为 G）。

---

示例

请参阅仓库源码中更新的 example-datapack 目录，其中包含精美完善且注释充分的示例，演示了自动刷新时钟、直接计分板交易、状态效果控制器和自定义视觉模型！

---

构建

chmod +x gradlew
./gradlew build
# 输出：build/libs/guiapi-1.0.4.jar

需要 Java 21。

---

许可证

MIT — 参见 LICENSE。