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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (264) hide show
  1. package/.editorconfig +1 -1
  2. package/.gitattributes +1 -1
  3. package/.githooks/pre-commit +31 -5
  4. package/.githooks/pre-push +50 -0
  5. package/.github/dependabot.yml +24 -2
  6. package/.github/scripts/check-markdown-links.ps1 +77 -0
  7. package/.github/scripts/check_markdown_links.py +89 -0
  8. package/.github/scripts/check_markdown_url_encoding.py +74 -0
  9. package/.github/scripts/validate_markdown_links.py +194 -0
  10. package/.github/workflows/csharpier-autofix.yml +152 -0
  11. package/.github/workflows/format-on-demand.yml +305 -0
  12. package/.github/workflows/lint-doc-links.yml +8 -5
  13. package/.github/workflows/markdown-json.yml +6 -2
  14. package/.github/workflows/npm-publish.yml +1 -1
  15. package/.github/workflows/prettier-autofix.yml +195 -0
  16. package/.github/workflows/update-dotnet-tools.yml +80 -0
  17. package/.github/workflows/yaml-format-lint.yml +41 -0
  18. package/.lychee.toml +4 -4
  19. package/.markdownlint.jsonc +21 -0
  20. package/.pre-commit-config.yaml +11 -3
  21. package/.yamllint.yaml +31 -0
  22. package/AGENTS.md +5 -1
  23. package/Docs/CHANGELOG.md +11 -0
  24. package/Docs/CONTRIBUTING.md +49 -0
  25. package/Docs/CONTRIBUTING.md.meta +7 -0
  26. package/{EDITOR_TOOLS_GUIDE.md → Docs/EDITOR_TOOLS_GUIDE.md} +4 -0
  27. package/Docs/EFFECTS_SYSTEM.md +1316 -0
  28. package/{EFFECTS_SYSTEM_TUTORIAL.md → Docs/EFFECTS_SYSTEM_TUTORIAL.md} +1 -1
  29. package/{GETTING_STARTED.md → Docs/GETTING_STARTED.md} +50 -64
  30. package/{GLOSSARY.md → Docs/GLOSSARY.md} +4 -4
  31. package/Docs/HELPER_UTILITIES.md +885 -0
  32. package/Docs/HELPER_UTILITIES.md.meta +7 -0
  33. package/{INDEX.md → Docs/INDEX.md} +107 -62
  34. package/Docs/MATH_AND_EXTENSIONS.md +1039 -0
  35. package/{RANDOM_PERFORMANCE.md → Docs/RANDOM_PERFORMANCE.md} +15 -15
  36. package/{RELATIONAL_COMPONENTS.md → Docs/RELATIONAL_COMPONENTS.md} +111 -84
  37. package/{SERIALIZATION.md → Docs/SERIALIZATION.md} +15 -0
  38. package/{SPATIAL_TREES_2D_GUIDE.md → Docs/SPATIAL_TREES_2D_GUIDE.md} +2 -2
  39. package/{SPATIAL_TREES_3D_GUIDE.md → Docs/SPATIAL_TREES_3D_GUIDE.md} +1 -1
  40. package/Docs/SPATIAL_TREE_2D_PERFORMANCE.md +241 -0
  41. package/Docs/SPATIAL_TREE_3D_PERFORMANCE.md +243 -0
  42. package/{THIRD_PARTY_NOTICES.md → Docs/THIRD_PARTY_NOTICES.md} +1 -1
  43. package/Docs/UTILITY_COMPONENTS.md +906 -0
  44. package/Docs/UTILITY_COMPONENTS.md.meta +7 -0
  45. package/Docs/VISUAL_COMPONENTS.md +337 -0
  46. package/Docs/VISUAL_COMPONENTS.md.meta +7 -0
  47. package/Editor/AnimationEventEditor.cs +337 -160
  48. package/Editor/Core/Helper/AnimationEventHelpers.cs +178 -152
  49. package/Editor/CustomEditors/PersistentDirectoryGUI.cs +20 -11
  50. package/Editor/CustomEditors/TexturePlatformOverrideEntryDrawer.cs +11 -2
  51. package/Editor/FitTextureSizeWindow.cs +43 -19
  52. package/Editor/PersistentDirectorySettings.cs +64 -12
  53. package/Editor/PrefabChecker.cs +72 -5
  54. package/Editor/Sprites/AnimationCopier.cs +131 -55
  55. package/Editor/Sprites/AnimationCreator.cs +63 -22
  56. package/Editor/Sprites/AnimationViewerWindow.cs +42 -6
  57. package/Editor/Sprites/TexturePlatformNameHelper.cs +50 -39
  58. package/Editor/Sprites/TextureResizerWizard.cs +23 -1
  59. package/Editor/Sprites/TextureSettingsApplierWindow.cs +148 -85
  60. package/Editor/Tools/ImageBlurTool.cs +81 -10
  61. package/Editor/Utils/EditorUi.cs +1 -1
  62. package/Editor/Utils/ScriptableObjectSingletonCreator.cs +1 -1
  63. package/README.md +428 -2433
  64. package/Runtime/AssemblyInfo.cs +4 -0
  65. package/Runtime/Core/Attributes/NotNullAttribute.cs +1 -3
  66. package/Runtime/Core/Attributes/RelationalComponentAssigner.cs +50 -5
  67. package/Runtime/Core/DataStructure/CyclicBuffer.cs +0 -1
  68. package/Runtime/Core/DataStructure/KDTree3D.cs +1 -1
  69. package/Runtime/Core/DataStructure/OctTree3D.cs +1 -1
  70. package/Runtime/Core/Extension/AsyncOperationExtensions.cs +122 -0
  71. package/Runtime/Core/Extension/RandomExtensions.cs +68 -0
  72. package/Runtime/Core/Extension/WallstopStudiosLogger.cs +16 -0
  73. package/Runtime/Core/Helper/Partials/ObjectHelpers.cs +4 -1
  74. package/Runtime/Core/Helper/ReflectionHelpers.cs +21 -10
  75. package/Runtime/Core/Helper/SpriteHelpers.cs +3 -1
  76. package/Runtime/Core/Helper/UnityMainThreadDispatcher.cs +45 -1
  77. package/Runtime/Core/Serialization/JsonConverters/GameObjectConverter.cs +13 -5
  78. package/Runtime/Core/Serialization/JsonConverters/ResolutionConverter.cs +1 -1
  79. package/Runtime/Core/Serialization/JsonConverters/TypeConverter.cs +1 -1
  80. package/Runtime/Core/Serialization/ProtobufUnitySurrogates.cs +24 -29
  81. package/Runtime/Core/Serialization/Serializer.cs +101 -0
  82. package/Runtime/Integrations/Reflex/AssemblyInfo.cs +7 -0
  83. package/Runtime/Integrations/Reflex/AssemblyInfo.cs.meta +11 -0
  84. package/Runtime/Integrations/Reflex/ContainerRelationalExtensions.cs +198 -0
  85. package/Runtime/Integrations/Reflex/ContainerRelationalExtensions.cs.meta +11 -0
  86. package/Runtime/Integrations/Reflex/RelationalComponentsInstaller.cs +86 -0
  87. package/Runtime/Integrations/Reflex/RelationalComponentsInstaller.cs.meta +11 -0
  88. package/Runtime/Integrations/Reflex/RelationalReflexSceneBootstrapper.cs +316 -0
  89. package/Runtime/Integrations/Reflex/RelationalReflexSceneBootstrapper.cs.meta +11 -0
  90. package/Runtime/Integrations/Reflex/RelationalSceneAssignmentOptions.cs +86 -0
  91. package/Runtime/Integrations/Reflex/RelationalSceneAssignmentOptions.cs.meta +11 -0
  92. package/Runtime/Integrations/Reflex/WallstopStudios.UnityHelpers.Integration.Reflex.asmdef +20 -0
  93. package/Runtime/Integrations/Reflex/WallstopStudios.UnityHelpers.Integration.Reflex.asmdef.meta +7 -0
  94. package/Runtime/Integrations/Reflex.meta +8 -0
  95. package/Runtime/Integrations/VContainer/AssemblyInfo.cs +9 -0
  96. package/Runtime/Integrations/VContainer/AssemblyInfo.cs.meta +3 -0
  97. package/Runtime/Integrations/VContainer/ObjectResolverRelationalExtensions.cs +96 -0
  98. package/Runtime/Integrations/VContainer/RelationalComponentEntryPoint.cs +90 -10
  99. package/Runtime/Integrations/VContainer/RelationalComponentsBuilderExtensions.cs +13 -1
  100. package/Runtime/Integrations/VContainer/RelationalObjectPools.cs +114 -0
  101. package/Runtime/Integrations/VContainer/RelationalObjectPools.cs.meta +11 -0
  102. package/Runtime/Integrations/VContainer/RelationalSceneAssignmentOptions.cs +16 -4
  103. package/Runtime/Integrations/VContainer/RelationalSceneLoadListener.cs +241 -0
  104. package/Runtime/Integrations/VContainer/RelationalSceneLoadListener.cs.meta +11 -0
  105. package/Runtime/Integrations/Zenject/AssemblyInfo.cs +9 -0
  106. package/Runtime/Integrations/Zenject/AssemblyInfo.cs.meta +3 -0
  107. package/Runtime/Integrations/Zenject/DiContainerRelationalExtensions.cs +69 -2
  108. package/Runtime/Integrations/Zenject/RelationalComponentSceneInitializer.cs +89 -12
  109. package/Runtime/Integrations/Zenject/RelationalComponentsInstaller.cs +23 -1
  110. package/Runtime/Integrations/Zenject/RelationalMemoryPools.cs +44 -0
  111. package/Runtime/Integrations/Zenject/RelationalMemoryPools.cs.meta +11 -0
  112. package/Runtime/Integrations/Zenject/RelationalSceneAssignmentOptions.cs +16 -10
  113. package/Runtime/Integrations/Zenject/RelationalSceneLoadListener.cs +243 -0
  114. package/Runtime/Integrations/Zenject/RelationalSceneLoadListener.cs.meta +11 -0
  115. package/Runtime/Tags/AttributeMetadataCache.cs +1 -4
  116. package/Runtime/Utils/Buffers.cs +4 -4
  117. package/Runtime/Utils/ScriptableObjectSingleton.cs +1 -2
  118. package/Runtime/Utils/SetTextureImportData.cs +3 -1
  119. package/Runtime/Utils/TextureScale.cs +10 -2
  120. package/Runtime/Visuals/UGUI/EnhancedImage.cs +6 -0
  121. package/Runtime/Visuals/UIToolkit/LayeredImage.cs +4 -1
  122. package/Samples~/DI - Reflex/README.md +527 -0
  123. package/Samples~/DI - Reflex/README.md.meta +7 -0
  124. package/Samples~/DI - Reflex/Scripts/ReflexPaletteService.cs +36 -0
  125. package/Samples~/DI - Reflex/Scripts/ReflexPaletteService.cs.meta +11 -0
  126. package/Samples~/DI - Reflex/Scripts/ReflexRelationalConsumer.cs +79 -0
  127. package/Samples~/DI - Reflex/Scripts/ReflexRelationalConsumer.cs.meta +11 -0
  128. package/Samples~/DI - Reflex/Scripts/ReflexSampleInstaller.cs +30 -0
  129. package/Samples~/DI - Reflex/Scripts/ReflexSampleInstaller.cs.meta +11 -0
  130. package/Samples~/DI - Reflex/Scripts/ReflexSpawner.cs +79 -0
  131. package/Samples~/DI - Reflex/Scripts/ReflexSpawner.cs.meta +11 -0
  132. package/Samples~/DI - Reflex/Scripts/Samples.UnityHelpers.DI.Reflex.asmdef +26 -0
  133. package/Samples~/DI - Reflex/Scripts/Samples.UnityHelpers.DI.Reflex.asmdef.meta +9 -0
  134. package/Samples~/DI - Reflex/Scripts.meta +8 -0
  135. package/Samples~/DI - Reflex.meta +8 -0
  136. package/Samples~/DI - VContainer/README.md +238 -56
  137. package/Samples~/DI - VContainer/Scripts/GameLifetimeScope.cs +22 -4
  138. package/Samples~/DI - VContainer/Scripts/RelationalConsumer.cs +5 -2
  139. package/Samples~/DI - VContainer/Scripts/Spawner.cs +113 -4
  140. package/Samples~/DI - Zenject/README.md +223 -58
  141. package/Samples~/DI - Zenject/Scripts/RelationalConsumer.cs +3 -0
  142. package/Samples~/DI - Zenject/Scripts/RelationalConsumerPool.cs +37 -0
  143. package/Samples~/DI - Zenject/Scripts/RelationalConsumerPool.cs.meta +12 -0
  144. package/Samples~/DI - Zenject/Scripts/SpawnerZenject.cs +74 -3
  145. package/Samples~/Random - PRNG/README.md +2 -1
  146. package/Samples~/Relational Components - Basic/README.md +3 -1
  147. package/Samples~/Serialization - JSON/README.md +2 -1
  148. package/Samples~/Spatial Structures - 2D and 3D/README.md +2 -1
  149. package/Samples~/UGUI - EnhancedImage/README.md +2 -1
  150. package/Samples~/UI Toolkit - MultiFile Selector (Editor)/README.md +2 -1
  151. package/Tests/Editor/Attributes/AnimationEventHelpersTests.cs +16 -0
  152. package/Tests/Editor/Core/Attributes/RelationalComponentAssignerTests.cs +32 -34
  153. package/Tests/Editor/Integrations/Reflex/ReflexIntegrationCompilationTests.cs +41 -0
  154. package/Tests/Editor/Integrations/Reflex/ReflexIntegrationCompilationTests.cs.meta +11 -0
  155. package/Tests/Editor/Integrations/Reflex/WallstopStudios.UnityHelpers.Tests.Editor.Reflex.asmdef +27 -0
  156. package/Tests/Editor/Integrations/Reflex/WallstopStudios.UnityHelpers.Tests.Editor.Reflex.asmdef.meta +7 -0
  157. package/Tests/Editor/Integrations/Reflex.meta +8 -0
  158. package/Tests/Editor/Integrations/VContainer/VContainerRelationalEntryPointTests.cs +21 -18
  159. package/Tests/Editor/Integrations/VContainer/VContainerRelationalHelpersTests.cs +164 -0
  160. package/Tests/Editor/Integrations/VContainer/VContainerRelationalHelpersTests.cs.meta +11 -0
  161. package/Tests/Editor/Integrations/VContainer/WallstopStudios.UnityHelpers.Tests.Editor.VContainer.asmdef +2 -1
  162. package/Tests/Editor/Integrations/Zenject/WallstopStudios.UnityHelpers.Tests.Editor.Zenject.asmdef +3 -2
  163. package/Tests/Editor/Integrations/Zenject/ZenjectRelationalHelpersTests.cs +127 -0
  164. package/Tests/Editor/Integrations/Zenject/ZenjectRelationalHelpersTests.cs.meta +11 -0
  165. package/Tests/Editor/Integrations/Zenject/ZenjectRelationalInitializerTests.cs +25 -23
  166. package/Tests/Editor/PersistentDirectorySettingsTests.cs +58 -0
  167. package/Tests/Editor/PersistentDirectorySettingsTests.cs.meta +11 -0
  168. package/Tests/Editor/PrefabCheckerReportTests.cs +32 -0
  169. package/Tests/Editor/PrefabCheckerReportTests.cs.meta +11 -0
  170. package/Tests/Editor/Sprites/AnimationCopierFilterTests.cs +63 -0
  171. package/Tests/Editor/Sprites/AnimationCopierFilterTests.cs.meta +11 -0
  172. package/Tests/Editor/Sprites/AnimationCopierWindowTests.cs +1 -1
  173. package/Tests/Editor/Sprites/AnimationViewerWindowTests.cs +38 -0
  174. package/Tests/Editor/Sprites/AnimationViewerWindowTests.cs.meta +11 -0
  175. package/Tests/Editor/Sprites/ScriptableSpriteAtlasEditorTests.cs +1 -1
  176. package/Tests/Editor/Sprites/SpriteCropperAdditionalTests.cs +12 -12
  177. package/Tests/Editor/Sprites/SpriteCropperTests.cs +9 -9
  178. package/Tests/Editor/Sprites/SpritePivotAdjusterTests.cs +3 -3
  179. package/Tests/Editor/Sprites/TexturePlatformNameHelperTests.cs +18 -0
  180. package/Tests/Editor/Sprites/TextureResizerWizardTests.cs +5 -5
  181. package/Tests/Editor/Sprites/TextureSettingsApplierAPITests.cs +3 -3
  182. package/Tests/Editor/Sprites/TextureSettingsApplierWizardAdditionalTests.cs +4 -4
  183. package/Tests/Editor/Sprites/TextureSettingsApplierWizardTests.cs +4 -4
  184. package/Tests/Editor/Tools/ImageBlurToolTests.cs +22 -110
  185. package/Tests/Editor/Utils/CommonTestBase.cs +60 -1
  186. package/Tests/Editor/Utils/ScriptableObjectSingletonCreatorTests.cs +6 -6
  187. package/Tests/Editor/Windows/FitTextureSizeWindowTests.cs +66 -74
  188. package/Tests/Runtime/Attributes/RelationalComponentInitializerTests.cs +4 -15
  189. package/Tests/Runtime/DataStructures/SpatialTree3DBoundsConsistencyTests.cs +29 -29
  190. package/Tests/Runtime/Extensions/AsyncOperationExtensionsTests.cs +179 -0
  191. package/Tests/Runtime/Extensions/RandomExtensionTests.cs +55 -0
  192. package/Tests/Runtime/Integrations/Reflex/RelationalComponentsReflexTests.cs +445 -0
  193. package/Tests/Runtime/Integrations/Reflex/RelationalComponentsReflexTests.cs.meta +11 -0
  194. package/Tests/Runtime/Integrations/Reflex/WallstopStudios.UnityHelpers.Tests.Runtime.Reflex.asmdef +28 -0
  195. package/Tests/Runtime/Integrations/Reflex/WallstopStudios.UnityHelpers.Tests.Runtime.Reflex.asmdef.meta +7 -0
  196. package/Tests/Runtime/Integrations/Reflex.meta +8 -0
  197. package/Tests/Runtime/Integrations/VContainer/RelationalComponentsVContainerTests.cs +257 -221
  198. package/Tests/Runtime/Integrations/VContainer/RelationalObjectPoolsVContainerTests.cs +91 -0
  199. package/Tests/Runtime/Integrations/VContainer/RelationalObjectPoolsVContainerTests.cs.meta +11 -0
  200. package/Tests/Runtime/Integrations/Zenject/RelationalComponentsZenjectTests.cs +251 -233
  201. package/Tests/Runtime/Performance/RandomPerformanceTests.cs +1 -1
  202. package/Tests/Runtime/Performance/SpatialTree2DPerformanceTests.cs +6 -1
  203. package/Tests/Runtime/Performance/SpatialTree3DPerformanceTests.cs +4 -1
  204. package/Tests/Runtime/Serialization/JsonConverterAdditionalTests.cs +30 -0
  205. package/Tests/Runtime/Serialization/JsonConverterAdditionalTests.cs.meta +11 -0
  206. package/Tests/Runtime/Serialization/JsonConverterTests.cs +8 -12
  207. package/Tests/Runtime/Serialization/JsonRoundtripComprehensiveTests.cs +4 -9
  208. package/Tests/Runtime/Serialization/JsonSerializationTest.cs +16 -5
  209. package/Tests/Runtime/Serialization/ProtoRoundtripComprehensiveTests.cs +13 -13
  210. package/Tests/Runtime/Serialization/SerializerAdditionalTests.cs +12 -0
  211. package/Tests/Runtime/Serialization/SerializerFileIoTests.cs +105 -0
  212. package/Tests/Runtime/Serialization/SerializerFileIoTests.cs.meta +11 -0
  213. package/Tests/Runtime/Serialization/UnityEngineObjectJsonTests.cs +247 -0
  214. package/Tests/Runtime/Serialization/UnityEngineObjectJsonTests.cs.meta +11 -0
  215. package/Tests/Runtime/TestUtils/CommonTestBase.cs +99 -0
  216. package/Tests/Runtime/TestUtils/ReflexTestSupport.cs +111 -0
  217. package/Tests/Runtime/TestUtils/ReflexTestSupport.cs.meta +12 -0
  218. package/Tests/Runtime/Utils/CoroutineHandlerTests.cs +1 -1
  219. package/Tests/Runtime/Utils/LZMAComprehensiveTests.cs +1 -1
  220. package/Tests/Runtime/Utils/LZMATests.cs +1 -1
  221. package/Tests/Runtime/Utils/MatchColliderToSpriteTests.cs +5 -5
  222. package/Tests/Runtime/Visuals/EnhancedImageTests.cs +25 -56
  223. package/Tests/Runtime/Visuals/VisualsTestHelpers.cs +1 -8
  224. package/Tests/TestUtils.meta +8 -0
  225. package/package-lock.json.meta +7 -0
  226. package/package.json +13 -4
  227. package/scripts/check-eol.ps1 +4 -5
  228. package/scripts/lint-tests.ps1 +156 -0
  229. package/scripts/lint-tests.ps1.meta +7 -0
  230. package/scripts/normalize-eol.ps1 +6 -9
  231. package/.github/workflows/csharpier.yml +0 -135
  232. package/CHANGELOG.md +0 -0
  233. package/EFFECTS_SYSTEM.md +0 -242
  234. package/MATH_AND_EXTENSIONS.md +0 -316
  235. package/SPATIAL_TREE_2D_PERFORMANCE.md +0 -238
  236. package/SPATIAL_TREE_3D_PERFORMANCE.md +0 -240
  237. /package/{CHANGELOG.md.meta → Docs/CHANGELOG.md.meta} +0 -0
  238. /package/{DATA_STRUCTURES.md → Docs/DATA_STRUCTURES.md} +0 -0
  239. /package/{DATA_STRUCTURES.md.meta → Docs/DATA_STRUCTURES.md.meta} +0 -0
  240. /package/{EDITOR_TOOLS_GUIDE.md.meta → Docs/EDITOR_TOOLS_GUIDE.md.meta} +0 -0
  241. /package/{EFFECTS_SYSTEM.md.meta → Docs/EFFECTS_SYSTEM.md.meta} +0 -0
  242. /package/{EFFECTS_SYSTEM_TUTORIAL.md.meta → Docs/EFFECTS_SYSTEM_TUTORIAL.md.meta} +0 -0
  243. /package/{GETTING_STARTED.md.meta → Docs/GETTING_STARTED.md.meta} +0 -0
  244. /package/{GLOSSARY.md.meta → Docs/GLOSSARY.md.meta} +0 -0
  245. /package/{HULLS.md → Docs/HULLS.md} +0 -0
  246. /package/{HULLS.md.meta → Docs/HULLS.md.meta} +0 -0
  247. /package/{INDEX.md.meta → Docs/INDEX.md.meta} +0 -0
  248. /package/{LICENSE.md → Docs/LICENSE.md} +0 -0
  249. /package/{LICENSE.md.meta → Docs/LICENSE.md.meta} +0 -0
  250. /package/{MATH_AND_EXTENSIONS.md.meta → Docs/MATH_AND_EXTENSIONS.md.meta} +0 -0
  251. /package/{RANDOM_PERFORMANCE.md.meta → Docs/RANDOM_PERFORMANCE.md.meta} +0 -0
  252. /package/{REFLECTION_HELPERS.md → Docs/REFLECTION_HELPERS.md} +0 -0
  253. /package/{REFLECTION_HELPERS.md.meta → Docs/REFLECTION_HELPERS.md.meta} +0 -0
  254. /package/{RELATIONAL_COMPONENTS.md.meta → Docs/RELATIONAL_COMPONENTS.md.meta} +0 -0
  255. /package/{SERIALIZATION.md.meta → Docs/SERIALIZATION.md.meta} +0 -0
  256. /package/{SINGLETONS.md → Docs/SINGLETONS.md} +0 -0
  257. /package/{SINGLETONS.md.meta → Docs/SINGLETONS.md.meta} +0 -0
  258. /package/{SPATIAL_TREES_2D_GUIDE.md.meta → Docs/SPATIAL_TREES_2D_GUIDE.md.meta} +0 -0
  259. /package/{SPATIAL_TREES_3D_GUIDE.md.meta → Docs/SPATIAL_TREES_3D_GUIDE.md.meta} +0 -0
  260. /package/{SPATIAL_TREE_2D_PERFORMANCE.md.meta → Docs/SPATIAL_TREE_2D_PERFORMANCE.md.meta} +0 -0
  261. /package/{SPATIAL_TREE_3D_PERFORMANCE.md.meta → Docs/SPATIAL_TREE_3D_PERFORMANCE.md.meta} +0 -0
  262. /package/{SPATIAL_TREE_SEMANTICS.md → Docs/SPATIAL_TREE_SEMANTICS.md} +0 -0
  263. /package/{SPATIAL_TREE_SEMANTICS.md.meta → Docs/SPATIAL_TREE_SEMANTICS.md.meta} +0 -0
  264. /package/{THIRD_PARTY_NOTICES.md.meta → Docs/THIRD_PARTY_NOTICES.md.meta} +0 -0
