RTree
RBush is a high-performance JavaScript library for 2D spatial indexing of points and rectangles. It's based on an optimized R-tree data structure with bulk insertion support.
Spatial index is a special data structure for points and rectangles that allows you to perform queries like "all items within this bounding box" very efficiently (e.g. hundreds of times faster than looping over all items).
This version of RBush uses a fixed min/max accessor structure of [ '.left', '.top', '.right', '.bottom' ]. This is to avoid the eval-like function creation that the original library used, which caused CSP policy violations.
rbush is forked from https://github.com/mourner/rbush by Vladimir Agafonkin
Scope: static
Source: src/structs/RTree.js#L10
Since: 3.0.0
Public Methods
all
<instance> all()
Description:
Returns all items stored in the RTree as a flat array.
Returns: Array.<any> - An array containing all items currently stored in the tree.
Source: src/structs/RTree.js#L44
Since: 3.0.0
clear
<instance> clear()
Description:
Removes all items from the RTree, resetting it to an empty state.
Returns: Phaser.Structs.RTree - This RTree instance, for chaining.
Source: src/structs/RTree.js#L203
Since: 3.0.0
collides
<instance> collides(bbox)
Description:
Tests whether any item in the RTree intersects with the given bounding box.
Unlike search, this method stops as soon as the first intersection is found, making it more efficient when you only need to know whether a collision exists rather than retrieving all results.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| bbox | Object | No | The bounding box to test against. Must have minX, minY, maxX, and maxY properties. |
Returns: boolean - true if any item in the tree intersects with the bounding box, otherwise false.
Source: src/structs/RTree.js#L96
Since: 3.0.0
compareMinX
<instance> compareMinX(a, b)
Description:
Comparator function used to sort items by their minimum X boundary (left property).
Returns a negative number if a should sort before b, a positive number if after, or zero if equal.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| a | Object | No | The first item to compare. |
| b | Object | No | The second item to compare. |
Returns: number - The difference between the left values of the two items.
Source: src/structs/RTree.js#L569
Since: 3.0.0
compareMinY
<instance> compareMinY(a, b)
Description:
Comparator function used to sort items by their minimum Y boundary (top property).
Returns a negative number if a should sort before b, a positive number if after, or zero if equal.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| a | Object | No | The first item to compare. |
| b | Object | No | The second item to compare. |
Returns: number - The difference between the top values of the two items.
Source: src/structs/RTree.js#L587
Since: 3.0.0
fromJSON
<instance> fromJSON(data)
Description:
Populates this RTree with data previously exported via toJSON.
This allows a tree to be serialized and restored without re-inserting every item individually.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| data | Object | No | The tree data to import, as returned by toJSON. |
Returns: Phaser.Structs.RTree - This RTree instance, for chaining.
Source: src/structs/RTree.js#L299
Since: 3.0.0
insert
<instance> insert(item)
Description:
Inserts a single item into the RTree.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| item | * | No | The item to insert. Must have left, top, right, and bottom properties. |
Returns: Phaser.Structs.RTree - This RTree instance, for chaining.
Source: src/structs/RTree.js#L187
Since: 3.0.0
load
<instance> load(data)
Description:
Bulk loads an array of items into the RTree.
Bulk loading is significantly more efficient than inserting items one by one when adding large datasets, as it builds an optimally structured tree in a single pass using the OMT algorithm. If the array is smaller than the minimum entry threshold, items are inserted individually instead.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| data | Array.<any> | No | An array of items to insert. Each item must have left, top, right, and bottom properties. |
Returns: Phaser.Structs.RTree - This RTree instance, for chaining.
Source: src/structs/RTree.js#L136
Since: 3.0.0
remove
<instance> remove(item, [equalsFn])
Description:
Removes a single item from the RTree.
An optional equality function can be provided to compare items by value rather than by reference, which is useful when the original item reference is not available. The function receives two items and should return true if they are considered equal.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| item | * | No | The item to remove. |
| equalsFn | function | Yes | An optional custom equality function taking two items and returning a boolean. |
Returns: Phaser.Structs.RTree - This RTree instance, for chaining.
Source: src/structs/RTree.js#L217
Since: 3.0.0
search
<instance> search(bbox)
Description:
Searches the RTree for all items that intersect with the given bounding box and returns them as an array.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| bbox | Object | No | The bounding box to search within. Must have minX, minY, maxX, and maxY properties. |
Returns: Array.<any> - An array of all items in the tree that intersect with the given bounding box.
Source: src/structs/RTree.js#L57
Since: 3.0.0
toBBox
<instance> toBBox(a)
Description:
Converts a Phaser-style bounds object into the internal bounding box format used by the RTree.
Maps the left, top, right, and bottom properties of the input to minX, minY, maxX, and maxY respectively, which is the format expected by the R-tree algorithms.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| a | Object | No | The object to convert. Must have left, top, right, and bottom properties. |
Returns: Object - A bounding box object with minX, minY, maxX, and maxY properties.
Source: src/structs/RTree.js#L605
Since: 3.0.0
toJSON
<instance> toJSON()
Description:
Returns the raw internal tree data as a JSON-compatible object.
The returned value can be passed to fromJSON to restore the tree state at a later point.
Returns: Object - The internal tree data object.
Source: src/structs/RTree.js#L287
Since: 3.0.0