# 对象筛选器参考

# 入口与前置

在对象系统打开 对象筛选器，先准备对象类和用于比较的属性。筛选器只产生对象集合或绑定结果，不直接修改对象。

# 字段表

字段	作用
筛选器名称	稳定识别这套规则
绑定类	候选对象的来源类
筛选属性	每个对象必须满足的比较条件
筛选判断模式	全部满足或任意满足
无筛选结果则代表全选	空结果时使用整类对象
无筛选结果则代表不足	空结果直接判定失败
筛选后二次策略	排除当前对象或继续限制结果
最多筛选数量	截断返回集合
绑定属性	将数量或统计结果写入指定属性
AI 展示属性	允许 AI 上下文读取的对象字段

# 求值顺序

绑定类 -> 逐对象条件 -> 条件组合 -> 空结果策略 -> 二次策略 -> 数量限制 -> 绑定统计

在需求、消耗和获得中，筛选器完成后才会继续执行转化。对象销毁或列表变化后要重新求值，不能缓存对象下标。

# 定义输入与消费者

合同部分	必须回答的问题
来源	哪个类提供候选对象？是否允许为空？
上下文	比较读取玩家、当前对象还是候选对象状态？
条件	要求全部还是任意？单位和边界是什么？
当前对象	包含、排除，还是仅作为比较上下文？
数量限制	截断结果是否符合所属规则？
输出	消费者需要集合、数量、统计值还是可用性？
消费者	哪个需求、花费/获得、页面、脚本或 AI 上下文读取它？

筛选器是一份可复用查询合同。不要给它副作用，也不要假设所有消费者对空结果有相同解释。

# 消费者边界

• 需求使用结果允许或拒绝动作。
• 花费/获得按稳定对象 ID 对选中对象各执行一次。
• 绑定属性可展示或复用数量/统计值，但不能代替对象身份。
• 脚本可调用 objects.getObjectsByFilter(filterId, currentObjectId)，并处理 false 或空数组。
• AI 展示属性 决定进入 AI 上下文的字段，不代表完整对象存档公开。

# 空结果策略

“全选”和“不足”表达两种相反的业务语义：前者把空条件当作整类命中，后者把空集合当作资源不足。没有明确业务含义时不要打开任一开关。

# 常见失败

现象	检查项
所有对象都被修改	是否误开“无结果代表全选”
没有目标但需求通过	空结果策略与消费者语义是否冲突
当前对象命中自己	是否缺少排除/当前上下文策略
删除后结果指向其他对象	消费者是否缓存下标/数组而非稳定 ID
绑定数量没有更新	来源变化后是否重新求值
AI 看到了错误字段	AI 展示属性是否过宽或未更新

# 迁移风险与验收

检查当前对象排除、最多数量、类继承和对象已销毁场景。验收全部/任意条件、零结果、单结果、多结果、绑定属性更新，以及筛选结果用于需求、花费和获得时不重复修改。

返回：类与对象。