ICustomMenu GUI 配置教程

作者: JoBackRer
Icon发表于2026-01-27
Icon更新于2026-02-07
Icon总字数: 1.6k字
Icon阅读时长: 5分钟
Iconicm
Icon

ICustomMenu GUI 配置教程

本模组允许通过数据包（Datapack）完全自定义游戏内界面。配置文件路径：
data/<命名空间>/custom_menus/<文件名>.json

1. 核心属性 (Root Properties)

属性 类型 描述 示例
keybind String 快捷键 ID。 "key.keyboard.k"
animation_direction String 滑入方向 (left, right, top, bottom)。 "left"
background Object 背景贴图与区域定义。 见下文
components Array 界面组件列表。 见下文

2. 背景配置 (Background)

1
2
3
4
5
6
7
8
9
"background": {
  "texture": "icustommenu:textures/gui/bg.png",
  "x": 0, "y": 0,
  "width": 150,    // -1 为全屏宽
  "height": -1,    // -1 为全屏高
  "nine_slice": {  // 防止贴图拉伸变形
    "left": 4, "top": 4, "right": 4, "bottom": 4
  }
}

A. 文字组件 (text)

支持样式代码（§）、动态缩放以及动态占位符。

1
2
3
4
5
6
7
{
  "id": "player_info",
  "type": "text",
  "content": "§e玩家: %player_name% §7| §c血量: %health%/%max_health%",
  "x": 10, "y": 20,
  "color": "#FFFFFF" // 支持 6 位 (#RRGGBB) 或 8 位 (#AARRGGBB) 十六进制颜色
}

支持的占位符：

  • %player_name%: 玩家名称
  • %health%: 当前血量
  • %max_health%: 最大血量
  • %food%: 饥饿值
  • %level%: 等级
  • %x%, %y%, %z%: 坐标
  • [联动] ClassBioArsenal:
    • %cba_profession%: 当前职业名称
    • %cba_level%: 职业等级
    • %cba_exp%: 当前经验
    • %cba_max_exp%: 升级所需经验
    • %cba_exp_progress%: 经验百分比 (例如 45.00%)
  • [联动] PlayerAffixes:
    • %pa_talents_count%: 已解锁天赋总数
    • %pa_has_talent:<id>%: 是否拥有特定天赋 (true/false)
    • %pa_has_affix:<id>%: 是否拥有特定词条 (true/false)

B. 基础按钮 (button)

自定义背景色的矩形按钮。

1
2
3
4
5
6
7
8
{
  "id": "btn_simple",
  "type": "button",
  "text": "普通按钮",
  "x": 10, "y": 50,
  "width": 100, "height": 20,
  "action": { "type": "close" }
}

C. 原版样式按钮 (vanilla_button)

使用 Minecraft 标准按钮贴图。

1
2
3
4
5
6
7
8
{
  "id": "btn_vanilla",
  "type": "vanilla_button",
  "text": "原版按钮",
  "x": 10, "y": 80,
  "width": 100, "height": 20,
  "action": { "type": "command", "value": "/help" }
}

D. 图片按钮 (image_button)

完全自定义贴图的按钮，支持叠加文字。

1
2
3
4
5
6
7
8
9
10
11
{
  "id": "btn_img",
  "type": "image_button",
  "x": 10, "y": 110,
  "width": 32, "height": 32,
  "texture": "icustommenu:textures/gui/btn_normal.png",
  "hover_texture": "icustommenu:textures/gui/btn_hover.png",
  "text": "点击我",        // [可选] 按钮上的文字
  "text_color": "#FFFFFF", // [可选] 文字颜色
  "action": { "type": "server_event", "value": "open_bank" }
}

E. 静态图片 (image)

用于装饰或展示贴图。

1
2
3
4
5
6
7
{
  "id": "icon_diamond",
  "type": "image",
  "texture": "minecraft:textures/item/diamond.png",
  "x": 150, "y": 20,
  "width": 32, "height": 32
}

F. 玩家模型 (player_model)

渲染 3D 玩家小人，会跟随鼠标旋转。

1
2
3
4
5
6
{
  "id": "my_avatar",
  "type": "player_model",
  "x": 200, "y": 150,
  "size": 50 // 模型大小
}

G. 线框组件 (wireframe / rounded_wireframe)

用于勾勒区域或装饰。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "id": "box_1",
  "type": "wireframe",
  "x": 10, "y": 10,
  "width": 100, "height": 50,
  "color": "#FFD700", // 金色
  "thickness": 1      // 线条粗细
},
{
  "id": "box_rounded",
  "type": "rounded_wireframe",
  "x": 120, "y": 10,
  "width": 100, "height": 50,
  "color": "#00FFFF",
  "thickness": 1,
  "radius": 5         // 圆角半径
}

H. 线条组件 (horizontal_line / vertical_line)

简单的分割线。

1
2
3
4
5
6
7
8
{
  "id": "sep",
  "type": "horizontal_line",
  "x": 10, "y": 70,
  "width": 200,
  "color": "#555555",
  "thickness": 1
}

I. 进度条 (progress_bar)

展示数值进度（如血量、经验）。

1
2
3
4
5
6
7
8
9
{
  "id": "hp_bar",
  "type": "progress_bar",
  "x": 10, "y": 80,
  "width": 100, "height": 5,
  "value": "%health%/%max_health%", // 支持占位符或 0-1 的浮点数
  "bg_color": "#330000",
  "fill_color": "#FF0000"
}

J. 物品渲染 (item)

直接渲染 Minecraft 物品图标。

1
2
3
4
5
6
7
8
{
  "id": "diamond_icon",
  "type": "item",
  "item_id": "minecraft:diamond",
  "x": 10, "y": 100,
  "count": 1,          // [可选] 数量
  "show_overlay": true // [可选] 是否显示数量/耐久条
}

