@gridworkjs/quadtree 1.0.0 → 1.1.1

package/README.md

@@ -6,46 +6,44 @@
 
 <p align="center">quadtree spatial index for sparse, uneven point and region data</p>
 
-## install
+## Install
 
 ```
 npm install @gridworkjs/quadtree
 ```
 
-## usage
+## Usage
+
+A 2D game where entities spawn and despawn dynamically. The quadtree tracks their positions so you can efficiently query who's nearby:
 
 ```js
 import { createQuadtree } from '@gridworkjs/quadtree'
 import { point, rect, bounds } from '@gridworkjs/core'
 
-// create a quadtree with a bounds accessor
-const tree = createQuadtree(item => bounds(item.position))
-
-// insert items - any shape, the accessor extracts bounds
-tree.insert({ id: 1, position: point(10, 20) })
-tree.insert({ id: 2, position: point(50, 60) })
-tree.insert({ id: 3, position: rect(70, 70, 90, 90) })
+const entities = createQuadtree(e => bounds(e.position))
 
-// search for items intersecting a region
-tree.search({ minX: 0, minY: 0, maxX: 55, maxY: 65 })
-// => [{ id: 1, ... }, { id: 2, ... }]
+// entities come and go at arbitrary positions
+entities.insert({ name: 'player', position: point(100, 200) })
+const goblin = { name: 'goblin', position: point(120, 210) }
+entities.insert(goblin)
+entities.insert({ name: 'chest', position: point(400, 50) })
+entities.insert({ name: 'trap', position: rect(110, 190, 130, 220) })
 
-// also accepts geometry objects as queries
-tree.search(rect(0, 0, 55, 65))
+// who's in the player's field of view?
+entities.search(rect(50, 150, 200, 300))
+// => [player, goblin, trap]
 
-// find nearest neighbors
-tree.nearest({ x: 12, y: 22 }, 2)
-// => [{ id: 1, ... }, { id: 2, ... }]
+// what's closest to the goblin for it to target?
+entities.nearest({ x: 120, y: 210 }, 2)
+// => [goblin, player]
 
-// remove by identity
-tree.remove(item)
-
-tree.size   // number of items
-tree.bounds // current root bounds
-tree.clear()
+// entity defeated - remove it (by reference)
+entities.remove(goblin)
 ```
 
-## options
+Quadtrees handle sparse, uneven data well. Entities can cluster in one corner or spread across the whole map - the tree adapts its subdivision to match.
+
+## Options
 
 ```js
 createQuadtree(accessor, {
@@ -93,6 +91,6 @@ Number of items in the tree.
 
 Current root bounds, or `null` if empty and no fixed bounds were set.
 
-## license
+## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gridworkjs/quadtree",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "quadtree spatial index for sparse, uneven point and region data",
   "type": "module",
   "main": "src/index.js",

package/src/quadtree.js

@@ -166,6 +166,19 @@ function growToContain(root, target) {
   return root
 }
 
+function validateAccessorBounds(b) {
+  if (b === null || typeof b !== 'object') {
+    throw new Error('accessor must return a bounds object')
+  }
+  if (!Number.isFinite(b.minX) || !Number.isFinite(b.minY) ||
+      !Number.isFinite(b.maxX) || !Number.isFinite(b.maxY)) {
+    throw new Error('accessor returned non-finite bounds')
+  }
+  if (b.minX > b.maxX || b.minY > b.maxY) {
+    throw new Error('accessor returned inverted bounds (minX > maxX or minY > maxY)')
+  }
+}
+
 function normalizeBounds(input) {
   if (input != null && typeof input === 'object' &&
       'minX' in input && 'minY' in input && 'maxX' in input && 'maxY' in input) {
@@ -255,12 +268,15 @@ export function createQuadtree(accessor, options = {}) {
   const index = {
     [SPATIAL_INDEX]: true,
 
+    accessor,
+
     get size() { return size },
 
     get bounds() { return root ? root.bounds : null },
 
     insert(item) {
       const itemBounds = accessor(item)
+      validateAccessorBounds(itemBounds)
       const entry = { item, bounds: itemBounds }
 
       if (!root) {
@@ -284,6 +300,7 @@ export function createQuadtree(accessor, options = {}) {
     remove(item) {
       if (!root) return false
       const itemBounds = accessor(item)
+      validateAccessorBounds(itemBounds)
       const removed = removeEntry(root, item, itemBounds)
       if (removed) size--
       return removed