package/SPATIAL_TREE_2D_PERFORMANCE.md DELETED
@@ -1,238 +0,0 @@
1
- # 2D Spatial Tree Performance Benchmarks
2
-
3
- ## TL;DR — What Problem This Solves
4
-
5
- - Fast range/bounds/nearest‑neighbor queries on 2D data without scanning everything.
6
- - Quick picks: QuadTree2D for broad‑phase; KDTree2D (Balanced) for NN; KDTree2D (Unbalanced) for fast rebuilds; RTree2D for bounds‑based data.
7
-
8
- This document contains performance benchmarks for the 2D spatial tree implementations in Unity Helpers.
9
-
10
- ## Available 2D Spatial Trees
11
-
12
- - **QuadTree2D** - Easiest to use, good all-around performance
13
- - **KDTree2D** - Balanced and unbalanced variants available
14
- - **RTree2D** - Optimized for bounding box queries
15
-
16
- ### Correctness & Semantics
17
-
18
- - 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.
19
- - 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.
20
-
21
- ## Performance Benchmarks
22
-
23
- <!-- SPATIAL_TREE_BENCHMARKS_START -->
24
- <!-- tabs:start -->
25
-
26
- ### 1,000,000 entries
27
-
28
- #### Construction
29
-
30
- | Construction | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
31
- | ----------------- | ------------------- | --------------------- | ---------- | ---------- |
32
- | 1,000,000 entries | 4 (0.244s) | 6 (0.153s) | 4 (0.222s) | 2 (0.386s) |
33
-
34
- #### Elements In Range
35
-
36
- | Elements In Range | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
37
- | --------------------------- | ------------------- | --------------------- | ---------- | ------- |
38
- | Full (~span/2) (r=499.5) | 59 | 58 | 56 | 7 |
39
- | Half (~span/4) (r=249.8) | 236 | 236 | 217 | 28 |
40
- | Quarter (~span/8) (r=124.9) | 946 | 945 | 816 | 119 |
41
- | Tiny (~span/1000) (r=1) | 101,504 | 105,285 | 142,984 | 106,816 |
42
-
43
- #### Get Elements In Bounds
44
-
45
- | Get Elements In Bounds | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
46
- | -------------------------- | ------------------- | --------------------- | ---------- | ------- |
47
- | Full (size=999.0x999.0) | 380 | 382 | 344 | 17 |
48
- | Half (size=499.5x499.5) | 1,851 | 1,843 | 1,236 | 75 |
49
- | Quarter (size=249.8x249.8) | 7,483 | 7,248 | 3,887 | 377 |
50
- | Unit (size=1) | 147,825 | 152,474 | 196,544 | 110,185 |
51
-
52
- #### Approximate Nearest Neighbors
53
-
54
- | Approximate Nearest Neighbors | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
55
- | ----------------------------- | ------------------- | --------------------- | ---------- | ------- |
56
- | 500 neighbors | 8,454 | 16,901 | 12,715 | 69,581 |
57
- | 100 neighbors | 77,855 | 76,370 | 78,317 | 175,585 |
58
- | 10 neighbors | 377,857 | 352,657 | 225,271 | 281,743 |
59
- | 1 neighbor | 516,596 | 504,358 | 276,636 | 296,533 |
60
-
61
- ### 100,000 entries
62
-
63
- #### Construction
64
-
65
- | Construction | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
66
- | --------------- | ------------------- | --------------------- | ----------- | ----------- |
67
- | 100,000 entries | 50 (0.020s) | 83 (0.012s) | 50 (0.020s) | 50 (0.020s) |
68
-
69
- #### Elements In Range
70
-
71
- | Elements In Range | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
72
- | --------------------------- | ------------------- | --------------------- | ---------- | ------- |
73
- | Full (~span/2) (r=199.5) | 601 | 601 | 601 | 74 |
74
- | Half (~span/4) (r=99.75) | 1,353 | 1,358 | 1,248 | 186 |
75
- | Quarter (~span/8) (r=49.88) | 4,667 | 5,176 | 4,299 | 724 |
76
- | Tiny (~span/1000) (r=1) | 127,432 | 127,776 | 178,260 | 145,496 |
77
-
78
- #### Get Elements In Bounds
79
-
80
- | Get Elements In Bounds | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
81
- | -------------------------- | ------------------- | --------------------- | ---------- | ------- |
82
- | Full (size=399.0x249.0) | 4,571 | 4,588 | 4,675 | 232 |
83
- | Half (size=199.5x124.5) | 9,686 | 12,037 | 8,043 | 973 |
84
- | Quarter (size=99.75x62.25) | 25,538 | 33,097 | 19,916 | 3,832 |
85
- | Unit (size=1) | 182,094 | 183,264 | 244,353 | 154,606 |
86
-
87
- #### Approximate Nearest Neighbors
88
-
89
- | Approximate Nearest Neighbors | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
90
- | ----------------------------- | ------------------- | --------------------- | ---------- | ------- |
91
- | 500 neighbors | 9,965 | 9,922 | 11,666 | 69,077 |
92
- | 100 neighbors | 49,164 | 92,888 | 55,324 | 216,799 |
93
- | 10 neighbors | 474,916 | 390,202 | 265,444 | 350,326 |
94
- | 1 neighbor | 474,933 | 543,573 | 323,662 | 372,714 |
95
-
96
- #### **10,000 entries**
97
-
98
- ##### Construction
99
-
100
- | Construction | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
101
- | -------------- | ------------------- | --------------------- | ------------ | ------------ |
102
- | 10,000 entries | 537 (0.002s) | 801 (0.001s) | 542 (0.002s) | 504 (0.002s) |
103
-
104
- ##### Elements In Range
105
-
106
- | Elements In Range | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
107
- | --------------------------- | ------------------- | --------------------- | ---------- | ------- |
108
- | Full (~span/2) (r=49.50) | 5,935 | 5,938 | 5,944 | 735 |
109
- | Half (~span/4) (r=24.75) | 22,275 | 22,241 | 13,866 | 2,926 |
110
- | Quarter (~span/8) (r=12.38) | 44,200 | 51,396 | 38,060 | 12,233 |
111
- | Tiny (~span/1000) (r=1) | 166,755 | 161,974 | 232,843 | 168,516 |
112
-
113
- ##### Get Elements In Bounds
114
-
115
- | Get Elements In Bounds | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
116
- | -------------------------- | ------------------- | --------------------- | ---------- | ------- |
117
- | Full (size=99.00x99.00) | 46,195 | 46,083 | 46,681 | 2,426 |
118
- | Half (size=49.50x49.50) | 167,388 | 148,478 | 36,590 | 9,339 |
119
- | Quarter (size=24.75x24.75) | 75,940 | 104,014 | 75,785 | 35,720 |
120
- | Unit (size=1) | 239,397 | 231,168 | 318,259 | 179,268 |
121
-
122
- ##### Approximate Nearest Neighbors
123
-
124
- | Approximate Nearest Neighbors | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
125
- | ----------------------------- | ------------------- | --------------------- | ---------- | ------- |
126
- | 500 neighbors | 13,166 | 13,003 | 14,458 | 64,265 |
127
- | 100 neighbors | 62,425 | 56,807 | 96,006 | 221,880 |
128
- | 10 neighbors | 395,764 | 419,775 | 284,603 | 415,788 |
129
- | 1 neighbor | 597,510 | 602,338 | 369,442 | 459,139 |
130
-
131
- ### 1,000 entries
132
-
133
- #### Construction
134
-
135
- | Construction | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
136
- | ------------- | ------------------- | --------------------- | -------------- | -------------- |
137
- | 1,000 entries | 5,327 (0.000s) | 7,739 (0.000s) | 4,952 (0.000s) | 4,764 (0.000s) |
138
-
139
- #### Elements In Range
140
-
141
- | Elements In Range | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
142
- | -------------------------- | ------------------- | --------------------- | ---------- | ------- |
143
- | Full (~span/2) (r=24.50) | 58,072 | 57,956 | 57,377 | 7,419 |
144
- | Half (~span/4) (r=12.25) | 60,307 | 76,412 | 57,036 | 14,715 |
145
- | Quarter (~span/8) (r=6.13) | 95,578 | 108,397 | 95,395 | 38,031 |
146
- | Tiny (~span/1000) (r=1) | 238,625 | 236,418 | 334,236 | 251,174 |
147
-
148
- #### Get Elements In Bounds
149
-
150
- | Get Elements In Bounds | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
151
- | ------------------------- | ------------------- | --------------------- | ---------- | ------- |
152
- | Full (size=49.00x19.00) | 496,607 | 498,142 | 539,878 | 24,229 |
153
- | Half (size=24.50x9.5) | 165,447 | 287,325 | 127,121 | 75,159 |
154
- | Quarter (size=12.25x4.75) | 255,238 | 273,498 | 194,690 | 176,327 |
155
- | Unit (size=1) | 338,275 | 335,033 | 453,237 | 279,167 |
156
-
157
- #### Approximate Nearest Neighbors
158
-
159
- | Approximate Nearest Neighbors | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
160
- | ----------------------------- | ------------------- | --------------------- | ---------- | ------- |
161
- | 500 neighbors | 46,525 | 47,120 | 38,307 | 69,953 |
162
- | 100 neighbors | 80,804 | 78,180 | 92,282 | 268,937 |
163
- | 10 neighbors | 520,835 | 601,494 | 416,276 | 506,668 |
164
- | 1 neighbor | 725,705 | 581,979 | 388,981 | 591,498 |
165
-
166
- ### 100 entries
167
-
168
- #### Construction
169
-
170
- | Construction | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
171
- | ------------ | ------------------- | --------------------- | --------------- | --------------- |
172
- | 100 entries | 42,553 (0.000s) | 21,929 (0.000s) | 29,325 (0.000s) | 21,786 (0.000s) |
173
-
174
- #### Elements In Range
175
-
176
- | Elements In Range | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
177
- | -------------------------- | ------------------- | --------------------- | ---------- | ------- |
178
- | Full (~span/2) (r=4.5) | 504,629 | 463,895 | 509,215 | 72,746 |
179
- | Half (~span/4) (r=2.25) | 425,242 | 430,575 | 256,046 | 236,805 |
180
- | Quarter (~span/8) (r=1.13) | 425,958 | 430,848 | 593,604 | 338,080 |
181
- | Tiny (~span/1000) (r=1) | 424,528 | 430,448 | 591,691 | 338,365 |
182
-
183
- #### Get Elements In Bounds
184
-
185
- | Get Elements In Bounds | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
186
- | ------------------------ | ------------------- | --------------------- | ---------- | ------- |
187
- | Full (size=9x9) | 2,269,583 | 2,434,901 | 2,501,705 | 224,429 |
188
- | Half (size=4.5x4.5) | 566,944 | 555,712 | 360,504 | 369,394 |
189
- | Quarter (size=2.25x2.25) | 592,102 | 565,569 | 753,693 | 390,919 |
190
- | Unit (size=1) | 592,678 | 595,395 | 784,153 | 386,053 |
191
-
192
- #### Approximate Nearest Neighbors
193
-
194
- | Approximate Nearest Neighbors | KDTree2D (Balanced) | KDTree2D (Unbalanced) | QuadTree2D | RTree2D |
195
- | ----------------------------- | ------------------- | --------------------- | ---------- | ------- |
196
- | 100 neighbors (max) | 165,219 | 164,632 | 200,629 | 306,317 |
197
- | 10 neighbors | 610,304 | 516,470 | 619,678 | 760,800 |
198
- | 1 neighbor | 499,393 | 737,678 | 642,498 | 823,829 |
199
-
200
- <!-- tabs:end -->
201
- <!-- SPATIAL_TREE_BENCHMARKS_END -->
202
-
203
- ## Interpreting the Results
204
-
205
- All numbers represent **operations per second** (higher is better), except for construction times which show operations per second and absolute time.
206
-
207
- ### Choosing the Right Tree
208
-
209
- **QuadTree2D**:
210
-
211
- - Best for: General-purpose 2D spatial queries
212
- - Strengths: Balanced performance across all operation types, simple to use
213
- - Weaknesses: Slightly slower than KDTree for point queries
214
-
215
- **KDTree2D (Balanced)**:
216
-
217
- - Best for: When you need consistent query performance
218
- - Strengths: Fast nearest-neighbor queries, good for smaller datasets
219
- - Weaknesses: Slower construction time
220
-
221
- **KDTree2D (Unbalanced)**:
222
-
223
- - Best for: When you need fast construction and will rebuild frequently
224
- - Strengths: Fastest construction, similar query performance to balanced
225
- - Weaknesses: May degrade on pathological data distributions
226
-
227
- **RTree2D**:
228
-
229
- - Best for: Bounding box queries, especially with large query areas
230
- - Strengths: Excellent for large bounding box queries, handles overlapping objects well
231
- - Weaknesses: Slower for point queries and small ranges
232
-
233
- ### Important Notes
234
-
235
- - All spatial trees assume **immutable** positional data
236
- - If positions change, you must reconstruct the tree
237
- - Spatial queries are O(log n) vs O(n) for linear search
238
- - Construction cost is amortized over many queries
package/SPATIAL_TREE_3D_PERFORMANCE.md DELETED
@@ -1,240 +0,0 @@
1
- # 3D Spatial Tree Performance Benchmarks
2
-
3
- ## TL;DR — What Problem This Solves
4
-
5
- - Need fast “what’s near X?” or “what’s inside this volume?” in 3D.
6
- - These structures avoid scanning every object; queries touch only nearby data.
7
- - Quick picks: OctTree3D for general 3D queries; KDTree3D for nearest‑neighbor on points; RTree3D for volumetric bounds.
8
-
9
- Note: KdTree3D, OctTree3D, and RTree3D are under active development and their APIs/performance may evolve. SpatialHash3D is stable and recommended for broad‑phase neighbor queries with many moving objects.
10
-
11
- For boundary and result semantics across structures, see [Spatial Tree Semantics](SPATIAL_TREE_SEMANTICS.md)
12
-
13
- This document contains performance benchmarks for the 3D spatial tree implementations in Unity Helpers.
14
-
15
- ## Available 3D Spatial Trees
16
-
17
- - **OctTree3D** - Easiest to use, good all-around performance for 3D
18
- - **KDTree3D** - Balanced and unbalanced variants available
19
- - **RTree3D** - Optimized for 3D bounding box queries
20
- - **SpatialHash3D** - Efficient for uniformly distributed moving objects (stable)
21
-
22
- ## Performance Benchmarks
23
-
24
- <!-- SPATIAL_TREE_3D_BENCHMARKS_START -->
25
- <!-- tabs:start -->
26
-
27
- ### 1,000,000 entries
28
-
29
- #### Construction
30
-
31
- | Construction | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
32
- | ----------------- | ------------------- | --------------------- | ---------- | ---------- |
33
- | 1,000,000 entries | 2 (0.405s) | 3 (0.321s) | 4 (0.238s) | 2 (0.369s) |
34
-
35
- #### Elements In Range
36
-
37
- | Elements In Range | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
38
- | --------------------------- | ------------------- | --------------------- | --------- | ------- |
39
- | Full (~span/2) (r=49.50) | 17 | 20 | 33 | 15 |
40
- | Half (~span/4) (r=24.75) | 131 | 160 | 242 | 153 |
41
- | Quarter (~span/8) (r=12.38) | 937 | 1,229 | 1,653 | 1,520 |
42
- | Tiny (~span/1000) (r=1) | 23,510 | 23,699 | 97,513 | 76,591 |
43
-
44
- #### Get Elements In Bounds
45
-
46
- | Get Elements In Bounds | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
47
- | -------------------------------- | ------------------- | --------------------- | --------- | ------- |
48
- | Full (size≈99.00x99.00x99.00) | 33 | 39 | 225 | 23 |
49
- | Half (size≈49.50x49.50x49.50) | 39 | 46 | 1,298 | 276 |
50
- | Quarter (size≈24.75x24.75x24.75) | 40 | 47 | 4,050 | 2,531 |
51
- | Unit (size=1) | 40 | 48 | 182,963 | 77,858 |
52
-
53
- #### Approximate Nearest Neighbors
54
-
55
- | Approximate Nearest Neighbors | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
56
- | ----------------------------- | ------------------- | --------------------- | --------- | ------- |
57
- | 500 neighbors | 5,895 | 10,188 | 2,309 | 304 |
58
- | 100 neighbors | 65,303 | 74,548 | 10,926 | 3,387 |
59
- | 10 neighbors | 408,553 | 419,729 | 16,046 | 7,914 |
60
- | 1 neighbor | 552,534 | 484,025 | 19,874 | 8,610 |
61
-
62
- ### 100,000 entries
63
-
64
- #### Construction
65
-
66
- | Construction | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
67
- | --------------- | ------------------- | --------------------- | ----------- | ----------- |
68
- | 100,000 entries | 34 (0.029s) | 47 (0.021s) | 65 (0.015s) | 44 (0.022s) |
69
-
70
- #### Elements In Range
71
-
72
- | Elements In Range | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
73
- | --------------------------- | ------------------- | --------------------- | --------- | ------- |
74
- | Full (~span/2) (r=49.50) | 335 | 485 | 776 | 213 |
75
- | Half (~span/4) (r=24.75) | 1,021 | 1,434 | 2,047 | 857 |
76
- | Quarter (~span/8) (r=12.38) | 2,568 | 3,994 | 6,043 | 3,441 |
77
- | Tiny (~span/1000) (r=1) | 26,786 | 29,821 | 177,795 | 101,341 |
78
-
79
- #### Get Elements In Bounds
80
-
81
- | Get Elements In Bounds | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
82
- | ------------------------------- | ------------------- | --------------------- | --------- | ------- |
83
- | Full (size≈99.00x99.00x9) | 636 | 778 | 2,716 | 354 |
84
- | Half (size≈49.50x49.50x4.5) | 740 | 909 | 9,663 | 3,518 |
85
- | Quarter (size≈24.75x24.75x2.25) | 752 | 934 | 46,764 | 24,351 |
86
- | Unit (size=1) | 755 | 942 | 245,087 | 103,425 |
87
-
88
- #### Approximate Nearest Neighbors
89
-
90
- | Approximate Nearest Neighbors | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
91
- | ----------------------------- | ------------------- | --------------------- | --------- | ------- |
92
- | 500 neighbors | 6,738 | 12,074 | 1,626 | 271 |
93
- | 100 neighbors | 38,663 | 44,099 | 9,271 | 2,266 |
94
- | 10 neighbors | 424,563 | 310,952 | 19,261 | 7,732 |
95
- | 1 neighbor | 460,856 | 332,893 | 30,086 | 12,328 |
96
-
97
- ### 10,000 entries
98
-
99
- #### Construction
100
-
101
- | Construction | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
102
- | -------------- | ------------------- | --------------------- | ------------ | ------------ |
103
- | 10,000 entries | 450 (0.002s) | 146 (0.007s) | 601 (0.002s) | 435 (0.002s) |
104
-
105
- #### Elements In Range
106
-
107
- | Elements In Range | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
108
- | --------------------------- | ------------------- | --------------------- | --------- | ------- |
109
- | Full (~span/2) (r=49.50) | 4,778 | 4,607 | 9,136 | 1,904 |
110
- | Half (~span/4) (r=24.75) | 5,951 | 6,495 | 8,914 | 3,800 |
111
- | Quarter (~span/8) (r=12.38) | 5,924 | 6,936 | 11,190 | 7,081 |
112
- | Tiny (~span/1000) (r=1) | 41,368 | 38,706 | 220,785 | 157,777 |
113
-
114
- #### Get Elements In Bounds
115
-
116
- | Get Elements In Bounds | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
117
- | ------------------------------ | ------------------- | --------------------- | --------- | ------- |
118
- | Full (size≈99.00x9x9) | 6,536 | 6,552 | 26,350 | 3,597 |
119
- | Half (size≈49.50x4.5x4.5) | 7,376 | 7,413 | 46,213 | 37,593 |
120
- | Quarter (size≈24.75x2.25x2.25) | 7,520 | 7,551 | 168,253 | 121,961 |
121
- | Unit (size=1) | 7,612 | 7,590 | 323,189 | 163,462 |
122
-
123
- #### Approximate Nearest Neighbors
124
-
125
- | Approximate Nearest Neighbors | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
126
- | ----------------------------- | ------------------- | --------------------- | --------- | ------- |
127
- | 500 neighbors | 9,768 | 10,516 | 636 | 184 |
128
- | 100 neighbors | 50,714 | 66,402 | 5,931 | 2,247 |
129
- | 10 neighbors | 441,906 | 453,023 | 27,115 | 13,149 |
130
- | 1 neighbor | 503,317 | 596,546 | 45,358 | 22,171 |
131
-
132
- ### 1,000 entries
133
-
134
- #### Construction
135
-
136
- | Construction | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
137
- | ------------- | ------------------- | --------------------- | -------------- | ------------ |
138
- | 1,000 entries | 1,970 (0.001s) | 5,010 (0.000s) | 4,001 (0.000s) | 661 (0.002s) |
139
-
140
- #### Elements In Range
141
-
142
- | Elements In Range | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
143
- | -------------------------- | ------------------- | --------------------- | --------- | ------- |
144
- | Full (~span/2) (r=4.5) | 12,016 | 14,151 | 24,554 | 19,616 |
145
- | Half (~span/4) (r=2.25) | 52,024 | 62,524 | 124,541 | 148,200 |
146
- | Quarter (~span/8) (r=1.13) | 60,415 | 64,618 | 338,784 | 226,687 |
147
- | Tiny (~span/1000) (r=1) | 62,656 | 64,645 | 338,789 | 226,826 |
148
-
149
- #### Get Elements In Bounds
150
-
151
- | Get Elements In Bounds | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
152
- | ----------------------------- | ------------------- | --------------------- | --------- | ------- |
153
- | Full (size≈9x9x9) | 59,709 | 64,685 | 323,836 | 35,735 |
154
- | Half (size≈4.5x4.5x4.5) | 65,153 | 71,612 | 198,320 | 179,787 |
155
- | Quarter (size≈2.25x2.25x2.25) | 65,827 | 73,267 | 496,693 | 237,774 |
156
- | Unit (size=1) | 65,842 | 74,314 | 496,960 | 238,324 |
157
-
158
- #### Approximate Nearest Neighbors
159
-
160
- | Approximate Nearest Neighbors | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
161
- | ----------------------------- | ------------------- | --------------------- | --------- | ------- |
162
- | 500 neighbors | 15,885 | 14,863 | 3,257 | 617 |
163
- | 100 neighbors | 69,896 | 65,777 | 15,639 | 4,137 |
164
- | 10 neighbors | 473,839 | 394,340 | 73,941 | 33,359 |
165
- | 1 neighbor | 668,802 | 659,922 | 83,425 | 44,659 |
166
-
167
- ### 100 entries
168
-
169
- #### Construction
170
-
171
- | Construction | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
172
- | ------------ | ------------------- | --------------------- | --------------- | --------------- |
173
- | 100 entries | 26,666 (0.000s) | 34,013 (0.000s) | 25,188 (0.000s) | 21,834 (0.000s) |
174
-
175
- #### Elements In Range
176
-
177
- | Elements In Range | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
178
- | -------------------------- | ------------------- | --------------------- | --------- | ------- |
179
- | Full (~span/2) (r=4.5) | 126,202 | 127,160 | 294,794 | 195,711 |
180
- | Half (~span/4) (r=2.25) | 146,998 | 149,086 | 318,059 | 307,466 |
181
- | Quarter (~span/8) (r=1.13) | 147,360 | 150,616 | 393,125 | 403,724 |
182
- | Tiny (~span/1000) (r=1) | 147,348 | 150,680 | 394,470 | 423,009 |
183
-
184
- #### Get Elements In Bounds
185
-
186
- | Get Elements In Bounds | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
187
- | ----------------------- | ------------------- | --------------------- | --------- | ------- |
188
- | Full (size≈9x4x1) | 533,149 | 533,863 | 1,745,022 | 329,398 |
189
- | Half (size≈4.5x2x1) | 557,962 | 567,439 | 514,854 | 460,328 |
190
- | Quarter (size≈2.25x1x1) | 542,713 | 566,118 | 765,601 | 729,872 |
191
- | Unit (size=1) | 572,783 | 566,230 | 764,660 | 692,164 |
192
-
193
- #### Approximate Nearest Neighbors
194
-
195
- | Approximate Nearest Neighbors | KDTree3D (Balanced) | KDTree3D (Unbalanced) | OctTree3D | RTree3D |
196
- | ----------------------------- | ------------------- | --------------------- | --------- | ------- |
197
- | 100 neighbors (max) | 91,290 | 87,287 | 69,665 | 65,698 |
198
- | 10 neighbors | 608,256 | 510,875 | 105,249 | 101,525 |
199
- | 1 neighbor | 850,358 | 628,202 | 173,277 | 224,265 |
200
-
201
- <!-- tabs:end -->
202
- <!-- SPATIAL_TREE_3D_BENCHMARKS_END -->
203
-
204
- ## Interpreting the Results
205
-
206
- All numbers represent **operations per second** (higher is better), except for construction times which show operations per second and absolute time.
207
-
208
- ### Choosing the Right Tree
209
-
210
- **OctTree3D**:
211
-
212
- - Best for: General-purpose 3D spatial queries
213
- - Strengths: Balanced performance, easy to use, good spatial locality
214
- - Use cases: 3D collision detection, visibility culling, spatial audio
215
-
216
- **KDTree3D (Balanced)**:
217
-
218
- - Best for: Nearest-neighbor queries in 3D space
219
- - Strengths: Fast point queries, good for smaller datasets
220
- - Use cases: Pathfinding, AI spatial awareness, particle systems
221
-
222
- **KDTree3D (Unbalanced)**:
223
-
224
- - Best for: When you need fast construction and will rebuild frequently
225
- - Strengths: Fastest construction, similar query performance to balanced
226
- - Use cases: Dynamic environments, frequently changing spatial data
227
-
228
- **RTree3D**:
229
-
230
- - Best for: 3D bounding box queries, especially with volumetric data
231
- - Strengths: Excellent for large bounding volumes, handles overlapping objects
232
- - Use cases: Physics engines, frustum culling, volumetric effects
233
-
234
- ### Important Notes
235
-
236
- - All spatial trees assume **immutable** positional data
237
- - If positions change, you must reconstruct the tree
238
- - Spatial queries are O(log n) vs O(n) for linear search
239
- - 3D trees have higher construction costs than 2D variants due to additional dimension
240
- - Construction cost is amortized over many queries
/package/{CHANGELOG.md.meta → Docs/CHANGELOG.md.meta} RENAMED
File without changes
/package/{DATA_STRUCTURES.md → Docs/DATA_STRUCTURES.md} RENAMED
File without changes
/package/{GLOSSARY.md.meta → Docs/GLOSSARY.md.meta} RENAMED
File without changes
/package/{HULLS.md → Docs/HULLS.md} RENAMED
File without changes
/package/{HULLS.md.meta → Docs/HULLS.md.meta} RENAMED
File without changes
/package/{INDEX.md.meta → Docs/INDEX.md.meta} RENAMED
File without changes
/package/{LICENSE.md → Docs/LICENSE.md} RENAMED
File without changes
/package/{LICENSE.md.meta → Docs/LICENSE.md.meta} RENAMED
File without changes
/package/{SINGLETONS.md → Docs/SINGLETONS.md} RENAMED
File without changes
/package/{SINGLETONS.md.meta → Docs/SINGLETONS.md.meta} RENAMED
File without changes