# 先区分四种状态

状态	API	是否适合写入
普通数值	getPro / setPro / addPro	行为脚本可写
派生数值	getComPro	只读
表格	getTable	只有动态表格可 setData
动态字符串	getString / setString	目标必须允许修改且不是脚本模式

渲染布局、组合属性脚本和动态字符串脚本应只调用读取方法。写入放在控件、事件或明确的动作脚本中。

# API 清单

方法	参数	返回
player.getPro(name)	属性 ID 或名称	数值；找不到时回退为组合属性或 undefined
player.setPro(name, value)	属性、目标值	成功 true，找不到 false；会执行上下限检查
player.addPro(name, delta)	属性、增量	成功 true，找不到 false；会执行上下限检查
player.getComPro(name)	组合属性 ID 或名称	当前派生结果
player.getTable(name)	表格 ID 或名称	表格代理或 undefined
player.getString(name)	动态字符串 ID 或名称	解析后的字符串
player.setString(name, value)	可写字符串、内容	成功 true，不可写时 false
player.getEventEnabled(name)	事件 ID 或名称	boolean 或 undefined
player.setEventEnabled(name, enabled)	事件、开关	成功 true，找不到 false

AI 生成脚本时应先查询项目资源，使用真实 ID；显示名称可能重复，不能把用户可见文本当成稳定标识。

# 读取与写入的安全顺序

一个购买动作应遵循：

const price = 50;
if (player.getPro("金币") < price) {
  tools.showToast(tools.tr("金币不足"), "warning");
  return;
}

player.addPro("金币", -price);
player.addPro("经验", 10);
tools.showToast(tools.tr("购买成功"), "success");

复杂动作要先把所有条件算完，再集中写入。不要一边扣费一边发起异步请求，否则请求失败时很难回滚。

# 数值 API 的边界

setPro 和 addPro 会按属性定义做数值归一化，并触发最小值/最大值检查。它们不会自动保存云端，也不会替你处理重复点击。需要持久化时，在动作完成后显式调用合适的存档工具。

不要在以下位置写入：

• 组合属性脚本或动态字符串脚本；
• 页面渲染每次都会重新执行的脚本；
• 每帧脚本里没有频率控制的循环。

# 表格代理

const config = player.getTable("掉落配置");
const weight = Number(config?.getData("狼", "权重") || 0);

const log = player.getTable("行动日志");
if (log?.tableType === "dynamic") {
  log.setData(0, "内容", tools.tr("进入森林"));
}

静态表格只提供 getData；动态表格首次从项目默认数据初始化，后续写入进入玩家存档。使用 tableType 检查后再写，避免把配置表当成存档。

# 动态字符串代理

const oldName = player.getString("玩家昵称");
if (!oldName) return;
const ok = player.setString("玩家昵称", "新昵称");
if (!ok) tools.showToast(tools.tr("这个字符串不可修改"), "error");

setString 只适用于启用了“允许修改”的动态字符串。脚本模式字符串是实时计算值，不能同时作为写入目标。

# 事件开关

if (player.getPro("章节") >= 3) {
  player.setEventEnabled("每日任务", true);
}

事件开关只改变事件是否启用，不会删除事件配置。重新启用前要确认重复触发是否幂等。

# 验收清单

• 找不到 ID 时脚本有明确回退，不会静默发放奖励。
• 所有扣费和奖励在同一动作中可追踪、可防重复。
• 静态表格不会被写入，动态表格写入可保存并恢复。
• 不可写动态字符串会给出提示。
• 只读脚本没有 setPro、addPro 或异步副作用。

下一步阅读：objects：对象集合 API 和 tools：外部能力 API。