com.wallstop-studios.unity-helpers 2.0.0-rc81.9 → 2.0.1

package/{RANDOM_PERFORMANCE.md → Docs/RANDOM_PERFORMANCE.md}

@@ -81,18 +81,18 @@ This document contains performance benchmarks for the various random number gene
 
 | Random                      | NextBool    | Next        | NextUInt      | NextFloat   | NextDouble  | NextUint - Range | NextInt - Range |
 | --------------------------- | ----------- | ----------- | ------------- | ----------- | ----------- | ---------------- | --------------- |
-| DotNetRandom                | 548,300,000 | 54,900,000  | 58,300,000    | 48,000,000  | 28,100,000  | 54,800,000       | 54,100,000      |
-| LinearCongruentialGenerator | 805,700,000 | 829,700,000 | 1,334,700,000 | 212,300,000 | 411,000,000 | 558,500,000      | 503,400,000     |
-| IllusionFlow                | 787,300,000 | 655,900,000 | 885,100,000   | 203,500,000 | 309,000,000 | 442,200,000      | 392,100,000     |
-| PcgRandom                   | 793,900,000 | 662,100,000 | 919,300,000   | 211,700,000 | 341,200,000 | 453,800,000      | 407,700,000     |
-| RomuDuo                     | 796,900,000 | 556,300,000 | 707,100,000   | 189,500,000 | 254,800,000 | 423,300,000      | 390,900,000     |
-| SplitMix64                  | 803,400,000 | 739,200,000 | 1,063,900,000 | 212,600,000 | 381,300,000 | 485,700,000      | 439,400,000     |
-| SquirrelRandom              | 781,900,000 | 394,900,000 | 413,800,000   | 198,000,000 | 203,400,000 | 365,900,000      | 311,700,000     |
-| SystemRandom                | 143,400,000 | 148,500,000 | 65,200,000    | 131,400,000 | 137,200,000 | 59,000,000       | 60,000,000      |
-| UnityRandom                 | 657,500,000 | 85,000,000  | 87,800,000    | 65,200,000  | 41,500,000  | 81,500,000       | 82,200,000      |
-| WyRandom                    | 771,400,000 | 389,300,000 | 456,500,000   | 183,500,000 | 194,200,000 | 297,000,000      | 282,100,000     |
-| XorShiftRandom              | 796,600,000 | 563,800,000 | 603,100,000   | 212,800,000 | 286,800,000 | 481,000,000      | 392,200,000     |
-| XoroShiroRandom             | 793,500,000 | 557,600,000 | 712,900,000   | 190,200,000 | 244,000,000 | 428,100,000      | 379,800,000     |
+| DotNetRandom                | 550,600,000 | 53,100,000  | 57,400,000    | 45,600,000  | 26,900,000  | 53,700,000       | 53,900,000      |
+| LinearCongruentialGenerator | 814,800,000 | 538,900,000 | 1,335,100,000 | 184,700,000 | 296,500,000 | 591,500,000      | 508,400,000     |
+| IllusionFlow                | 800,200,000 | 489,500,000 | 892,600,000   | 167,600,000 | 268,200,000 | 444,600,000      | 396,100,000     |
+| PcgRandom                   | 796,400,000 | 537,900,000 | 889,500,000   | 184,300,000 | 291,400,000 | 456,500,000      | 412,000,000     |
+| RomuDuo                     | 794,300,000 | 359,300,000 | 766,200,000   | 167,200,000 | 191,600,000 | 446,000,000      | 397,600,000     |
+| SplitMix64                  | 801,100,000 | 537,400,000 | 972,300,000   | 183,800,000 | 296,600,000 | 487,500,000      | 446,600,000     |
+| SquirrelRandom              | 747,700,000 | 383,300,000 | 413,800,000   | 172,300,000 | 204,800,000 | 330,200,000      | 314,200,000     |
+| SystemRandom                | 146,800,000 | 148,300,000 | 65,700,000    | 132,500,000 | 139,500,000 | 59,800,000       | 61,300,000      |
+| UnityRandom                 | 647,700,000 | 77,800,000  | 87,800,000    | 62,100,000  | 39,500,000  | 81,500,000       | 82,400,000      |
+| WyRandom                    | 750,700,000 | 382,900,000 | 447,500,000   | 166,800,000 | 191,700,000 | 296,800,000      | 281,100,000     |
+| XorShiftRandom              | 792,900,000 | 536,400,000 | 606,000,000   | 184,100,000 | 287,300,000 | 442,800,000      | 391,200,000     |
+| XoroShiroRandom             | 789,200,000 | 359,300,000 | 715,100,000   | 167,300,000 | 192,500,000 | 428,900,000      | 383,500,000     |
 
 <!-- RANDOM_BENCHMARKS_END -->
 
