只读常量 ​

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

只读常量可以用于：

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

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

全局变量 ​

vals.global.变量名 / 常量.全局.变量名 读取 global-scripts.yml 的服务器共享变量。它与每张页面自己的 vars.* 相互独立，服务端修改后会自动刷新已打开页面的文字、公式和响应式图片路径。完整声明、修改和路径示例见服务端通用脚本与 Cron。

世界页面绑定实体 ​

跟随世界页面可以读取自己绑定的实体。vals.player.* 始终表示观看页面的玩家；vals.boundEntity.* 表示跟随目标，例如其他玩家、怪物或展示实体。

英文和中文属性不能赋值。目标不在客户端加载范围内、死亡，或页面没有绑定目标时，exists 为 false，字符串为空、数字为 0、布尔值为 false。跟随页面同时隐藏并停止交互，目标重新可见后自动恢复。血量和名称以客户端实际收到的实体数据为准。

文字可填写 {常量.绑定实体.名称} {常量.绑定实体.血量}/{常量.绑定实体.最大血量}；进度条使用 value: vals.boundEntity.health、max: max(1, vals.boundEntity.maxHealth)。完整页面及打开方式见制作第一个世界界面。

ChaUI 槽物品 ​

vals.slots.<模式>.<bind>.<字段> 读取持久槽、临时槽或背包映射槽中的物品。例如 {vals.slots.temporary.offer.name} 会随临时槽 offer 中的物品名称刷新。模式使用 persistent、temporary、mapped；字段包括 itemId、name、count、loreText 和 lore。

也可以通过 getItemName、getItemLore、getItemCount 读取。模式前缀、空槽结果和可直接使用的页面见读取槽位物品。容器替换页面的 containerBinding 则使用本页后文的原版容器物品视图。

玩家基础状态 ​

背包汇总数据 ​

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

主手、副手与盔甲 ​

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

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

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

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

对应的中文写法为：

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

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

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

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

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
    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。点击按钮后，脚本根据主手数量显示或隐藏提示文字。

- 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
  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}, {vals.mouse.y}　左键按下：{vals.mouse.leftDown}

在 timer 或 interval 正文中读取这些字段时，每次回调都会获取当前状态。下面的完整脚本可以放入普通页面的 events.open，每隔至少 500 毫秒在聊天中输出当前鼠标位置和左键状态：

interval("mouse_probe", 500) {
    log("鼠标：{vals.mouse.x}, {vals.mouse.y}，左键按下：{vals.mouse.leftDown}")
}

打开页面后移动鼠标，并按住、松开左键，预期下一次输出随操作变化；关闭页面后自动停止，也可以在其他事件中执行 cancel("mouse_probe") 停止。timeout、debounce 和 sleep/delay 之后同样读取执行时的状态。

如果只在启动时把坐标保存为 vars.startX，这个页面变量会保留当时的值，不会自动跟随鼠标；需要实时判断时，应在回调正文内直接读取 vals.mouse.*。

原版容器物品 ​

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

第 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.<名称>。这些值由服务端解析并下发，客户端只负责读取。

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

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

称号：{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. 未知名称或拼写错误不会创建新常量，请对照本页检查完整路径。

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