四叉树碰撞检测模块

前置条件

游戏引擎 开发框架

使用案例

import { Body, QuadTree } from 'db://pkg/@icjhd/cj-quadtree';

const tree = new QuadTree<number>(0, 0, 1000, 1000, 6);
const body = new Body<number>(1)
    .setData(1001)
    .setRect({ x: 10, y: 20, width: 40, height: 60 });

tree.insert(body);
tree.forEachBody((item) => console.log(item.id, item.data));
tree.visitCellBounds((bounds) => console.log(bounds));

跨空间包复用 Body

QuadTree 的第二个泛型参数接受满足 ISpatialBody<T> 的纯结构对象，不要求继承本包的 Body。因此其它空间索引包的 Body 可以直接复用，cj-quadtree 不需要依赖这些包：

import { Body as SapBody } from 'db://pkg/@icjhd/cj-sap';
import { QuadTree } from 'db://pkg/@icjhd/cj-quadtree';

const tree = new QuadTree<number, SapBody<number>>(0, 0, 1000, 1000, 6);
const body = new SapBody<number>(1).setData(1001).setRect({ x: 10, y: 20, width: 40, height: 60 });

tree.insert(body); // 无需 any 转换，并继续自动监听 AABB 变化。

同一棵树内的 Body ID 必须唯一。重复插入相同 ID 会抛出 RangeError，避免旧节点残留为 无法移除的“幽灵节点”。

公共诊断能力

• size()：返回当前碰撞体数量。
• forEachBody(visitor, target?)：访问当前持有的碰撞体，不暴露内部容器。
• visitCellBounds(visitor, limit?)：访问已创建的树单元边界，供调试绘制使用，默认最多 4096 个。

这些遍历 API 不承诺可用于权威碰撞结果的稳定排序。帧同步业务应在消费候选集前按稳定业务键排序。