脚本 API
objects：对象集合 API
按类查询、创建、修改和删除玩家存档中的对象实例。
脚本 API · 对象
用稳定对象 ID 管理多份独立实例
`objects` 操作的是当前玩家存档里的对象实例。类定义结构，实例保存自己的属性、字符串、名称和 ID；页面只展示快照，动作脚本负责修改。
# API 清单
| 方法 | 参数 | 返回 |
|---|---|---|
objects.getObjects(classname, pro?, start?, end?) |
类、可选属性范围 | 对象代理数组 |
objects.getObjectsByFilter(filterid, curobjectid?) |
筛选器、可选当前对象 ID | 对象代理数组；筛选器不存在时 false |
objects.newObject(classname, name, des) |
类、名称、介绍 | 新对象代理；失败 false |
objects.delObject(classname, index) |
类、数组位置 | 成功 true，失败 false |
objects.delObjectByID(classname, id) |
类、稳定对象 ID | 成功 true，失败 false |
对象代理提供：
| 方法 | 用途 |
|---|---|
getID() |
读取稳定身份 |
getName() / setName(name) |
读写名称 |
getDes() / setDes(des) |
读写介绍 |
getPro(name) / setPro(name, value) / addPro(name, delta) / delPro(name) |
读写对象属性或清除对象覆写 |
getComPro(name) |
读取当前对象的派生属性 |
getString(name) / setString(name, value) |
读写对象上下文动态字符串 |
# 查询不要依赖数组位置
const candidates = objects.getObjects("装备")
.filter((item) => Number(item.getPro("耐久") || 0) <= 0);
for (const item of candidates) {
objects.delObjectByID("装备", item.getID());
}
排序、筛选和删除都会改变数组顺序。数组索引只适合一次性的临时操作；跨脚本或异步回调必须保存 getID()。
# 创建对象是一个事务
const count = objects.getObjects("宠物").length;
if (count >= 50) {
tools.showToast(tools.tr("宠物栏已满"), "warning");
return;
}
const pet = objects.newObject("宠物", "幼狼", tools.tr("刚加入队伍的伙伴"));
if (!pet) return;
pet.setPro("等级", 1);
pet.setPro("好感度", 0);
先检查资源和数量，再创建并初始化全部字段，最后才扣费或发放结果。异步动作要使用提交锁或幂等标记，避免快速点击创建两份实例。
# 当前对象上下文
对象控件、对象行脚本和拖放脚本会把当前实例放到 tools.kwargs：
const object = tools.kwargs.object;
const objectID = tools.kwargs.objID;
if (!object || !objectID) return;
object.addPro("经验", 1);
object 是可读写代理；objID 适合传给删除、特效和后续动作。名称会变化，不能作为唯一身份。
# 对象筛选器
const targets = objects.getObjectsByFilter("可攻击目标", tools.kwargs.objID);
if (targets === false || targets.length === 0) return;
for (const target of targets) {
target.addPro("生命", -10);
}
筛选器规则由项目配置决定，脚本只消费结果。需要完全动态的查询时，使用 getObjects 后在脚本中筛选；传统筛选器页面默认隐藏，可从文档开关进入。
# 对象动态字符串
对象上下文读取字符串时，会优先使用当前对象自己的可写覆写，再回退到玩家级字符串：
const title = object.getString("称号");
object.setString("备注", tools.tr("已完成训练"));
写入前确认目标字符串允许修改，并避免把对象描述和权威状态混为一谈。
# 删除与清理
删除对象会从玩家对象集合移除实例并注销运行时对象。删除前应处理当前选中状态、仍指向该 ID 的控件和任务记录、删除奖励的幂等性，以及存档写入失败后的重试。
# 验收清单
- 同类对象的 ID、属性和字符串彼此独立。
- 异步回调仍按 ID 操作正确实例。
- 创建失败不会留下半初始化对象或已扣除资源。
- 删除当前实例后页面没有悬空选择。
- 对象脚本没有在渲染/只读上下文中写入。