quadtree-js快速上手教程：5分钟安装并跑通你的第一个四叉树

quadtree-js快速上手教程：5分钟安装并跑通你的第一个四叉树

【免费下载链接】quadtree-jsA lightweight quadtree implementation for javascript项目地址: https://gitcode.com/gh_mirrors/qu/quadtree-js

quadtree-js 是一款轻量的JavaScript 四叉树（Quadtree）库，压缩后仅 639 字节，专为二维空间中的对象存储与碰撞检测而设计。本教程带你 5 分钟内完成安装，并跑通你的第一个四叉树：创建树、插入矩形对象、检索碰撞候选。

为什么需要四叉树？

想象一个游戏里有 1000 个移动对象，每帧都要判断谁和谁碰撞。两两比较意味着近50 万次检查——而四叉树能帮你把检查量压缩到极小一部分：

• 空间被不断一分为四（左上 / 右上 / 左下 / 右下）
• 每个节点最多存放max_objects个对象，超出自动分裂
• 查询时只遍历"有可能相关"的子区域，远离的对象根本不用比较

┌─────────────────────────┐ │ ┌─────────┬─────────┐│ │ NW │ NE │ SE ││ ├──────┼─────────┼─────────┤│ │ SW │ SW │ ││ └─────────────────────────┘

第一步：安装 quadtree-js（npm 一键完成）

在你的项目目录下执行：

npm i -D @timohausmann/quadtree-js

然后在代码中导入：

// ES 模块 import Quadtree from '@timohausmann/quadtree-js'; // 或 CommonJS const Quadtree = require('@timohausmann/quadtree-js');

💡 如果想拿到完整源码研究，可以直接克隆仓库：git clone https://gitcode.com/gh_mirrors/qu/quadtree-js

不想装包？直接用浏览器方式引入压缩文件即可：

<script src="quadtree.min.js"></script>

第二步：创建你的第一个四叉树

一个四叉树定义了一个二维空间（矩形边界）。只需 4 行代码：

var myTree = new Quadtree({ x: 0, y: 0, width: 400, height: 300 });

• 第 2、3 个参数是可选的max_objects（默认 10）和max_levels（默认 4）
• 对象只会存放在叶子节点，跨区域的对象会在每个命中的叶子节点各存一份引用，因此碰撞候选非常精准

第三步：插入对象并查询碰撞

所有对象都是统一的矩形格式{ x, y, width, height }，还能附加自己的属性：

// 插入一个对象 myTree.insert({ x: 100, y: 100, width: 100, height: 100 }); // 查询：找出与该区域相交的所有候选对象 var candidates = myTree.retrieve({ x: 150, y: 150, width: 100, height: 100 });

用完之后可以用myTree.clear()清空整棵树，方便下一帧重建。

进阶：调优 max_objects 与 max_levels

var myTree = new Quadtree({ x: 0, y: 0, width: 800, height: 600 }, 15, 6); // 第2参数：节点容量；第3参数：最大层级

快速参考：核心 API 一览

常见问题 FAQ

• retrieve 返回的就是碰撞对象吗？它返回的是"候选者"——最终是否碰撞（例如圆与圆）需要你自己做精确判断。
• 对象超出边界会怎样？四叉树只管理边界内的空间，对象尺寸建议不要超过边界范围。
• 支持哪些浏览器？所有现代浏览器与运行时。注意 1.2.x 起使用 ES6（new Set()），不再兼容 IE9。

动手试试看：项目自带的演示页面

仓库里的docs/目录提供了几个开箱即用的示例，浏览器直接打开就能玩：

• docs/simple.html—— 添加静态对象，直观看到四叉树如何分裂
• docs/dynamic.html—— 持续追踪移动对象
• docs/many.html—— 大量对象两两互相检测
• docs/test-retrieve.html—— 100 万对象的检索性能测试

核心源码在 quadtree.js，注释非常详尽，TypeScript 类型定义见 quadtree.d.ts，压缩版为quadtree.min.js。

总结：npm 一条命令安装 →new Quadtree(bounds)创建 →insert()存对象 →retrieve()查碰撞。整个流程不到 10 行代码。现在就打开终端，5 分钟后你的第一个四叉树就能跑起来 🚀

【免费下载链接】quadtree-jsA lightweight quadtree implementation for javascript项目地址: https://gitcode.com/gh_mirrors/qu/quadtree-js