# 先判断是否需要组合属性

需求	使用
金币、等级、当前生命等权威状态	普通属性
根据多个状态计算的结果	组合属性
需要多行多列的系数	表格 + 组合属性脚本
只在某个页面临时显示的简单比例	渲染布局内只读计算
需要产生奖励或扣除资源	控件/事件行为脚本，不是组合属性

如果一个值需要单独保存、重置或被玩家直接修改，它不是纯派生值。

# 纯 AI 模式的定义方式

给 AI 一份计算契约：

名称：总战力
依赖：攻击、防御、等级
公式：攻击 * 2 + 防御 + 等级 * 5
返回：非负整数
缺失处理：任一依赖缺失时按 0 计算
用途：队伍页显示和排行，不允许脚本写入

AI 应先查询依赖资源，再创建 compose_property/<id>/script。组合属性脚本只能读取并返回数值：

const attack = player.getPro("攻击");
const defense = player.getPro("防御");
const level = player.getPro("等级");
return Math.max(0, Math.floor(attack * 2 + defense + level * 5));

# 只读边界

组合属性可能在页面刷新、需求判断和其他计算中被多次读取，因此禁止：

• setPro、addPro 或对象增删改。
• 弹窗、跳转、AI、存档和联网调用。
• 发放奖励、记录日志或修改临时会话。
• 依赖形成循环的其他组合属性。

不要利用“当前看起来只调用一次”规避只读规则。渲染和事件频率变化后，副作用会重复发生。

# 玩家与对象上下文

玩家级组合属性直接读取 player。绑定对象类的组合属性可以通过 tools.kwargs.object 读取当前实例：

const equipment = tools.kwargs.object;
if (!equipment) return 0;
return equipment.getPro("攻击") + equipment.getPro("品质") * 20;

对象结果只描述当前对象，跨对象总和应在明确的行为脚本中遍历并缓存，避免页面每次读取都扫描大型对象列表。

# 传统模式的公式与脚本

传统模式可以维护基值与可视公式，计算规则为“基值 + 公式结果”。也可以填写脚本；一旦存在脚本，脚本结果覆盖公式，移除脚本后公式才重新生效。

传统作者还需要维护单位、保留小数、科学计数和计数单位等显示字段。显示格式不应改变权威数值。

# 验收组合属性

• 默认状态返回预期数值。
• 每个依赖处于 0、最小值和最大值时结果正确。
• 对象上下文缺失时有明确回退。
• 没有 NaN、Infinity 或循环依赖。
• 多次读取不会改变任何状态。
• 修改基础属性后，页面立即显示新结果。

继续阅读：组合属性脚本 和 属性与状态。