4. 全局属性 (Global Properties)

所有组件都支持以下属性：

属性 类型 描述
tooltip String / Array 鼠标悬停时显示的提示文字。支持占位符。如果是数组，则显示为多行。
color String 颜色字符串。支持 #RRGGBB 或 #AARRGGBB。

示例:

1
2
3
4
5
{
  "type": "image",
  "texture": "...",
  "tooltip": ["§b钻石", "§7极其珍贵的矿石"]
}

5. 动作系统 (Action System)

类型 描述 示例值 (value)
command 以玩家身份执行指令。 "/spawn"
close 关闭当前 GUI。 (无需值)
server_event 触发后端 Java 事件。 "my_mod_event"
custom [API] 触发通过 API 注册的自定义动作。 "my_custom_action"
switch_menu [高级] 切换子菜单内容。 "icustommenu:sub_page"

5. 动作前置要求 (Action Requirements)

您可以为按钮动作添加 requirements，只有满足条件时动作才会执行。

物品消耗示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "id": "btn_buy",
  "type": "vanilla_button",
  "text": "花费1钻石执行指令",
  "action": {
    "type": "command",
    "value": "/give @s apple 64",
    "requirements": [
      {
        "type": "item",
        "id": "minecraft:diamond",
        "amount": 1,
        "consume": true // 是否消耗物品
      }
    ]
  }
}

6. 联动模组扩展 (Mod Integration)

当安装了以下模组时，将自动解锁额外的占位符与动作要求。

A. ClassBioArsenal (职业系统)

占位符:

  • %cba_profession%: 当前职业名称 (如 berserker)
  • %cba_level%: 职业等级
  • %cba_exp%: 当前经验
  • %cba_max_exp%: 升级所需经验
  • %cba_exp_progress%: 经验百分比 (例如 45.00%)

动作要求 (requirements):

  • 职业检查 (cba_profession): 只有指定职业的玩家才能执行动作。
    1
    2
    3
    4
    {
      "type": "cba_profession",
      "id": "berserker"
    }
  • 等级检查 (cba_level): 只有达到指定等级的玩家才能执行动作。
    1
    2
    3
    4
    {
      "type": "cba_level",
      "min": 10
    }

B. PlayerAffixes (天赋系统)

占位符:

  • %pa_talents_count%: 已解锁天赋总数
  • %pa_has_talent:<id>%: 是否拥有特定天赋 (true/false)
  • %pa_has_affix:<id>%: 是否拥有特定词条 (true/false)

动作要求 (requirements):

  • 天赋检查 (pa_talent): 检查是否解锁了特定天赋。
    1
    2
    3
    4
    {
      "type": "pa_talent",
      "id": "playeraffixes:strength_boost"
    }
  • 词条检查 (pa_affix): 检查是否拥有特定词条。
    1
    2
    3
    4
    {
      "type": "pa_affix",
      "id": "playeraffixes:lifesteal"
    }

7. 嵌套菜单与路由 (Nested Menus / Router)

嵌套菜单允许您在主界面（如侧边栏）不变的情况下，动态切换中间的内容区域。

步骤 1: 定义主菜单 (main.json)

主菜单中定义导航按钮，并指定子菜单的偏移位置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "components": [
    {
      "type": "button",
      "text": "切换到首页",
      "action": {
        "type": "switch_menu",
        "value": "icustommenu:home_sub",
        "offset_x": 160, // 子菜单相对于主菜单 X 轴偏移
        "offset_y": 20   // 子菜单相对于主菜单 Y 轴偏移
      }
    }
  ]
}

步骤 2: 定义子菜单 (home_sub.json)

子菜单中的坐标（x, y）是相对于主菜单中定义的 offset 的。

1
2
3
4
5
6
7
8
9
{
  "components": [
    {
      "type": "text",
      "content": "这是子菜单内容",
      "x": 0, "y": 0 // 实际显示在 (160, 20)
    }
  ]
}

7. 自定义动作 API (Custom Actions API)

custom 类型的动作允许您通过 Java 代码或 KubeJS 脚本注册复杂的逻辑。

JSON 配置

1
2
3
4
5
6
7
8
{
  "type": "button",
  "text": "触发脚本",
  "action": {
    "type": "custom",
    "value": "my_scripted_action"
  }
}

KubeJS 注册示例 (Server Script)

在 kubejs/server_scripts/ 目录下创建脚本：

1
2
3
4
5
6
7
8
// 获取 API 类
const CustomMenuAPI = Java.loadClass('site.backrer.icustommenu.api.CustomMenuAPI')

// 注册动作
CustomMenuAPI.registerAction('my_scripted_action', (player) => {
    player.tell('你触发了来自 KubeJS 的自定义动作！')
    // 执行任何逻辑，如给予物品、传送、修改数据等
})

8. 开发者贴士

  • 热加载: 修改 JSON 后，在游戏内输入 /custommenu reload 即可立即看到效果。
  • 贴图路径: 推荐放在 assets/<命名空间>/textures/gui/ 下。
  • 透明度: 贴图支持透明通道（PNG）。
  • KubeJS 联动: 确保已安装 KubeJS，并使用 CustomMenuAPI 进行逻辑扩展。
Icon喜欢这篇作品的话，奖励一下我吧～
💗感谢你的喜欢与支持！
致谢名单
本作品由 JoBackRer 于 2026-01-27 18:00:22 发布
作品地址：ICustomMenu GUI 配置教程
除特别声明外，本站作品均采用 CC BY-NC-SA 4.0 许可协议，转载请注明来自 JoBackRer の blog
Logo