脚本 API
组合属性脚本
用同步、无副作用的函数计算派生数值。
脚本 API · 只读计算
组合属性是函数，不是第二份存档
组合属性脚本根据当前玩家或对象状态同步返回一个数值。它可能被界面和需求判断反复读取，因此必须纯粹、快速、确定。
# 输入与输出契约
向编辑器 AI 说明依赖、单位、精度、空值和边界：
创建组合属性“战力”。
输入：攻击、防御、等级；缺失按 0。
公式：floor(攻击 * 2 + 防御 + 等级 * 5)，最低 0。
输出整数，只用于显示和判断，不修改任何状态。
const attack = Number(player.getPro("攻击") || 0);
const defense = Number(player.getPro("防御") || 0);
const level = Number(player.getPro("等级") || 0);
return Math.max(0, Math.floor(attack * 2 + defense + level * 5));
# 可以读取什么
- 普通属性和当前对象属性；
- 静态/动态表格的当前值；
- 对象集合，用于低频、规模受控的统计；
- 当前
tools.kwargs.object。
不要读取自己或形成环路的组合属性。跨对象大规模统计会在每次读取时重新执行，应该在明确的事件中缓存结果。
# 对象上下文
const equipment = tools.kwargs.object;
if (!equipment) return 0;
const attack = Number(equipment.getPro("攻击") || 0);
const quality = Number(equipment.getPro("品质") || 0);
return attack + quality * 20;
对象上下文缺失时必须返回有效数值，不能返回 undefined。
# 表格驱动计算
const level = Number(player.getPro("工坊等级") || 0);
const table = player.getTable("工坊倍率");
const rate = Number(table?.getData(level, "倍率") || 1);
return Number(player.getPro("基础产量") || 0) * rate;
配置值缺失时选择明确回退。不要让空单元格传播成 NaN。
# 禁止事项
setPro、addPro、对象增删改；- 弹窗、场景跳转、AI、存档、弱联网；
- 随机抽奖或依赖调用次数的结果；
Promise、延迟或客户端特效；- 返回字符串、布尔值、
NaN或Infinity。
# 验收清单
- 默认、0、最小和最大输入均返回有限数值。
- 多次读取不会改变任何玩家或对象状态。
- 当前对象缺失时有回退。
- 表格缺行列时不会产生
NaN。 - 依赖关系无循环，大集合统计有性能上限。