Spatial Hashing (#31)

Implements spatial hashing, to performantly run distance checks, find
all entities located in the same cell, or neighboring cells.

CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## UNRELEASED
+
+### New: `GridCell` Spatial Hashing
+
+Spatial hashing makes fast spatial queries and neighbor lookups possible. This release adds the `GridHashMap`, an automatically updated map of the entities in each grid cell. This makes it possible to query things like:
+
+- What other entities are in the same cell as this entity?
+- Are these two entities in the same cell?
+- What entities are in adjacent grid cells?
+
+This introduces a new component, the `GridHash`, which is automatically kept up to date, and stores a precomputed hash. This makes the spatial hash map especially fast, because hashing is only done when an entity moves between cells, not every time a hash map lookup is needed.
+
+The map has received a few rounds of optimization passes to make incremental updates and neighbor lookups especially fast. This map does not suffer from hash collisions.
+
+### New: Spatial Partitioning
+
+Built on top of the new spatial hashing feature is the `GridPartitionMap`. This map tracks groups of adjacent grid cells that have at least one entity. Each of these partitions contains many entities, and each partition is independent. That is, entities in partition A are guaranteed to be unable to collide with entities in partition B.
+
+This lays the groundwork for adding physics integrations. Because each partition is a clump of entities independent from all other entities, it should be possible to have independent physics simulations for each partition. Not only will this allow for extreme parallelism, it becomes possible to use 32-bit physics simulations in a 160-bit big_space.
+
+### `ReferenceFrame` Renamed `Grid`
+
+While revisiting documentation, it became clear that the naming scheme can be confusing and inconsistent. Most notably, it wasn't immediately clear there is a relationship between `ReferenceFrame` and `GridCell`. Additionally, there were multiple places where reference frames were clarified to be fixed precision grids.
+
+To clear this up, `ReferenceFrame` has been renamed `Grid`. The core spatial types in this library are now:
+
+- `Grid`: Defines the size of a grid for its child cells.
+- `GridCell`: Cell index of an entity within its parent's grid.
+- `GridPrecision`: Integer precision of a grid.
+
+The newly added types follow this pattern:
+
+- `GridHash`: The spatial hash of an entity's grid cell.
+- `GridHashMap`: A map for entity, grid cell, and neighbor lookups.
+- `GridPartition`: Group of adjacent grid cells.
+- `GridPartitionMap`: A map for finding independent partitions of entities.
+
+
+It should now be more clear how all of the `Grid` types are related to each other.

Cargo.toml

@@ -8,13 +8,20 @@ keywords = ["bevy", "floating-origin", "large-scale", "space"]
 repository = "https://github.com/aevyrie/big_space"
 documentation = "https://docs.rs/crate/big_space/latest"
 
+[features]
+default = []
+debug = ["bevy_gizmos", "bevy_color"]
+camera = ["bevy_render", "bevy_time", "bevy_input"]
+
 [dependencies]
-tracing = { version = "0.1", default-features = false }
+tracing = "0.1" # Less deps than pulling in bevy_log
+smallvec = "1.13.2" # Already used by bevy in commands
 bevy_app = { version = "0.15.0", default-features = false }
-bevy_ecs = { version = "0.15.0", default-features = false }
+bevy_ecs = { version = "0.15.0", default-features = true }
 bevy_hierarchy = { version = "0.15.0", default-features = false }
 bevy_math = { version = "0.15.0", default-features = false }
 bevy_reflect = { version = "0.15.0", default-features = false }
+bevy_tasks = { version = "0.15.0", default-features = false }
 bevy_transform = { version = "0.15.0", default-features = false, features = [
     "bevy-support",
 ] }
@@ -26,9 +33,12 @@ bevy_render = { version = "0.15.0", default-features = false, optional = true }
 bevy_input = { version = "0.15.0", default-features = false, optional = true }
 bevy_time = { version = "0.15.0", default-features = false, optional = true }
 
+
 [dev-dependencies]
+big_space = { path = "", features = ["debug", "camera"] }
 bevy = { version = "0.15.0", default-features = false, features = [
     "bevy_scene",
+    "bevy_asset",
     "bevy_gltf",
     "bevy_winit",
     "default_font",
@@ -41,45 +51,57 @@ bevy = { version = "0.15.0", default-features = false, features = [
     "tonemapping_luts",
     "multi_threaded",
 ] }
-rand = "0.8.5"
+noise = "0.9"
+turborand = "0.10"
+criterion = "0.5"
+bytemuck = "1.20"
+bevy_hanabi = "0.14"
 
-[features]
-default = ["debug", "camera", "bevy_render"]
-debug = ["bevy_gizmos", "bevy_color"]
-camera = ["bevy_render", "bevy_time", "bevy_input"]
+[[bench]]
+name = "benchmarks"
+harness = false
+
+[[example]]
+name = "debug"
+path = "examples/debug.rs"
+doc-scrape-examples = true
 
 [[example]]
 name = "demo"
 path = "examples/demo.rs"
-required-features = ["default"]
 doc-scrape-examples = true
 
 [[example]]
-name = "debug"
-path = "examples/debug.rs"
-required-features = ["default"]
+name = "error_child"
+path = "examples/error_child.rs"
 doc-scrape-examples = true
 
 [[example]]
 name = "error"
 path = "examples/error.rs"
-required-features = ["default"]
 doc-scrape-examples = true
 
 [[example]]
-name = "error_child"
-path = "examples/error_child.rs"
-required-features = ["default"]
+name = "infinite"
+path = "examples/infinite.rs"
+doc-scrape-examples = true
+
+[[example]]
+name = "minimal"
+path = "examples/minimal.rs"
+doc-scrape-examples = true
+
+[[example]]
+name = "particles"
+path = "examples/particles.rs"
 doc-scrape-examples = true
 
 [[example]]
 name = "planets"
 path = "examples/planets.rs"
-required-features = ["default"]
 doc-scrape-examples = true
 
 [[example]]
 name = "split_screen"
 path = "examples/split_screen.rs"
-required-features = ["default"]
 doc-scrape-examples = true

README.md

@@ -1,40 +1,31 @@
 <div align="center">
-  
+
 # Big Space
 
+<img src="https://raw.githubusercontent.com/aevyrie/big_space/refs/heads/main/assets/bigspacebanner.svg" width="80%">
+
+Huge worlds, high performance, no dependencies, ecosystem compatibility. [Read the docs](https://docs.rs/big_space)
+
 [![crates.io](https://img.shields.io/crates/v/big_space)](https://crates.io/crates/big_space)
 [![docs.rs](https://docs.rs/big_space/badge.svg)](https://docs.rs/big_space)
 [![test suite](https://github.com/aevyrie/big_space/actions/workflows/rust.yml/badge.svg)](https://github.com/aevyrie/big_space/actions/workflows/rust.yml)
-[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-main-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)
-
-A floating origin plugin for [Bevy](https://github.com/bevyengine/bevy).
-
-https://user-images.githubusercontent.com/2632925/215318129-5bab3095-a7dd-455b-a4b6-71840cde096c.mp4
-
-### [Read the docs](https://docs.rs/big_space)
 
 </div>
 
-## Features
-
-Lots of space to play in.
-
-This is a floating origin plugin, useful if you want to work with very large or very small scales. It works with bevy's existing `f32`-based `Transform`s, which means it's largely compatible with the bevy ecosystem. The plugin positions entities within large fixed precision grids, effectively adding precision to the location of objects.
-
-Additionally, you can use reference frames to nest high precision coordinate systems. For example you might want to put all entities on a planet's surface into the same reference frame. You can then rotate this reference frame with the planet, and orbit that planet around a star.
-
-The plugin is generic over a few integer types, to trade off scale and precision for memory use. Some fun numbers with a worst case precision of 0.5mm:
-  - `i8`: 2,560 km = 74% of the diameter of the Moon
-  - `i16`: 655,350 km = 85% of the diameter of the Moon's orbit around Earth
-  - `i32`: 0.0045 light years = ~4 times the width of the solar system
-  - `i64`: 19.5 million light years = ~100 times the width of the milky way galaxy
-  - `i128`: 3.6e+26 light years = ~3.9e+15 times the width of the observable universe
-
-This can also be used for small scales. With a cell edge length of `1e-11`, and using `i128`, there is enough precision to render objects the size of quarks anywhere in the observable universe.
+## Highlights
 
-From the docs: https://docs.rs/big_space/latest/big_space/precision/trait.GridPrecision.html
+- Enough precision to render proton-sized meshes across the observable universe.
+- Uses `Transform`, making it compatible with most of the Bevy ecosystem.
+- No added dependencies.
+- Absolute coordinates without drift, unlike camera-relative or periodic recentering solutions.
+- Chunks the world into integer grids, from `i8` up to `i128`.
+- Grids can be nested.
+- Spatial hashing for fast grid cell lookups and neighbor search.
+- Spatial partitioning to group sets of disconnected entities.
+- 3-5x faster than Bevy's transform propagation for wide hierarchies.
+- 👉 [Extensive documentation you should read.](https://docs.rs/big_space)
 
-# Bevy Version Support
+## Bevy Version Support
 
 | bevy | big_space |
 | ---- | --------- |

assets/fonts/FiraMono-LICENSE

@@ -0,0 +1,93 @@
+Digitized data copyright (c) 2012-2015, The Mozilla Foundation and Telefonica S.A.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.