@@ -124,13 +124,13 @@ All benchmarks are run for 1 second per operation type to ensure statistical sig
 **Core Guides:**
 
 - [Getting Started](GETTING_STARTED.md) - Your first 5 minutes with Unity Helpers
-- [Main README](README.md) - Complete feature overview
+- [Main README](../README.md) - Complete feature overview
 - [Feature Index](INDEX.md) - Alphabetical reference
 
 **Random Number Generator Features:**
 
-- [README - Random Generators](README.md#random-number-generators) - Full API reference
-- [README - Quick Start](README.md#random-number-generation) - 60-second tutorial
+- [README - Random Generators](../README.md#random-number-generators) - Full API reference
+- [README - Quick Start](../README.md#random-number-generation) - 60-second tutorial
 
 **Related Features:**
 

package/{RELATIONAL_COMPONENTS.md → Docs/RELATIONAL_COMPONENTS.md}

@@ -314,114 +314,120 @@ Notes:
 
 ## Dependency Injection Integrations
 
-Unity Helpers provides optional integration assemblies that only compile when Zenject or VContainer is present in your project. Install the corresponding DI package via the Unity Package Manager and the helpers become available automatically (no additional scripting defines required).
+**Stop choosing between DI and clean hierarchy references** - Unity Helpers provides seamless integrations with Zenject/Extenject, VContainer, and Reflex that automatically wire up your relational component fields right after dependency injection completes.
 
-Why use the DI integrations
+### The DI Pain Point
 
-- Eliminate boilerplate: hydrate relational fields after DI injection automatically.
-- Consistent behavior: integrates with constructor/property injection and works with runtime instantiation.
-- Safe fallback: if the DI binding is missing, falls back to the non-DI path so fields still populate.
+Without these integrations, you're stuck writing `Awake()` methods full of `GetComponent` boilerplate **even when using a DI framework**:
 
-Supported package IDs (auto-detected)
-
-- Zenject/Extenject: `com.extenject.zenject`, `com.modesttree.zenject`, `com.svermeulen.extenject`
-- VContainer: `jp.cysharp.vcontainer`, `jp.hadashikick.vcontainer`
+```csharp
+public class Enemy : MonoBehaviour
+{
+    [Inject] private IHealthSystem _health;  // ✅ DI handles this
 
-Manual or source imports (no UPM)
+    private Animator _animator;               // ❌ Still manual boilerplate
+    private Rigidbody2D _rigidbody;          // ❌ Still manual boilerplate
 
-- If you import Zenject/VContainer as source, a .unitypackage, or a plain DLL, Unity cannot infer package IDs and the `versionDefines` in the asmdefs won’t trigger.
-- Add scripting defines in Project Settings to enable the integrations:
-  - `Project Settings > Player > Other Settings > Scripting Define Symbols`
-  - Add `ZENJECT_PRESENT` when Zenject/Extenject is present and/or `VCONTAINER_PRESENT` when VContainer is present.
-  - Set defines per target platform (Standalone, Android, iOS, etc.).
-  - After adding, Unity recompiles and the optional assemblies under `Runtime/Integrations/*` compile automatically.
+    void Awake()
+    {
+        _animator = GetComponent<Animator>();
+        _rigidbody = GetComponent<Rigidbody2D>();
+        // ... 15 more lines of GetComponent hell
+    }
+}
+```
 
-### Quick Start — VContainer
+### The Integration Solution
 
-1. Register integration in your `LifetimeScope`
+With the DI integrations, **everything just works**:
 
 ```csharp
-using VContainer;
-using VContainer.Unity;
-using WallstopStudios.UnityHelpers.Integrations.VContainer;
-
-public sealed class GameLifetimeScope : LifetimeScope
+public class Enemy : MonoBehaviour
 {
-    protected override void Configure(IContainerBuilder builder)
-    {
-        // Registers IRelationalComponentAssigner and a scene entry point
-        builder.RegisterRelationalComponents();
+    [Inject] private IHealthSystem _health;         // ✅ DI injection
+    [SiblingComponent] private Animator _animator;  // ✅ Relational auto-wiring
+    [SiblingComponent] private Rigidbody2D _rigidbody; // ✅ Relational auto-wiring
 
-        // Or customize scanning (active objects only)
-        // builder.RegisterRelationalComponents(new RelationalSceneAssignmentOptions(includeInactive: false));
-    }
+    // No Awake() needed! Both DI and hierarchy references wired automatically
 }
 ```
 
-1. Build up runtime instances (DI + relational fields)
+### Why Use the DI Integrations
 
-```csharp
-using UnityEngine;
-using VContainer;
-using WallstopStudios.UnityHelpers.Integrations.VContainer;
+- **Zero boilerplate** - No `Awake()` method needed, no manual `GetComponent` calls, no validation code
+- **Consistent behavior** - Works seamlessly with constructor/property/field injection and runtime instantiation
+- **Safe fallback** - Gracefully degrades to standard behavior if DI binding is missing
+- **Risk-free adoption** - Use incrementally, mix DI and non-DI components freely
 
-public sealed class Spawner : MonoBehaviour
-{
-    [Inject] private IObjectResolver _resolver;
-    [SerializeField] private Enemy _enemyPrefab;
+### Supported Packages (Auto-detected)
 
-    public Enemy Spawn(Transform parent)
-    {
-        Enemy enemy = Instantiate(_enemyPrefab, parent);
-        return _resolver.BuildUpWithRelations(enemy);
-    }
-}
-```
+Unity Helpers automatically detects these packages via UPM:
 
-1. Apply to whole hierarchies when needed
+- **Zenject/Extenject**: `com.extenject.zenject`, `com.modesttree.zenject`, `com.svermeulen.extenject`
+- **VContainer**: `jp.cysharp.vcontainer`, `jp.hadashikick.vcontainer`
+- **Reflex**: `com.gustavopsantos.reflex`
 
-```csharp
-_resolver.AssignRelationalHierarchy(root, includeInactiveChildren: false);
-```
+> 💡 **UPM packages work out-of-the-box** - No scripting defines needed!
 
-### Quick Start — Zenject
+### Manual or Source Imports (Non-UPM)
 
-1. Add the installer to your SceneContext
+If you import Zenject/VContainer/Reflex as source code, .unitypackage, or raw DLLs (not via UPM), you need to manually add scripting defines:
 
-- Add a `SceneContext` to your scene.
-- Add `RelationalComponentsInstaller` to the same GameObject.
-- Toggle "Assign Scene On Initialize" to run a one-time scene scan after the container builds.
+1. Open `Project Settings > Player > Other Settings > Scripting Define Symbols`
+2. Add the appropriate define(s) for your target platforms:
+   - `ZENJECT_PRESENT` - When using Zenject/Extenject
+   - `VCONTAINER_PRESENT` - When using VContainer
+   - `REFLEX_PRESENT` - When using Reflex
+3. Unity will recompile and the integration assemblies under `Runtime/Integrations/*` will activate automatically
 
-1. Instantiate prefabs with DI + relational assignment
+### VContainer at a Glance
 
-```csharp
-using UnityEngine;
-using Zenject;
-using WallstopStudios.UnityHelpers.Integrations.Zenject;
+- **Enable once per scope**
 
-public sealed class Spawner
-{
-    readonly DiContainer _container;
-    readonly Enemy _enemyPrefab;
+  ```csharp
+  builder.RegisterRelationalComponents(
+      new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true),
+      enableAdditiveSceneListener: true
+  );
+  ```
 
-    public Spawner(DiContainer container, Enemy enemyPrefab)
-    {
-        _container = container;
-        _enemyPrefab = enemyPrefab;
-    }
+- **Runtime helpers**
+  - `_resolver.InstantiateComponentWithRelations(componentPrefab, parent)`
+  - `_resolver.InstantiateGameObjectWithRelations(rootPrefab, parent, includeInactiveChildren: true)`
+  - `_resolver.AssignRelationalHierarchy(existingRoot, includeInactiveChildren: true)`
+  - `RelationalObjectPools.CreatePoolWithRelations(...)` + `pool.GetWithRelations(resolver)`
 
-    public Enemy Spawn(Transform parent)
-    {
-        return _container.InstantiateComponentWithRelations(_enemyPrefab, parent);
-    }
-}
-```
+- **Full walkthrough**: [DI – VContainer sample](Samples~/DI%20-%20VContainer/README.md)
 
-1. Apply to whole hierarchies
+### Zenject at a Glance
 
-```csharp
-Container.AssignRelationalHierarchy(root, includeInactiveChildren: true);
-```
+- **Install once per scene**
+  - Add `RelationalComponentsInstaller` to your `SceneContext`.
+  - Toggles cover include-inactive scanning, single-pass strategy, and additive-scene listening.
+
+- **Runtime helpers**
+  - `_container.InstantiateComponentWithRelations(componentPrefab, parent)`
+  - `_container.InstantiateGameObjectWithRelations(rootPrefab, parent, includeInactiveChildren: true)`
+  - `_container.AssignRelationalHierarchy(existingRoot, includeInactiveChildren: true)`
+  - Subclass `RelationalMemoryPool<T>` to hydrate pooled items on spawn.
+
+- **Full walkthrough**: [DI – Zenject sample](Samples~/DI%20-%20Zenject/README.md)
+
+### Reflex at a Glance
+
+- **Install once per scene**
+  - Reflex creates a `SceneScope` in each scene. Add `RelationalComponentsInstaller` to the same GameObject (or a child) to bind the relational assigner, run the initial scene scan, and optionally register the additive-scene listener.
+  - Toggles mirror the runtime helpers: include inactive objects, choose scan strategy, and enable additive listening.
+
+- **Runtime helpers**
+  - `_container.InjectWithRelations(existingComponent)` to inject DI fields and hydrate relational attributes on existing objects.
+  - `_container.InstantiateComponentWithRelations(componentPrefab, parent)` for component prefabs.
+  - `_container.InstantiateGameObjectWithRelations(rootPrefab, parent, includeInactiveChildren: true)` for full hierarchies.
+  - `_container.AssignRelationalHierarchy(existingRoot, includeInactiveChildren: true)` to hydrate arbitrary hierarchies after manual instantiation.
+
+- **Full walkthrough**: [DI – Reflex sample](Samples~/DI%20-%20Reflex/README.md)
+
+- Reflex shares the same fallback behaviour: if the assigner is not bound, the helpers call `AssignRelationalComponents()` directly so you can adopt incrementally.
 
 Notes
 
@@ -479,7 +485,21 @@ Beginner-friendly overview
 
 VContainer (1.16.x)
 
-- Runtime usage (LifetimeScope): Call `builder.RegisterRelationalComponents()` in `LifetimeScope.Configure`. The entry point runs automatically after the container builds.
+- Runtime usage (LifetimeScope): Call `builder.RegisterRelationalComponents()` in `LifetimeScope.Configure`. The entry point runs automatically after the container builds. You can enable an additive-scene listener and customize scan options:
+
+  ```csharp
+  using VContainer;
+  using VContainer.Unity;
+  using WallstopStudios.UnityHelpers.Integrations.VContainer;
+
+  protected override void Configure(IContainerBuilder builder)
+  {
+      // Single-pass scan + additive scene listener
+      var options = new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true);
+      builder.RegisterRelationalComponents(options, enableAdditiveSceneListener: true);
+  }
+  ```
+
 - Tests without LifetimeScope: Construct the entry point and call `Initialize()` yourself, and register your `AttributeMetadataCache` instance so the assigner uses it:
 
   ```csharp
@@ -500,7 +520,8 @@ VContainer (1.16.x)
   entry.Initialize();
   ```
 
-  - Inject vs BuildUp: Use `resolver.Inject(component)` before calling `resolver.AssignRelationalComponents(component)`.
+  - Inject vs BuildUp: Use `resolver.InjectWithRelations(component)` to inject + assign in one call, or `resolver.Inject(component)` then `resolver.AssignRelationalComponents(component)`.
+  - Prefabs & GameObjects: `resolver.InstantiateComponentWithRelations(prefab, parent)` or `resolver.InstantiateGameObjectWithRelations(prefab, parent)`; to inject existing hierarchies use `resolver.InjectGameObjectWithRelations(root)`.
 
 - EditMode reliability: In EditMode tests, prefer `[UnityTest]` and `yield return null` after creating objects and after initializing the entry point so Unity has a frame to register new objects before `FindObjectsOfType` runs and to allow assignments to complete.
 - Active scene filter: Entry points operate on the active scene only. In EditMode, create a new scene with `SceneManager.CreateScene`, set it active, and move your test hierarchy into it before calling `Initialize()`.
@@ -508,10 +529,16 @@ VContainer (1.16.x)
 
 Zenject/Extenject
 
-- Runtime usage: Add `RelationalComponentsInstaller` to your `SceneContext`. It binds `IRelationalComponentAssigner` and runs `RelationalComponentSceneInitializer` once the container is ready.
+- Runtime usage: Add `RelationalComponentsInstaller` to your `SceneContext`. It binds `IRelationalComponentAssigner` and runs `RelationalComponentSceneInitializer` once the container is ready. The installer exposes toggles to assign on initialize and to listen for additive scenes.
 - Tests: Bind a concrete `AttributeMetadataCache` instance and construct the assigner with that cache. Then resolve `IInitializable` and call `Initialize()`.
 - EditMode reliability: As with VContainer, consider `[UnityTest]` with a `yield return null` after creating objects and after calling `Initialize()` to allow Unity to register objects and complete assignments.
-- Active scene filter: The initializer operates on the active scene only. Create and set an active scene and move your test hierarchy into it before calling `Initialize()`.
+- Active scene filter: Initial one-time scan operates on the active scene only. The additive-scene listener processes only newly loaded scenes (not all loaded scenes).
+  - Prefabs & GameObjects: `container.InstantiateComponentWithRelations(...)`, `container.InstantiateGameObjectWithRelations(...)`, or `container.InjectGameObjectWithRelations(root)`; to inject + assign a single instance: `container.InjectWithRelations(component)`.
+
+### Object Pools (DI-aware)
+
+- Zenject: use `RelationalMemoryPool<T>` (or `<TParam, T>`) to assign relational fields in `OnSpawned` automatically.
+- VContainer: create pools with `RelationalObjectPools.CreatePoolWithRelations(...)` and rent via `pool.GetWithRelations(resolver)` to inject + assign.
 
 Common pitfalls and how to avoid them
 
@@ -526,7 +553,7 @@ Common pitfalls and how to avoid them
 **Core Guides:**
 
 - [Getting Started](GETTING_STARTED.md) - Your first 5 minutes with Unity Helpers
-- [Main README](README.md) - Complete feature overview
+- [Main README](../README.md) - Complete feature overview
 - [Feature Index](INDEX.md) - Alphabetical reference
 
 **Related Features:**

package/{SERIALIZATION.md → Docs/SERIALIZATION.md}

@@ -646,3 +646,18 @@ References
 - Replace direct `System.Text.Json.JsonSerializer` calls in app code with `Serializer.JsonSerialize/JsonDeserialize/JsonStringify`, or with `Serializer.Serialize/Deserialize` + `SerializationType.Json` to centralize options and Unity converters.
 - Replace any custom protobuf helpers with `Serializer.ProtoSerialize/ProtoDeserialize` or the generic `Serializer.Serialize/Deserialize` APIs. Ensure models are annotated with `[ProtoContract]` and stable `[ProtoMember(n)]` tags.
 - For existing binary saves using BinaryFormatter, prefer migrating to Json or Protobuf. If you must keep BinaryFormatter, scope it to trusted, same-version caches only.
+
+## 2.0 changes
+
+- BinaryFormatter (`SerializationType.SystemBinary`) is deprecated but remains functional for trusted/legacy scenarios. Prefer:
+  - `SerializationType.Json` (System.Text.Json with Unity-aware converters) for readable, diffable content.
+  - `SerializationType.Protobuf` (protobuf-net) for compact, high-performance binary payloads.
+
+## IL2CPP / AOT guidance
+
+System.Text.Json can require extra care under AOT (e.g., IL2CPP):
+
+- Prefer explicit `JsonSerializerOptions` and concrete generic APIs over `object`-based serialization to reduce reflection.
+- For hot POCO models, consider adding a source-generated context (JsonSerializerContext) in your game assembly and pass it to `JsonSerializer` calls.
+- If you rely on many custom converters, ensure they are referenced by code so the linker doesn't strip them. The UnityHelpers converters are referenced via options by default.
+- Avoid deserializing `System.Type` from untrusted input (see `TypeConverter`); this is intended for trusted configs/tools.

package/{SPATIAL_TREES_2D_GUIDE.md → Docs/SPATIAL_TREES_2D_GUIDE.md}

@@ -177,7 +177,7 @@ void Update()
 }
 ```
 
-See [Buffering Pattern](README.md#buffering-pattern) for the complete guide and [Pooling Utilities](README.md#pooling-utilities) for more pooling options.
+See [Buffering Pattern](../README.md#buffering-pattern) for the complete guide and [Pooling Utilities](../README.md#pooling-utilities) for more pooling options.
 
 ## Structures
 
@@ -247,7 +247,7 @@ START: Do your objects move frequently?
 - **Nearest neighbors on static points:** KDTree2D (Balanced)
 - **Fast builds with good-enough queries:** KDTree2D (Unbalanced)
 - **Objects with area; bounds queries primary:** RTree2D
-- **Very frequent movement (every frame):** SpatialHash2D (see [README](README.md#choosing-spatial-structures))
+- **Very frequent movement (every frame):** SpatialHash2D (see [README](../README.md#choosing-spatial-structures))
 
 ## Query Semantics
 

package/{SPATIAL_TREES_3D_GUIDE.md → Docs/SPATIAL_TREES_3D_GUIDE.md}

@@ -167,7 +167,7 @@ void Update()
 }
 ```
 
-See [Buffering Pattern](README.md#buffering-pattern) for the complete guide and [Pooling Utilities](README.md#pooling-utilities) for more pooling options.
+See [Buffering Pattern](../README.md#buffering-pattern) for the complete guide and [Pooling Utilities](../README.md#pooling-utilities) for more pooling options.
 
 ## Structures
 

package/Docs/SPATIAL_TREE_2D_PERFORMANCE.md

@@ -0,0 +1,241 @@
+# 2D Spatial Tree Performance Benchmarks
+
+## TL;DR — What Problem This Solves
+
+- Fast range/bounds/nearest‑neighbor queries on 2D data without scanning everything.
+- Quick picks: QuadTree2D for broad‑phase; KDTree2D (Balanced) for NN; KDTree2D (Unbalanced) for fast rebuilds; RTree2D for bounds‑based data.
+
+This document contains performance benchmarks for the 2D spatial tree implementations in Unity Helpers.
+
+## Available 2D Spatial Trees
+
+- **QuadTree2D** - Easiest to use, good all-around performance
+- **KDTree2D** - Balanced and unbalanced variants available
+- **RTree2D** - Optimized for bounding box queries
+
+### Correctness & Semantics
+
+- QuadTree2D and KdTree2D (balanced and unbalanced) guarantee the same results for the same input data and the same queries. They are both point-based trees and differ only in construction/query performance characteristics.
+- RTree2D is bounds-based (stores rectangles/AABBs), not points. Its spatial knowledge and query semantics operate on rectangles, so its results will intentionally differ for sized objects and bounds intersection queries.
+
+## Performance Benchmarks
+
+<!-- SPATIAL_TREE_BENCHMARKS_START -->
+
+### Datasets
+
+<!-- tabs:start -->
+
+#### **1,000,000 entries**
+
+##### Construction
+
+| Construction      | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D    |
+| ----------------- | ------------------- | --------------------- | ---------- | ---------- |
+| 1,000,000 entries | 3 (0.325s)          | 4 (0.218s)            | 4 (0.221s) | 1 (0.595s) |
+
+##### Elements In Range
+
+| Elements In Range           | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| --------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| Full (~span/2) (r=499.5)    | 58                  | 58                    | 56         | 7       |
+| Half (~span/4) (r=249.8)    | 236                 | 238                   | 215        | 28      |
+| Quarter (~span/8) (r=124.9) | 945                 | 946                   | 815        | 119     |
+| Tiny (~span/1000) (r=1)     | 103,233             | 105,580               | 142,838    | 107,126 |
+
+##### Get Elements In Bounds
+
+| Get Elements In Bounds     | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| -------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| Full (size=999.0x999.0)    | 314                 | 325                   | 344        | 17      |
+| Half (size=499.5x499.5)    | 1,730               | 1,822                 | 1,238      | 73      |
+| Quarter (size=249.8x249.8) | 7,188               | 7,170                 | 3,867      | 379     |
+| Unit (size=1)              | 149,753             | 153,363               | 197,026    | 113,010 |
+
+##### Approximate Nearest Neighbors
+
+| Approximate Nearest Neighbors | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| ----------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| 500 neighbors                 | 8,466               | 16,873                | 12,696     | 70,046  |
+| 100 neighbors                 | 78,952              | 76,476                | 78,720     | 171,372 |
+| 10 neighbors                  | 375,484             | 377,708               | 251,988    | 277,491 |
+| 1 neighbor                    | 551,002             | 508,239               | 276,379    | 299,010 |
+
+#### **100,000 entries**
+
+##### Construction
+
+| Construction    | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D  | RTree2D     |
+| --------------- | ------------------- | --------------------- | ----------- | ----------- |
+| 100,000 entries | 50 (0.020s)         | 83 (0.012s)           | 50 (0.020s) | 49 (0.020s) |
+
+##### Elements In Range
+
+| Elements In Range           | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| --------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| Full (~span/2) (r=199.5)    | 602                 | 602                   | 600        | 73      |
+| Half (~span/4) (r=99.75)    | 1,355               | 1,359                 | 1,248      | 185     |
+| Quarter (~span/8) (r=49.88) | 4,672               | 5,178                 | 4,300      | 723     |
+| Tiny (~span/1000) (r=1)     | 127,810             | 128,060               | 179,544    | 145,029 |
+
+##### Get Elements In Bounds
+
+| Get Elements In Bounds     | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| -------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| Full (size=399.0x249.0)    | 4,436               | 4,468                 | 4,702      | 235     |
+| Half (size=199.5x124.5)    | 9,433               | 11,669                | 7,996      | 967     |
+| Quarter (size=99.75x62.25) | 25,419              | 32,186                | 19,754     | 3,805   |
+| Unit (size=1)              | 184,712             | 185,636               | 245,390    | 155,220 |
+
+##### Approximate Nearest Neighbors
+
+| Approximate Nearest Neighbors | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| ----------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| 500 neighbors                 | 9,986               | 9,929                 | 11,705     | 69,966  |
+| 100 neighbors                 | 49,779              | 87,233                | 55,229     | 233,211 |
+| 10 neighbors                  | 470,175             | 394,286               | 294,299    | 352,517 |
+| 1 neighbor                    | 509,623             | 544,160               | 314,046    | 350,724 |
+
+#### **10,000 entries**
+
+##### Construction
+
+| Construction   | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D   | RTree2D      |
+| -------------- | ------------------- | --------------------- | ------------ | ------------ |
+| 10,000 entries | 533 (0.002s)        | 796 (0.001s)          | 408 (0.002s) | 507 (0.002s) |
+
+##### Elements In Range
+
+| Elements In Range           | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| --------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| Full (~span/2) (r=49.50)    | 5,944               | 5,941                 | 5,936      | 735     |
+| Half (~span/4) (r=24.75)    | 22,272              | 22,233                | 13,861     | 2,919   |
+| Quarter (~span/8) (r=12.38) | 44,278              | 51,526                | 38,041     | 12,217  |
+| Tiny (~span/1000) (r=1)     | 167,798             | 162,582               | 223,371    | 168,224 |
+
+##### Get Elements In Bounds
+
+| Get Elements In Bounds     | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| -------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| Full (size=99.00x99.00)    | 45,222              | 44,244                | 47,466     | 2,412   |
+| Half (size=49.50x49.50)    | 167,135             | 166,097               | 36,985     | 9,274   |
+| Quarter (size=24.75x24.75) | 76,007              | 104,425               | 74,227     | 35,573  |
+| Unit (size=1)              | 242,092             | 234,546               | 320,164    | 181,677 |
+
+##### Approximate Nearest Neighbors
+
+| Approximate Nearest Neighbors | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| ----------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| 500 neighbors                 | 13,178              | 12,888                | 14,441     | 65,299  |
+| 100 neighbors                 | 62,415              | 57,120                | 96,738     | 235,553 |
+| 10 neighbors                  | 418,552             | 392,340               | 316,886    | 420,625 |
+| 1 neighbor                    | 595,519             | 632,000               | 372,667    | 433,485 |
+
+#### **1,000 entries**
+
+##### Construction
+
+| Construction  | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D     | RTree2D        |
+| ------------- | ------------------- | --------------------- | -------------- | -------------- |
+| 1,000 entries | 4,672 (0.000s)      | 5,611 (0.000s)        | 4,847 (0.000s) | 4,764 (0.000s) |
+
+##### Elements In Range
+
+| Elements In Range          | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| -------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| Full (~span/2) (r=24.50)   | 58,142              | 56,029                | 57,082     | 7,394   |
+| Half (~span/4) (r=12.25)   | 60,439              | 76,572                | 57,123     | 14,698  |
+| Quarter (~span/8) (r=6.13) | 95,988              | 108,457               | 95,703     | 37,920  |
+| Tiny (~span/1000) (r=1)    | 239,460             | 237,275               | 333,071    | 251,518 |
+
+##### Get Elements In Bounds
+
+| Get Elements In Bounds    | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| ------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| Full (size=49.00x19.00)   | 499,193             | 498,444               | 508,596    | 24,141  |
+| Half (size=24.50x9.5)     | 167,532             | 291,283               | 126,274    | 75,139  |
+| Quarter (size=12.25x4.75) | 271,878             | 288,421               | 194,135    | 176,768 |
+| Unit (size=1)             | 342,402             | 339,166               | 460,883    | 281,383 |
+
+##### Approximate Nearest Neighbors
+
+| Approximate Nearest Neighbors | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| ----------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| 500 neighbors                 | 46,434              | 47,214                | 40,048     | 70,543  |
+| 100 neighbors                 | 80,837              | 77,933                | 91,884     | 267,760 |
+| 10 neighbors                  | 487,252             | 574,172               | 426,710    | 516,096 |
+| 1 neighbor                    | 754,604             | 618,120               | 404,966    | 594,659 |
+
+#### **100 entries**
+
+##### Construction
+
+| Construction | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D      | RTree2D         |
+| ------------ | ------------------- | --------------------- | --------------- | --------------- |
+| 100 entries  | 37,174 (0.000s)     | 3,938 (0.000s)        | 10,384 (0.000s) | 21,978 (0.000s) |
+
+##### Elements In Range
+
+| Elements In Range          | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| -------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| Full (~span/2) (r=4.5)     | 505,197             | 462,582               | 480,895    | 72,679  |
+| Half (~span/4) (r=2.25)    | 428,579             | 432,700               | 256,227    | 233,286 |
+| Quarter (~span/8) (r=1.13) | 422,859             | 432,362               | 601,655    | 318,360 |
+| Tiny (~span/1000) (r=1)    | 406,482             | 433,055               | 601,161    | 339,515 |
+
+##### Get Elements In Bounds
+
+| Get Elements In Bounds   | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| ------------------------ | ------------------- | --------------------- | ---------- | ------- |
+| Full (size=9x9)          | 2,460,211           | 2,459,261             | 2,542,373  | 223,694 |
+| Half (size=4.5x4.5)      | 572,726             | 561,349               | 365,082    | 372,098 |
+| Quarter (size=2.25x2.25) | 594,157             | 580,857               | 738,232    | 396,288 |
+| Unit (size=1)            | 593,669             | 576,995               | 787,477    | 395,564 |
+
+##### Approximate Nearest Neighbors
+
+| Approximate Nearest Neighbors | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
+| ----------------------------- | ------------------- | --------------------- | ---------- | ------- |
+| 100 neighbors (max)           | 166,728             | 165,861               | 199,072    | 303,148 |
+| 10 neighbors                  | 610,079             | 520,568               | 639,716    | 735,646 |
+| 1 neighbor                    | 457,409             | 765,967               | 667,953    | 818,651 |
+
+<!-- tabs:end -->
+<!-- SPATIAL_TREE_BENCHMARKS_END -->
+
+## Interpreting the Results
+
+All numbers represent **operations per second** (higher is better), except for construction times which show operations per second and absolute time.
+
+### Choosing the Right Tree
+
+**QuadTree2D**:
+
+- Best for: General-purpose 2D spatial queries
+- Strengths: Balanced performance across all operation types, simple to use
+- Weaknesses: Slightly slower than KDTree for point queries
+
+**KDTree2D (Balanced)**:
+
+- Best for: When you need consistent query performance
+- Strengths: Fast nearest-neighbor queries, good for smaller datasets
+- Weaknesses: Slower construction time
+
+**KDTree2D (Unbalanced)**:
+
+- Best for: When you need fast construction and will rebuild frequently
+- Strengths: Fastest construction, similar query performance to balanced
+- Weaknesses: May degrade on pathological data distributions
+
+**RTree2D**:
+
+- Best for: Bounding box queries, especially with large query areas
+- Strengths: Excellent for large bounding box queries, handles overlapping objects well
+- Weaknesses: Slower for point queries and small ranges
+
+### Important Notes
+
+- All spatial trees assume **immutable** positional data
+- If positions change, you must reconstruct the tree
+- Spatial queries are O(log n) vs O(n) for linear search
+- Construction cost is amortized over many queries