猹件开发组

Appearance

On this page

只读常量 ​

只读常量是 ChaUI 自动提供的实时数据，统一以 vals 开头。它们可以读取玩家生命、背包、鼠标位置和 PlaceholderAPI 结果，但不能像 vars 一样被脚本修改。

只读常量可以用于：

  • 响应式文字中的 {...}；
  • visibleWhen 与 enabledWhen 条件；
  • 布局和数字表达式；
  • if 条件与脚本赋值右侧。

英文前缀 vals 也可以写成中文 常量。例如 vals.player.health 与 常量.玩家.血量 表示同一个值。

玩家基础状态 ​

英文写法中文写法类型含义
vals.player.health常量.玩家.血量数字当前生命值
vals.player.maxHealth常量.玩家.最大血量数字最大生命值
vals.player.food常量.玩家.饥饿数字当前饥饿值
vals.player.saturation常量.玩家.饱和数字当前饱和度
vals.player.armor常量.玩家.护甲数字当前护甲值
vals.player.experienceLevel常量.玩家.等级数字当前经验等级

背包汇总数据 ​

英文写法中文写法类型含义
vals.player.inventory.heldItemSlot常量.玩家.背包.当前槽位数字当前选中的快捷栏索引，范围为 0～8
vals.player.inventory.emptySlots常量.玩家.背包.空槽位数字36 格主背包中的空槽数
vals.player.inventory.occupiedSlots常量.玩家.背包.已用槽位数字36 格主背包中的非空槽数
vals.player.inventory.totalItemCount常量.玩家.背包.物品总数数字36 格主背包中所有物品的数量总和

这里的“36 格主背包”包含 9 格快捷栏和 27 格普通背包，不包含副手、盔甲槽与合成格。

主手、副手与盔甲 ​

先选择需要读取的位置，再在后面加上物品属性。

英文位置中文位置对应槽位
mainhand主手当前选中的快捷栏槽
offhand副手副手槽
helmet头盔头盔槽
chestplate胸甲胸甲槽
leggings护腿护腿槽
boots靴子靴子槽

每个位置都支持下面四个属性：

英文属性中文属性类型含义
id物品ID字符串命名空间物品 ID，例如 minecraft:diamond_sword
count数量数字当前物品数量
damage损耗数字已损耗的耐久值
maxDamage最大耐久数字最大耐久值

把“位置”和“属性”连起来即可读取完整数据：

text
vals.player.inventory.mainhand.id
vals.player.inventory.mainhand.count
vals.player.inventory.offhand.id
vals.player.inventory.helmet.damage
vals.player.inventory.chestplate.maxDamage

对应的中文写法为：

text
常量.玩家.背包.主手.物品ID
常量.玩家.背包.主手.数量
常量.玩家.背包.副手.物品ID
常量.玩家.背包.头盔.损耗
常量.玩家.背包.胸甲.最大耐久

槽位为空时，id 为 minecraft:air，其余数字属性为 0。id 是字符串，只能用于文字、字符串比较和脚本值，不能直接参与宽高等数字公式。

完整示例：显示玩家和主手状态 ​

下面的页面可以直接保存为 yml。打开后，生命值、快捷栏位置和主手物品会随玩家状态实时变化。

yaml
id: readonly_status
version: 1
title: 只读常量示例
size:
  width: window.width
  height: window.height
coordinateMode: absolute
display:
  mode: screen
  screen:
    dimBackground: false
vars: {}
papi:
  refreshTicks: 20
  values: {}
events: {}
methods: {}
elements:
  - id: status_text
    type: text
    visible: true
    enabled: false
    pointerEvents: pass
    z: 10
    layout:
      x: 20
      y: 20
      width: 300
      height: 50
    text:
      value: "生命：{vals.player.health} / {vals.player.maxHealth}\n快捷栏：{vals.player.inventory.heldItemSlot + 1}\n主手：{vals.player.inventory.mainhand.id} × {vals.player.inventory.mainhand.count}"
      color: "#FFFFFF"
      textSize: 1
      textLineLength: 0
      revealIntervalMs: 0
      align: left

