SAP 宽阶段空间索引

cj-sap 提供基于 AABB 的 Sweep and Prune（扫描与裁剪）宽阶段索引。包本身不依赖 Cocos 节点、ECS 实体或其它空间索引，可以在运行时公共层独立使用。

Body 协议

SAP 默认使用包内的 Body，也接受实现 ISpatialBody 的结构兼容对象。原有 IBody 继续只描述 AABB 数据，ISpatialBody 在此基础上增量定义：

• 唯一 id、碰撞 group/mask；
• AABB 最小点、中点、最大点与尺寸；
• 业务 data 和相交判断；
• onAabbChanged/offAabbChanged 实例订阅方法。

因此同一个 Body 可以被不同空间索引复用，公共包之间无需互相依赖具体 Body 类。同一个 SAP 实例内不允许重复 id，重复插入会抛出 RangeError。

示例

import { Body, SAP, SortType } from 'db://pkg/@icjhd/cj-sap';

const sap = new SAP<number>(SortType.XAxis);
const body = new Body<number>(1)
    .setData(1001)
    .setRect({ x: 0, y: 0, width: 32, height: 32 });

sap.insert(body);

console.log(sap.size());
sap.forEachBody((current) => {
    console.log(current.id, current.data);
});

forEachBody 不暴露内部数组，返回本次访问数量。遍历顺序可能随 SAP 重建而变化，业务层 不得把该顺序作为帧同步或优先级依据，也不得在访问回调中修改同一个 SAP。

insert 默认通过 onAabbChanged 自动标记排序为脏。高频同步路径可以传入 { autoRefresh: false }，在批量更新 AABB 后显式调用 refreshBody(body) 或 refreshById(id)，下一次查询时再统一重建排序。

retrieve(query, out) 会继续向 out 追加结果，不会替调用方清空数组。热路径应复用数组并在 调用前显式设置 out.length = 0。