制作快捷栏 HUD ​

这篇教程会制作一条替换原版快捷栏的 HUD。它会实时显示玩家 9 个快捷栏槽，用浅色矩形标出当前选择，并在上方显示主手物品 ID 和数量。

开始前请先完成服务端安装与客户端安装。

先取得完整示例 ​

下载快捷栏HUD.yml，放到服务端：

plugins/ChaUI/pages/快捷栏HUD.yml

文件名和页面根级 id: 快捷栏HUD 必须一致。示例不依赖任何外部图片，放入后即可显示。

第一步：设置 HUD 页面 ​

示例使用：

display:
  mode: hud
  hud:
    always: true
    replaces:
      - hotbar

always: true 表示玩家进入服务器后自动显示。hotbar 表示隐藏原版快捷栏，由当前页面接管这一区域。如果只想叠加新内容而保留原版快捷栏，就删除 replaces 中的 hotbar。

第二步：映射 9 个快捷栏槽 ​

第一个槽位的关键配置如下：

- id: hotbar_0
  type: item_slot
  visible: true
  enabled: true
  pointerEvents: auto
  z: 2
  layout:
    x: 'window.width * 0.5 - 90 + 0 * 20'
    y: 'window.height - 23'
    width: '18'
    height: '18'
  itemSlot:
    bind: backpack_0
    mode: mapped
    allowPut: true
    allowTake: true

后面 8 个槽依次使用 backpack_1 到 backpack_8，并把 X 公式中的数字改为 1 到 8。全部位置以 window.width * 0.5 为中心，因此改变窗口宽度后仍会居中。

第三步：让选中框跟随当前槽位 ​

示例只用一个矩形，通过实时常量计算 X：

layout:
  x: 'window.width * 0.5 - 90 + vals.player.inventory.heldItemSlot * 20'
  y: 'window.height - 23'
  width: '18'
  height: '18'
rect:
  color: '#FFFFFF'

heldItemSlot 的范围是 0～8。玩家滚轮切换主手时，矩形会自动移动，不需要 timer 或点击脚本。

第四步：显示主手信息 ​

文字内容写成：

主手：{vals.player.inventory.mainhand.id} × {vals.player.inventory.mainhand.count}

花括号中的值会在每次渲染时重新读取。空手时 ID 显示为 minecraft:air，数量为 0。

第五步：重载并查看 ​

/chaui reload

因为示例配置了 always: true，重载后 HUD 会自动打开。也可以手动执行：

/chaui open <玩家> 快捷栏HUD

进入游戏后检查：

1. 原版快捷栏已经隐藏。
2. 9 个槽中的物品与真实快捷栏一致。
3. 滚轮切换槽位时高亮立即移动。
4. 拿起、消耗或更换主手物品时，上方文字立即变化。
5. 调整窗口宽度后快捷栏仍保持居中。

全部 bind 的含义见背包映射表。

按住 ALT 操作 HUD ​

在游戏中按住 左 ALT，鼠标就会出现，可以移动到 HUD 上点击按钮或拖动控件；松开 ALT 后，鼠标立即回到游戏，继续控制视角。呼出鼠标期间，点击空白区域不会攻击或使用物品，滚轮也不会切换快捷栏。

可以在游戏的“选项 → 控制 → 按键绑定”中搜索 ChaUI：按住呼出 HUD 鼠标，把它改成习惯的按键。该功能采用按住操作，无需先打开菜单，也不需要修改 HUD 的页面配置。

打开菜单、断开连接或 Alt+Tab 切出窗口时，本次呼出会结束。回到游戏后，先松开呼出键，再重新按住即可继续操作；正在进行的 HUD 拖拽也会随本次呼出结束。

在手机启动器中操作 HUD ​

FCL、ZL2 等手机启动器可以把手指操作转换成游戏能识别的虚拟鼠标。进入菜单、打开页面和点击普通按钮时，直接使用启动器的虚拟鼠标即可；页面编辑器、容器页面和原版替换页面也沿用同样的操作方式。

进入游戏后，单指可以点按 HUD 按钮，也可以按住后拖动仍在移动的控件。手指松开时，按钮会按照原来的 press、release 和 click 事件执行，页面脚本和物品槽规则不需要另写一份。HUD 空白区域会把操作交还给游戏本身。

建议在启动器的控制布局中打开“虚拟鼠标”或“鼠标层”，并保留一个返回键。部分布局在进入游戏后会隐藏绝对鼠标位置，这时可以给页面配置的 KEY_* 事件绑定启动器按键，作为按钮操作的备用方式。例如页面按钮可以继续使用：

events:
  click: "KEY_ENTER"

手机触控第一版按单指操作设计，同时拖动镜头和 HUD 控件时，优先使用启动器的鼠标层切换到 HUD 操作；多指手势和启动器私有手势由启动器自身处理。