heldItemSlot 从 0 开始，所以示例加 1 后会显示玩家习惯的第 1～9 格。物品 ID 不做运算，直接作为文字显示。

完整示例：点击后判断主手是否有物品 ​

下面两个组件可以放进页面的 elements。点击按钮后，脚本根据主手数量显示或隐藏提示文字。

yaml
- id: check_item
  type: button
  visible: true
  enabled: true
  pointerEvents: auto
  z: 10
  layout:
    x: 20
    y: 80
    width: 100
    height: 20
  button:
    label: 检查主手
    textSize: 1
    textX: 6
    textY: 6
    textLineLength: 0
    revealIntervalMs: 0
    align: left
  events:
    leftClick: |-
      if vals.player.inventory.mainhand.count > 0 {
        component("item_tip").visible = true
      } else {
        component("item_tip").visible = false
      }

- id: item_tip
  type: text
  visible: false
  enabled: false
  pointerEvents: pass
  z: 10
  layout:
    x: 130
    y: 85
    width: 220
    height: 16
  text:
    value: "主手物品：{vals.player.inventory.mainhand.id}"
    color: "#FFFFFF"
    textSize: 1
    textLineLength: 0
    revealIntervalMs: 0
    align: left

鼠标状态 ​

鼠标坐标使用 Minecraft GUI 缩放坐标，与组件 layout.x、layout.y 的坐标口径一致。

英文写法中文写法类型含义
vals.mouse.x常量.鼠标.x数字当前鼠标 X 坐标
vals.mouse.y常量.鼠标.y数字当前鼠标 Y 坐标
vals.mouse.leftDown常量.鼠标.左键按下布尔值鼠标左键是否正按下
vals.mouse.rightDown常量.鼠标.右键按下布尔值鼠标右键是否正按下
vals.mouse.middleDown常量.鼠标.中键按下布尔值鼠标中键是否正按下
text
鼠标：{vals.mouse.x}, {vals.mouse.y}　左键按下：{vals.mouse.leftDown}

原版容器物品 ​

只有 display.mode: container 的替换页面会提供 vals.container.*。每个真实槽位与绑定组件都有 itemId、count、name、loreText 四个只读字段。

text
第 14 格名称：{vals.container.slots.container_13.name}
按钮当前 Lore：{vals.container.components.menu_button.loreText}

空槽的 itemId 为 minecraft:air、count 为 0，名称和 Lore 为空。组件通过脚本动态改绑后，vals.container.components.<组件ID>.* 会自动跟随新槽位。

这些值用于显示与客户端页面逻辑。服务端发奖励、扣物品或判断业务条件时，仍应读取服务端真实容器。详细映射见槽位、按钮与物品信息。

PlaceholderAPI 常量 ​

页面根级 papi.values 可以把服务端 PlaceholderAPI 模板映射为 vals.papi.<名称>。这些值由服务端解析并下发，客户端只负责读取。

yaml
papi:
  refreshTicks: 20 # 每 20 tick 刷新一次，允许 5 至 1200
  values:
    balance: "%vault_eco_balance%"
    prefix: "%luckperms_prefix%"

配置后可以在文字中直接使用：

text
称号：{vals.papi.prefix}　余额：{vals.papi.balance}

values 左侧名称由页面作者定义。例如 balance 对应 vals.papi.balance。服务端没有安装 PlaceholderAPI 或占位符扩展不可用时，ChaUI 不会因此被禁用，但对应表达式可能保留原占位内容。

使用限制 ​

  1. vals 只能读取，不能写成 vals.player.health = 20。
  2. 玩家背包和鼠标常量来自当前客户端，适合界面显示、布局和交互提示。
  3. 发奖励、扣物品、执行购买或判断权限时，业务插件必须重新读取服务端真实状态，不能信任客户端常量。
  4. id 是字符串；count、damage、maxDamage 等数字才可以参与数学公式。
  5. 未知名称或拼写错误不会创建新常量，请对照本页检查完整路径。

需要操作真实背包槽位时，请阅读背包映射表。需要学习 {...} 的实时文字写法，请阅读响应式变量与实时文字；需要修改页面自己的状态，请阅读变量与条件。