de_index: Prep for faster indexing alternative (#772)

Currently, only collider based spatial indexing is implemented. It
allows reasonably fast spatial queries, for example ray casting or AABB
search applied on each entity collider.

It is the plan to extend `de_index` with point based indexing (as
opposed to collider based indexing). Point based spatial queries have to
potential to be much faster and yet sufficient for some important
use-cases (i.e. energy grid graph construction). This PR reorganizes
`de_index` so that we can add the alternative indexing alongside it.

Relates to #472.

Author: Indy2222

crates/index/src/lib.rs

@@ -1,26 +1,14 @@
 #![allow(rustdoc::private_intra_doc_links)]
-//! This module implements 2D object partitioning for fast geometric lookup,
-//! for example ray casting.
-//!
-//! The core structure is a square tile grid which points to Bevy ECS entities.
-//! Newly spawned entities are automatically added, despawned entities removed
-//! and moved entities updated by systems added by
-//! [`self::IndexPlugin`].
-mod aabb;
-mod collider;
-mod grid;
-mod index;
-mod range;
-mod segment;
-mod systems;
+//! This crate implements spatial indexing and various spatial queries of game
+//! entities.
 
-use bevy::{app::PluginGroupBuilder, prelude::PluginGroup};
-use systems::IndexPlugin;
+mod precise;
 
-pub use self::{
-    collider::{ColliderWithCache, LocalCollider, QueryCollider},
-    index::{EntityIndex, RayEntityIntersection, SpatialQuery},
-    systems::IndexSet,
+use bevy::{app::PluginGroupBuilder, prelude::PluginGroup};
+use precise::PreciseIndexPlugin;
+pub use precise::{
+    ColliderWithCache, EntityIndex, LocalCollider, PreciseIndexSet, QueryCollider,
+    RayEntityIntersection, SpatialQuery,
 };
 
 /// Size (in world-space) of a single square tile where entities are kept.
@@ -30,6 +18,6 @@ pub struct IndexPluginGroup;
 
 impl PluginGroup for IndexPluginGroup {
     fn build(self) -> PluginGroupBuilder {
-        PluginGroupBuilder::start::<Self>().add(IndexPlugin)
+        PluginGroupBuilder::start::<Self>().add(PreciseIndexPlugin)
     }
 }

crates/index/src/aabb.rs renamed to crates/index/src/precise/aabb.rs

@@ -2,10 +2,10 @@ use ahash::AHashSet;
 use bevy::prelude::Entity;
 use parry3d::bounding_volume::Aabb;
 
-use crate::{grid::TileGrid, range::TileRange};
+use super::{grid::TileGrid, range::TileRange};
 
 /// An iterator over unique entity IDs withing a box.
-pub(crate) struct AabbCandidates<'a> {
+pub(super) struct AabbCandidates<'a> {
     grid: &'a TileGrid,
     tiles: TileRange,
     row: Option<i32>,
@@ -16,7 +16,7 @@ pub(crate) struct AabbCandidates<'a> {
 impl<'a> AabbCandidates<'a> {
     /// Creates a new iterator of entities potentially colliding with a given
     /// AABB.
-    pub(crate) fn new(grid: &'a TileGrid, aabb: &Aabb) -> Self {
+    pub(super) fn new(grid: &'a TileGrid, aabb: &Aabb) -> Self {
         Self {
             grid,
             tiles: TileRange::from_aabb(aabb),

crates/index/src/collider.rs renamed to crates/index/src/precise/collider.rs

@@ -43,20 +43,20 @@ impl LocalCollider {
     }
 
     /// Updates position of cached world-space AABB of the collider.
-    pub(crate) fn update_position(&mut self, position: Isometry<f32>) {
+    pub(super) fn update_position(&mut self, position: Isometry<f32>) {
         self.world_aabb = self.local_aabb.transform_by(&position);
         self.position = position;
     }
 
-    pub(crate) fn cast_ray(&self, ray: &Ray, max_toi: f32) -> Option<f32> {
+    pub(super) fn cast_ray(&self, ray: &Ray, max_toi: f32) -> Option<f32> {
         if self.world_aabb.intersects_local_ray(ray, max_toi) {
             self.object_collider.cast_ray(&self.position, ray, max_toi)
         } else {
             None
         }
     }
 
-    pub(crate) fn intersects(&self, rhs: &impl ColliderWithCache) -> bool {
+    pub(super) fn intersects(&self, rhs: &impl ColliderWithCache) -> bool {
         if self.query_aabb(rhs.world_aabb()) {
             self.object_collider
                 .intersects(&self.position, rhs.inner(), rhs.position())
@@ -67,7 +67,7 @@ impl LocalCollider {
 
     /// Returns true if world-space axis-aligned bounding boxes of the two
     /// colliders intersect.
-    pub(crate) fn query_aabb(&self, aabb: &Aabb) -> bool {
+    pub(super) fn query_aabb(&self, aabb: &Aabb) -> bool {
         self.world_aabb.intersects(aabb)
     }
 }

crates/index/src/grid.rs renamed to crates/index/src/precise/grid.rs

@@ -6,20 +6,20 @@ use bevy::prelude::Entity;
 use glam::IVec2;
 use parry3d::bounding_volume::Aabb;
 
-use crate::range::TileRange;
+use super::range::TileRange;
 
 /// Rectangular (2D) grid of sets of Bevy ECS entities.
 ///
 /// Only non-empty sets are kept (a hash map mapping 2D tile coordinates to
 /// Entity sets is used under the hood). Each set contains entities whose
 /// absolute AABB intersects with the tile.
-pub(crate) struct TileGrid {
+pub(super) struct TileGrid {
     tiles: AHashMap<IVec2, AHashSet<Entity>>,
 }
 
 impl TileGrid {
     /// Creates a new empty grid.
-    pub(crate) fn new() -> Self {
+    pub(super) fn new() -> Self {
         Self {
             tiles: AHashMap::new(),
         }
@@ -36,7 +36,7 @@ impl TileGrid {
     /// # Panics
     ///
     /// Might panic if the entity is already present in the grid.
-    pub(crate) fn insert(&mut self, entity: Entity, aabb: &Aabb) {
+    pub(super) fn insert(&mut self, entity: Entity, aabb: &Aabb) {
         for tile in TileRange::from_aabb(aabb) {
             self.insert_to_tile(entity, tile);
         }
@@ -56,7 +56,7 @@ impl TileGrid {
     ///
     /// Might panic if the entity is not stored in the grid or if the last used
     /// update / insertion AABB differs from the one passed as an argument.
-    pub(crate) fn remove(&mut self, entity: Entity, aabb: &Aabb) {
+    pub(super) fn remove(&mut self, entity: Entity, aabb: &Aabb) {
         for tile in TileRange::from_aabb(aabb) {
             self.remove_from_tile(entity, tile);
         }
@@ -77,7 +77,7 @@ impl TileGrid {
     ///
     /// Might panic if the entity is not present in the grid or if `old_aabb`
     /// differs from the last used update / insert AABB.
-    pub(crate) fn update(&mut self, entity: Entity, old_aabb: &Aabb, new_aabb: &Aabb) {
+    pub(super) fn update(&mut self, entity: Entity, old_aabb: &Aabb, new_aabb: &Aabb) {
         let old_tiles = TileRange::from_aabb(old_aabb);
         let new_tiles = TileRange::from_aabb(new_aabb);
 
@@ -107,7 +107,7 @@ impl TileGrid {
     /// # Arguments
     ///
     /// `tile_coords` - coordinates of the tile.
-    pub(crate) fn get_tile_entities(&self, tile_coords: IVec2) -> Option<&AHashSet<Entity>> {
+    pub(super) fn get_tile_entities(&self, tile_coords: IVec2) -> Option<&AHashSet<Entity>> {
         self.tiles.get(&tile_coords)
     }
 

crates/index/src/index.rs renamed to crates/index/src/precise/index.rs

@@ -18,8 +18,10 @@ use parry3d::{
     shape::Segment,
 };
 
-use super::{collider::LocalCollider, grid::TileGrid, segment::SegmentCandidates};
-use crate::{aabb::AabbCandidates, collider::ColliderWithCache};
+use super::{
+    aabb::AabbCandidates, collider::ColliderWithCache, collider::LocalCollider, grid::TileGrid,
+    segment::SegmentCandidates,
+};
 
 /// 2D rectangular grid based spatial index of entities.
 #[derive(Resource)]
@@ -47,15 +49,15 @@ impl EntityIndex {
         self.colliders.insert(entity, collider);
     }
 
-    pub(crate) fn remove(&mut self, entity: Entity) {
+    pub(super) fn remove(&mut self, entity: Entity) {
         let collider = self
             .colliders
             .remove(&entity)
             .expect("Tried to remove non-existent entity.");
         self.grid.remove(entity, collider.world_aabb());
     }
 
-    pub(crate) fn update(&mut self, entity: Entity, position: Isometry<f32>) {
+    pub(super) fn update(&mut self, entity: Entity, position: Isometry<f32>) {
         let collider = self
             .colliders
             .get_mut(&entity)
@@ -107,7 +109,7 @@ impl Default for EntityIndex {
 /// System parameter implementing various spatial queries.
 ///
 /// Only entities automatically indexed by systems from
-/// [`super::systems::IndexPlugin`] could be retrieved.
+/// [`super::PreciseIndexPlugin`] could be retrieved.
 #[derive(SystemParam)]
 pub struct SpatialQuery<'w, 's, Q, F = ()>
 where
@@ -124,7 +126,7 @@ where
     F: ReadOnlyWorldQuery + Sync + Send + 'static,
 {
     /// Returns closest entity whose shape, as indexed by systems registered by
-    /// [`super::systems::IndexPlugin`], intersects a given ray.
+    /// [`super::PreciseIndexPlugin`], intersects a given ray.
     ///
     /// # Arguments
     ///
@@ -173,7 +175,7 @@ where
     }
 
     /// Returns true if queried solid object on the map, as indexed by
-    /// [`super::systems::IndexPlugin`], intersects with the given collider.
+    /// [`super::PreciseIndexPlugin`], intersects with the given collider.
     pub fn collides(&self, collider: &impl ColliderWithCache) -> bool {
         let candidate_sets = self.index.query_aabb(collider.world_aabb());
         candidate_sets.flatten().any(|candidate| {

crates/index/src/systems.rs renamed to crates/index/src/precise/mod.rs

@@ -1,6 +1,9 @@
-//! Module with systems and a Bevy plugin for automatic entity indexing of
-//! solid entities.
-
+//! This module implements collider based spatial indexing of game entities and
+//! various geometry based lookup (for example ray casting).
+//!
+//! The core structure is a square tile grid which points to Bevy ECS entities.
+//! Newly spawned entities are automatically added, despawned entities removed
+//! and moved entities updated by systems added by [`PreciseIndexPlugin`].
 use bevy::prelude::*;
 use de_core::{
     gamestate::GameState,
@@ -11,8 +14,17 @@ use de_core::{
 use de_objects::SolidObjects;
 use parry3d::math::Isometry;
 
-use super::index::EntityIndex;
-use crate::collider::LocalCollider;
+pub use self::{
+    collider::{ColliderWithCache, LocalCollider, QueryCollider},
+    index::{EntityIndex, RayEntityIntersection, SpatialQuery},
+};
+
+mod aabb;
+mod collider;
+mod grid;
+mod index;
+mod range;
+mod segment;
 
 type SolidEntityQuery<'w, 's> = Query<
     'w,
@@ -38,29 +50,29 @@ type MovedQuery<'w, 's> =
 /// insert newly spawned solid entities to the index, update their position
 /// when [`bevy::prelude::Transform`] is changed and remove the entities from
 /// the index when they are de-spawned.
-pub(crate) struct IndexPlugin;
+pub(super) struct PreciseIndexPlugin;
 
-impl Plugin for IndexPlugin {
+impl Plugin for PreciseIndexPlugin {
     fn build(&self, app: &mut App) {
         app.add_systems(OnEnter(AppState::InGame), setup)
             .add_systems(OnExit(AppState::InGame), cleanup)
             .add_systems(
                 PostUpdate,
                 (insert, remove)
                     .run_if(in_state(GameState::Playing))
-                    .in_set(IndexSet::Index),
+                    .in_set(PreciseIndexSet::Index),
             )
             .add_systems(
                 PostMovement,
                 update
                     .run_if(in_state(GameState::Playing))
-                    .in_set(IndexSet::Index),
+                    .in_set(PreciseIndexSet::Index),
             );
     }
 }
 
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, SystemSet)]
-pub enum IndexSet {
+pub enum PreciseIndexSet {
     Index,
 }
 

crates/index/src/range.rs renamed to crates/index/src/precise/range.rs

@@ -8,7 +8,7 @@ use crate::TILE_SIZE;
 ///
 /// The tiles are iterated row-by-row, for example: (1, 1) -> (2, 1) -> (1, 2)
 /// -> (2, 2).
-pub(crate) struct TileRange {
+pub(super) struct TileRange {
     a: IVec2,
     b: IVec2,
     x: i32,
@@ -21,7 +21,7 @@ impl TileRange {
     ///
     /// Tiles are assumed to be topologically closed. In other words, both
     /// touching and intersecting tiles are included in the range.
-    pub(crate) fn from_aabb(aabb: &Aabb) -> Self {
+    pub(super) fn from_aabb(aabb: &Aabb) -> Self {
         let aabb = aabb.to_flat();
         let min_flat: Vec2 = aabb.mins.into();
         let max_flat: Vec2 = aabb.maxs.into();
@@ -35,7 +35,7 @@ impl TileRange {
     /// * `a` - inclusive range start.
     ///
     /// * `b` - inclusive range end.
-    pub(crate) fn new(a: IVec2, b: IVec2) -> Self {
+    pub(super) fn new(a: IVec2, b: IVec2) -> Self {
         Self {
             a,
             b,
@@ -46,12 +46,12 @@ impl TileRange {
     }
 
     /// Returns true if the given point is not contained in the tile range.
-    pub(crate) fn excludes(&self, point: IVec2) -> bool {
+    pub(super) fn excludes(&self, point: IVec2) -> bool {
         self.a.cmpgt(point).any() || self.b.cmplt(point).any()
     }
 
     /// Returns intersecting tile range. The result might be empty.
-    pub(crate) fn intersection(&self, other: &TileRange) -> TileRange {
+    pub(super) fn intersection(&self, other: &TileRange) -> TileRange {
         Self::new(self.a.max(other.a), self.b.min(other.b))
     }
 }

crates/index/src/segment.rs renamed to crates/index/src/precise/segment.rs

@@ -6,7 +6,8 @@ use de_types::projection::ToFlat;
 use glam::{IVec2, Vec2};
 use parry3d::shape::Segment;
 
-use super::{grid::TileGrid, TILE_SIZE};
+use super::grid::TileGrid;
+use crate::TILE_SIZE;
 
 /// An iterator over sets of entities from tiles intersecting a given line
 /// segment.
@@ -18,14 +19,14 @@ use super::{grid::TileGrid, TILE_SIZE};
 /// The tiles (and thus the yielded sets) are iterated by increasing distance
 /// between point `a` of the given line segment and the intersection of the
 /// tile with the line segment.
-pub(crate) struct SegmentCandidates<'a> {
+pub(super) struct SegmentCandidates<'a> {
     grid: &'a TileGrid,
     tiles: TileIterator,
     encountered: Option<&'a AHashSet<Entity>>,
 }
 
 impl<'a> SegmentCandidates<'a> {
-    pub(crate) fn new(grid: &'a TileGrid, segment: Segment) -> Self {
+    pub(super) fn new(grid: &'a TileGrid, segment: Segment) -> Self {
         Self {
             grid,
             tiles: TileIterator::new(segment),
@@ -172,7 +173,6 @@ mod tests {
     use parry3d::{bounding_volume::Aabb, math::Point, shape::Segment};
 
     use super::*;
-    use crate::grid::TileGrid;
 
     #[test]
     fn test_segment_candidates() {

crates/spawner/src/draft.rs

@@ -12,7 +12,7 @@ use de_core::{
     objects::{MovableSolid, ObjectTypeComponent, StaticSolid},
     state::AppState,
 };
-use de_index::{ColliderWithCache, IndexSet, QueryCollider, SpatialQuery};
+use de_index::{ColliderWithCache, PreciseIndexSet, QueryCollider, SpatialQuery};
 use de_map::size::MapBounds;
 use de_objects::{AssetCollection, SceneType, Scenes, SolidObjects, EXCLUSION_OFFSET};
 use de_types::{
@@ -42,7 +42,7 @@ impl Plugin for DraftPlugin {
                 PostUpdate,
                 (update_draft, check_draft_loaded, update_draft_colour)
                     .run_if(in_state(GameState::Playing))
-                    .after(IndexSet::Index),
+                    .after(PreciseIndexSet::Index),
             );
     }
 }