猹件开发组ChaUI Script 速查表
本页适合已经写过 ChaUI Script、需要快速确认函数名、参数和适用范围的页面作者。第一次接触脚本时，建议先阅读脚本简介和语法与事件，再把本页当作随手查询的目录。
表格中的“脚本”指组件事件、页面事件和自定义方法；“确定性表达式”包括响应式文字、布局公式与页面条件，但具体可用函数仍以各行说明为准。
变量、常量与运算符
| 英文写法 | 中文写法 | 参数 | 返回值或效果 | 可用范围 | 详细说明 |
|---|---|---|---|---|---|
vars.name | 变量.name | 页面变量名 | 读取或修改当前页面会话变量 | 脚本、表达式 | 默认值写在页面根级 vars；详见变量与条件。 |
global.name | — | 已声明的全局变量名 | 读取或修改服务器共享变量 | 服务端通用脚本 | 在 global-scripts.yml 的 globals 声明；必须保持类型。详见全局变量。 |
vals.global.name | 常量.全局.name | 已声明的全局变量名 | 读取当前共享值 | 页面脚本、表达式 | 页面只读，服务端修改后自动更新；可用于文字、条件和响应式路径。 |
vals.boundEntity.* | 常量.绑定实体.* | 绑定实体字段 | 名称、血量、最大血量、位置等 | 跟随模式的世界页面 | 字段见只读常量，完整页面和指令见实体跟随。 |
vals.papi.name | 常量.papi.name | 已登记的 PAPI 名称 | 当前 PAPI 字符串 | 脚本、表达式 | PAPI 原始结果是字符串，可直接按真值规则判断或显式转换。 |
vals.player.* | 常量.玩家.* | 玩家字段 | 数字或物品视图 | 脚本、表达式 | 玩家、背包、装备和鼠标字段见只读常量。 |
true / false / null | 相同 | 无 | 布尔值或空值 | 脚本、表达式 | 字符串必须加引号；null 常用于解除父级或容器绑定。 |
+ - * / % | 相同 | 左值、右值 | 数字；+ 也可拼接字符串 | 脚本、表达式 | 字符串拼接整数时不会附加 .0。 |
== != > >= < <= | 相同 | 左值、右值 | 布尔值 | 脚本、条件 | 比较值是否相等或大小关系。 |
! && || | 相同 | 一个或两个值 | 布尔值 | 脚本、条件 | 使用统一真值规则；"0" 和 "false" 为假。 |
value[index] | 相同 | 从 0 开始的整数 | 列表项或 null | 有列表上下文时 | 主要用于 item.lore[0]；越界返回 null。 |
槽位物品读取
| 英文写法 | 中文写法 | 返回值或效果 |
|---|---|---|
getItemName("temporary:offer") | 获取物品名("temporary:offer") | 名称字符串，空槽为空字符串 |
getItemLore("temporary:offer", 0) | 获取物品Lore("temporary:offer", 0) | 从 0 开始的某行 Lore，不存在时为空字符串 |
getItemCount("temporary:offer") | 获取物品数量("temporary:offer") | 逻辑数量，空槽为 0 |
vals.slots.temporary.offer.name | 常量.槽位.temporary.offer.name | 随物品同步刷新的只读字段；另有 itemId/id/count/lore/loreText |
用于当前客户端页面的脚本和表达式。函数的第一个参数必须是固定字符串，使用槽位 bind；省略模式时默认 persistent，临时和映射槽需明确使用 temporary: / mapped:。完整示例和原版容器区别见读取槽位物品。
条件、循环与延时
| 英文写法 | 中文写法 | 参数 | 返回值或效果 | 可用范围 | 详细说明 |
|---|---|---|---|---|---|
if condition { ... } else { ... } | 如果 condition { ... } 否则 { ... } | 条件、两个代码块 | 只执行命中的分支 | 脚本 | else 可省略。 |
repeat(count, index) { ... } | 重复(count, index) { ... } | 次数、可选索引变量、代码块 | 有界重复执行 | 脚本 | 完整限制见循环与计时器。 |
timer(name, ticks) { ... } | 计时器(name, ticks) { ... } | 名称、tick 间隔、代码块 | 周期执行 | 脚本 | 同名任务重启；20 tick 通常约为 1 秒；每次回调刷新只读常量。 |
task(name) { ... } | 任务(name) { ... } | 名称、一次性代码块 | 立即启动，并允许延迟部分跨页面关闭完成 | 顶层脚本 | 只允许一个顶层 sleep/delay；延迟后只允许经过服务端确认的页面与指令动作。 |
stopTimer(name) | 停止计时器(name) | 名称 | 停止 tick 计时器 | 脚本 | 旧接口保留兼容。 |
sleep(name, milliseconds) | 等待(name, milliseconds) | 名称、毫秒 | 暂停当前执行链后继续 | 脚本 | 恢复时刷新只读常量；取消后不会恢复后续语句。 |
delay(milliseconds) | 延迟(milliseconds) | 毫秒 | 无名暂停当前执行链后继续 | 脚本 | 无需名称，不能用 cancel 取消；适合 repeat 逐轮等待。 |
timeout(name, milliseconds) { ... } | 延时(name, milliseconds) { ... } | 名称、毫秒、代码块 | 到期执行一次 | 脚本 | 毫秒范围为 1 至 3600000。 |
interval(name, milliseconds) { ... } | 间隔(name, milliseconds) { ... } | 名称、毫秒、代码块 | 按毫秒周期执行 | 脚本 | 首次回调等待完整间隔；每次回调刷新只读常量。 |
debounce(name, milliseconds) { ... } | 防抖(name, milliseconds) { ... } | 名称、毫秒、代码块 | 静默期结束执行最后一次 | 脚本 | 重复调用会重置截止时间。 |
throttle(name, milliseconds) { ... } | 节流(name, milliseconds) { ... } | 名称、毫秒、代码块 | 窗口首次立即执行 | 脚本 | 窗口内后续调用被忽略，无尾随执行。 |
cancel(name) | 取消(name) | 名称 | 取消同名毫秒任务、timer 或节流门 | 脚本 | 页面关闭时所有任务也会自动释放。 |
类型与通用函数
| 英文写法 | 中文写法 | 参数 | 返回值或效果 | 可用范围 | 详细说明 |
|---|---|---|---|---|---|
toString(value) | 转字符串(value) | 一个标量 | 字符串 | 脚本、确定性表达式 | 数字使用适合显示的格式；规则见变量与条件。 |
toNumber(value) | 转数字(value) | 数字、布尔值或数字字符串 | 数字 | 脚本、确定性表达式 | 空白、普通文本和 null 会失败。 |
toInteger(value) | 转整数(value) | 可转数字的值 | 向 0 截断的安全整数 | 脚本、确定性表达式 | 范围为 ±9007199254740991。 |
toBoolean(value) | 转布尔(value) | 任意运行时值 | 布尔值 | 脚本、确定性表达式 | 识别数字和字符串形式的 0/1/true/false。 |
contains(value, part) | 对象方法相同 | 字符串或列表、目标值 | 布尔值 | 脚本、声明式条件 | 也可写 value.contains(part)。 |
startsWith(value, prefix) | 对象方法相同 | 字符串、前缀 | 布尔值 | 脚本、声明式条件 | 也可写 value.startsWith(prefix)。 |
endsWith(value, suffix) | 对象方法相同 | 字符串、后缀 | 布尔值 | 脚本、声明式条件 | 也可写 value.endsWith(suffix)。 |
hasPermission("node") | 有权限("node") | 一个权限节点文字 | 布尔值 | 脚本、声明式条件 | 节点必须直接写在引号中；结果未同步时按没有权限处理。服务端业务仍会独立校验。 |
数学函数
| 英文写法 | 中文写法 | 参数 | 返回值或效果 | 可用范围 | 详细说明 |
|---|---|---|---|---|---|
trunc(value) | 取整(value) | 1 | 向 0 取整数字 | 脚本、确定性数字表达式 | -1.8 得到 -1。 |
round(value[, digits]) | 四舍五入(...) | 1 或 2 | 四舍五入数字 | 脚本、确定性数字表达式 | 小数位为 0 至 12。 |
floor(value) / ceil(value) | 向下取整 / 向上取整 | 1 | 取整数字 | 脚本、确定性数字表达式 | 分别朝负无穷和正无穷。 |
fixed(value, digits) | 保留小数(value, digits) | 2 | 固定小数位字符串 | 脚本、响应式文字 | 返回文字，不可写入纯数字公式或条件。 |
abs(value) / sign(value) | 绝对值 / 符号 | 1 | 数字 | 脚本、确定性数字表达式 | sign 返回 -1、0 或 1。 |
min(a, ...) / max(a, ...) | 最小值 / 最大值 | 1 至 32 | 数字 | 脚本、确定性数字表达式 | 返回最小值或最大值。 |
clamp(value, min, max) | 限制范围(...) | 3 | 数字 | 脚本、确定性数字表达式 | 限制到闭区间。 |
pow(value, power) / sqrt(value) | 次方 / 平方根 | 2 / 1 | 数字 | 脚本、确定性数字表达式 | 平方根参数不能为负。 |
lerp(start, end, ratio) | 插值(...) | 3 | 数字 | 脚本、确定性数字表达式 | 比例可超出 0 到 1。 |
map(value, inMin, inMax, outMin, outMax) | 映射范围(...) | 5 | 数字 | 脚本、确定性数字表达式 | 不会自动裁剪结果。 |
sin(value) / cos(value) / tan(value) | 正弦 / 余弦 / 正切 | 1 | 数字 | 脚本、确定性数字表达式 | 参数使用弧度。 |
atan2(y, x) | 方向角(y, x) | 2 | 弧度 | 脚本、确定性数字表达式 | 计算方向角。 |
radians(degrees) / degrees(radians) | 转弧度 / 转角度 | 1 | 数字 | 脚本、确定性数字表达式 | 角度和弧度互转。 |
random() / random(min, max) | 随机数(...) | 0 或 2 | 随机数字 | 仅执行脚本 | 不可用于响应式公式或声明式条件。 |
randomInt(min, max) | 随机整数(min, max) | 2 | 含两端的随机安全整数 | 仅执行脚本 | 参数必须是安全整数。 |
更多例子和错误边界见数学函数。
页面、日志与发包
玩家头顶原版名字的显隐独立于页面：setPlayerNameVisible("Alex", false) 只对当前观看者隐藏 Alex 的名字；setPlayerNameVisible("Alex", "all", false) 对所有观看者隐藏，all 也可以换成指定观看者的玩家名。把 false 改为 true 恢复原版显示规则。参数必须是固定字符串和布尔值，完整按钮示例及生命周期见控制玩家原版名字。
| 英文写法 | 中文写法 | 参数 | 返回值或效果 | 可用范围 | 详细说明 |
|---|---|---|---|---|---|
log(message) | 日志(message) | 一个标量或模板字符串 | 向当前玩家显示调试消息 | 脚本 | 表达式使用统一显示格式。 |
sound(path) | 音效(path) | 本地 OGG 相对路径 | 播放本地音效 | 脚本 | 详见内置动作。 |
keyPress(key) | 按键(key) / 模拟按键(key) | 字符串键名 | 模拟原生按下一次并释放 | 脚本 | 只在客户端运行；例如 keyPress("E")。非法键名安全忽略。 |
open(pageId) | 打开(pageId) | 固定页面 ID | 打开根页面 | 脚本，服务端确认 | 必须先保存页面。 |
openSub(pageId) | 打开子页面(pageId) | 固定页面 ID | 打开 GUI 子页面 | 脚本，服务端确认 | 子页面必须为 screen 模式。 |
close() / close(pageId) | 关闭(...) | 无或页面 ID | 关闭当前或指定页面 | 脚本，服务端确认 | 当前子页面只关闭自己。 |
closeAll() | 全部关闭() | 无 | 关闭当前 GUI 页面链 | 脚本，服务端确认 | 不影响 HUD 或世界页面。 |
isPageOpen(pageId) | 界面已打开(pageId) | 页面 ID 表达式 | 布尔值 | 脚本 | 查询当前客户端活动页面。 |
moveWorld(x, y, z[, milliseconds, type]) | 移动世界页面(...) | 3 或 5 | 移动当前世界页面实例 | 脚本 | 固定实例修改世界坐标，跟随实例修改相对目标脚底的偏移；动画类型为 linear 或 ease_in_out。 |
cmd(action) / opcmd(action) / consolecmd(action) | 指令 / OP指令 / 控制台指令 | 固定业务动作 | 以玩家原生命令包 / 后端 OP / 后端控制台执行 | 脚本，服务端确认 | cmd 支持代理命令；不要拼接玩家输入。具体规则见内置动作。 |
packet(packetId, data...) | 发包(packetId, data...) | 固定包 ID、零到多个数据 | 发送自定义数据 | 脚本 | 数据参数支持模板；见自定义发包。 |
methods.name() | 方法.name() | 无 | 执行页面自定义方法 | 脚本 | 定义和生命周期见生命周期与自定义方法。 |
global(methodId, args...) | 调用通用方法(methodId, args...) | 方法 ID 与字面量参数 | 启动独立服务端通用方法 | 页面脚本 | 方法 ID必须是字符串字面量；参数只接受字符串、有限数字和布尔字面量，不接受页面变量或公式。详见服务端通用脚本与 Cron。 |
组件引用与属性
| 英文写法 | 中文写法 | 参数 | 返回值或效果 | 可用范围 | 详细说明 |
|---|---|---|---|---|---|
component(id) | 组件(id) | 固定组件 ID | 安全组件引用 | 脚本 | 目标缺失时仅当前语句失败。 |
self | 自身 | 无 | 当前事件触发组件 | 组件事件及其回调 | 页面级事件中为 null。 |
parent / self.parent | 父级 / 自身.父级 | 无 | 父组件或 null | 组件事件及其回调 | 可读取或给 component(...).parent 赋布局组件。 |
child(index) | 子组件(index) | 从 0 开始的整数 | 直接子组件或 null | 组件引用后 | 使用稳定运行时子组件顺序。 |
component(id).layout.x/y/width/height | 组件(id).布局.* | 字段 | 当前值；按组件类型允许写入 | 脚本 | 文本宽高自动测量且只读，X/Y 仍可写；其他组件普通赋值固定当时结果。 |
formula(expression) | 公式(expression) | 确定性数字表达式或公式字符串 | 保存响应式公式 | 允许公式的写入右侧 | 会随变量和窗口变化重新求值。 |
layout.expression(field) | 布局.表达式(field) | 布局字段名 | 原公式对象 | 脚本 | 可读取 .source 与 .isFormula。 |
visible/enabled/z/pointerEvents | 显示/启用/层级/指针事件 | 对应标量 | 读取或修改会话状态 | 组件引用后 | 不写回页面 yml。 |
scale/rotation/opacity | 缩放/旋转/透明度 | 数字或公式 | 读取或修改视觉状态 | 支持的非布局组件 | 实体不支持根级 opacity。 |
containerBinding | 容器绑定 | 语义槽位 ID 或 null | 读取或临时改绑 | 容器页面非布局组件 | 修改只影响当前容器会话。 |
text.* / button.* / image.* / video.* / input.* / entity.* | 对应中文数据块 | 类型专属字段 | 读取或写入已开放字段 | 对应组件类型 | 完整字段说明见组件操作。 |
itemSlot.bind/mode/check/maxStack | 物品槽.* | 槽位字段 | 读取；bind/mode 可写 | item_slot | check 与 maxStack 只读。 |
savePosition() / resetPosition() | 保存位置() / 重置位置() | 无 | 保存或清除拖动记忆 | 组件引用后 | 操作当前服务器命名空间下的位置。 |
self.destroy() | 自身.销毁() | 无 | 销毁当前事件组件 | 组件事件及其回调 | self.destory() 为旧拼写兼容；直接子组件保留并解除父级。 |
scrollTo(x, y) / resetScroll() | 滚动到(x, y) / 重置滚动() | 两个非负数 / 无 | 控制滚动偏移 | layout_scroll | 旧资料中的 scrollTo(position) 只是参数占位写法，实际必须提供 X、Y。 |
video.play()/pause()/stop() | 视频.播放()/暂停()/停止() | 无 | 控制视频 | video | 只作用于当前页面会话。 |
video.seek(milliseconds) | 视频.跳转(milliseconds) | 非负整数 | 跳到指定时间 | video | 单位为毫秒。 |
动态组件
| 英文写法 | 中文写法 | 参数 | 返回值或效果 | 可用范围 | 详细说明 |
|---|---|---|---|---|---|
addComponent(type, id) | 新增组件(type, id) | 固定类型、固定新 ID | 新增默认根组件 | 脚本 | 支持当前 17 种组件类型。 |
copyComponent(source, target) | 复制组件(source, target) | 固定来源、目标 ID 字符串表达式 | 只复制一个组件 | 脚本 | 不复制后代，保留来源父级。 |
copyComponentTree(source, suffix) | 复制组件树(source, suffix) | 固定来源、后缀字符串表达式 | 原子复制完整子树 | 脚本 | 每个新 ID 为原 ID 加后缀；详见组件操作。 |
当前版本没有可用的 removeComponent(id) / 移除组件(id) 动作；不要把它当作已支持函数。动态组件会在当前页面会话结束时统一释放。
新 ID 只能包含 Unicode 字母、数字、_ 和 -，最多 64 个 Unicode 字符。单组件复制的 target 是完整 ID；子树复制的 suffix 会追加到来源根及每一个后代 ID。子树中任何目标冲突都会让整次复制失败。
生命周期和下一步
页面 open、组件 create、页面 close 与自定义方法共同组成脚本生命周期。事件字段、鼠标触发顺序、方法调用与 reload 行为统一见语法与事件和生命周期与自定义方法。本页只用于快速查名字；制作倒计时、子页面或复杂动态组件时，应继续阅读对应专题。