Support non-Vec data structures in relations

benches/benches/bevy_ecs/world/entity_hash.rs

@@ -1,4 +1,4 @@
-use bevy_ecs::entity::{Entity, EntityHashSet};
+use bevy_ecs::entity::{hash_set::EntityHashSet, Entity};
 use criterion::{BenchmarkId, Criterion, Throughput};
 use rand::{Rng, SeedableRng};
 use rand_chacha::ChaCha8Rng;

crates/bevy_core_pipeline/src/oit/resolve/mod.rs

@@ -6,7 +6,7 @@ use bevy_app::Plugin;
 use bevy_asset::{load_internal_asset, Handle};
 use bevy_derive::Deref;
 use bevy_ecs::{
-    entity::{EntityHashMap, EntityHashSet},
+    entity::{hash_map::EntityHashMap, hash_set::EntityHashSet},
     prelude::*,
 };
 use bevy_image::BevyDefault as _;

crates/bevy_ecs/Cargo.toml

@@ -121,7 +121,7 @@ derive_more = { version = "1", default-features = false, features = [
 ] }
 nonmax = { version = "0.5", default-features = false }
 arrayvec = { version = "0.7.4", default-features = false, optional = true }
-smallvec = { version = "1", features = ["union"] }
+smallvec = { version = "1", features = ["union", "const_generics"] }
 indexmap = { version = "2.5.0", default-features = false }
 variadics_please = { version = "1.1", default-features = false }
 critical-section = { version = "1.2.0", optional = true }

crates/bevy_ecs/src/entity/hash_map.rs

@@ -1,3 +1,7 @@
+//! Contains the [`EntityHashMap`] type, a [`HashMap`] pre-configured to use [`EntityHash`] hashing.
+//!
+//! This module is a lightweight wrapper around [`hashbrown`](bevy_utils::hashbrown)'s [`HashMap`] that is more performant for [`Entity`] keys.
+
 use core::{
     fmt::{self, Debug, Formatter},
     iter::FusedIterator,

crates/bevy_ecs/src/entity/hash_set.rs

@@ -1,3 +1,7 @@
+//! Contains the [`EntityHashSet`] type, a [`HashSet`] pre-configured to use [`EntityHash`] hashing.
+//!
+//! This module is a lightweight wrapper around [`hashbrown`](bevy_utils::hashbrown)'s [`HashSet`] that is more performant for [`Entity`] keys.
+
 use core::{
     fmt::{self, Debug, Formatter},
     iter::FusedIterator,
@@ -38,6 +42,16 @@ impl EntityHashSet {
         Self(HashSet::with_capacity_and_hasher(n, EntityHash))
     }
 
+    /// Returns the number of elements in the set.
+    pub fn len(&self) -> usize {
+        self.0.len()
+    }
+
+    /// Returns `true` if the set contains no elements.
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+
     /// Returns the inner [`HashSet`].
     pub fn into_inner(self) -> HashSet<Entity, EntityHash> {
         self.0
@@ -54,8 +68,8 @@ impl EntityHashSet {
     /// The iterator element type is `&'a Entity`.
     ///
     /// Equivalent to [`HashSet::iter`].
-    pub fn iter(&self) -> Iter<'_> {
-        Iter(self.0.iter(), PhantomData)
+    pub fn iter(&self) -> EntityHashSetIter<'_> {
+        EntityHashSetIter(self.0.iter(), PhantomData)
     }
 
     /// Drains elements which are true under the given predicate,
@@ -84,10 +98,10 @@ impl DerefMut for EntityHashSet {
 impl<'a> IntoIterator for &'a EntityHashSet {
     type Item = &'a Entity;
 
-    type IntoIter = Iter<'a>;
+    type IntoIter = EntityHashSetIter<'a>;
 
     fn into_iter(self) -> Self::IntoIter {
-        Iter((&self.0).into_iter(), PhantomData)
+        EntityHashSetIter((&self.0).into_iter(), PhantomData)
     }
 }
 
@@ -186,61 +200,61 @@ impl FromIterator<Entity> for EntityHashSet {
 /// This struct is created by the [`iter`] method on [`EntityHashSet`]. See its documentation for more.
 ///
 /// [`iter`]: EntityHashSet::iter
-pub struct Iter<'a, S = EntityHash>(hash_set::Iter<'a, Entity>, PhantomData<S>);
+pub struct EntityHashSetIter<'a, S = EntityHash>(hash_set::Iter<'a, Entity>, PhantomData<S>);
 
-impl<'a> Iter<'a> {
+impl<'a> EntityHashSetIter<'a> {
     /// Returns the inner [`Iter`](hash_set::Iter).
     pub fn into_inner(self) -> hash_set::Iter<'a, Entity> {
         self.0
     }
 }
 
-impl<'a> Deref for Iter<'a> {
+impl<'a> Deref for EntityHashSetIter<'a> {
     type Target = hash_set::Iter<'a, Entity>;
 
     fn deref(&self) -> &Self::Target {
         &self.0
     }
 }
 
-impl DerefMut for Iter<'_> {
+impl DerefMut for EntityHashSetIter<'_> {
     fn deref_mut(&mut self) -> &mut Self::Target {
         &mut self.0
     }
 }
 
-impl<'a> Iterator for Iter<'a> {
+impl<'a> Iterator for EntityHashSetIter<'a> {
     type Item = &'a Entity;
 
     fn next(&mut self) -> Option<Self::Item> {
         self.0.next()
     }
 }
 
-impl ExactSizeIterator for Iter<'_> {}
+impl ExactSizeIterator for EntityHashSetIter<'_> {}
 
-impl FusedIterator for Iter<'_> {}
+impl FusedIterator for EntityHashSetIter<'_> {}
 
-impl Clone for Iter<'_> {
+impl Clone for EntityHashSetIter<'_> {
     fn clone(&self) -> Self {
         Self(self.0.clone(), PhantomData)
     }
 }
 
-impl Debug for Iter<'_> {
+impl Debug for EntityHashSetIter<'_> {
     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         f.debug_tuple("Iter").field(&self.0).field(&self.1).finish()
     }
 }
 
-impl Default for Iter<'_> {
+impl Default for EntityHashSetIter<'_> {
     fn default() -> Self {
         Self(Default::default(), PhantomData)
     }
 }
 
 // SAFETY: Iter stems from a correctly behaving `HashSet<Entity, EntityHash>`.
-unsafe impl EntitySetIterator for Iter<'_> {}
+unsafe impl EntitySetIterator for EntityHashSetIter<'_> {}
 
 /// Owning iterator over the items of an [`EntityHashSet`].
 ///

crates/bevy_ecs/src/entity/map_entities.rs

@@ -4,7 +4,7 @@ use crate::{
     world::World,
 };
 
-use super::{EntityHashMap, VisitEntitiesMut};
+use super::{hash_map::EntityHashMap, VisitEntitiesMut};
 
 /// Operation to map all contained [`Entity`] fields in a type to new values.
 ///
@@ -71,7 +71,7 @@ impl<T: VisitEntitiesMut> MapEntities for T {
 ///
 /// ```
 /// # use bevy_ecs::entity::{Entity, EntityMapper};
-/// # use bevy_ecs::entity::EntityHashMap;
+/// # use bevy_ecs::entity::hash_map::EntityHashMap;
 /// #
 /// pub struct SimpleEntityMapper {
 ///   map: EntityHashMap<Entity>,
@@ -194,7 +194,7 @@ impl<'m> SceneEntityMapper<'m> {
 #[cfg(test)]
 mod tests {
     use crate::{
-        entity::{Entity, EntityHashMap, EntityMapper, SceneEntityMapper},
+        entity::{hash_map::EntityHashMap, Entity, EntityMapper, SceneEntityMapper},
         world::World,
     };
 

crates/bevy_ecs/src/entity/mod.rs

@@ -53,11 +53,8 @@ pub use visit_entities::*;
 mod hash;
 pub use hash::*;
 
-mod hash_map;
-mod hash_set;
-
-pub use hash_map::EntityHashMap;
-pub use hash_set::EntityHashSet;
+pub mod hash_map;
+pub mod hash_set;
 
 use crate::{
     archetype::{ArchetypeId, ArchetypeRow},

crates/bevy_ecs/src/entity/visit_entities.rs

@@ -58,7 +58,7 @@ impl VisitEntitiesMut for Entity {
 mod tests {
     use crate::{
         self as bevy_ecs,
-        entity::{EntityHashMap, MapEntities, SceneEntityMapper},
+        entity::{hash_map::EntityHashMap, MapEntities, SceneEntityMapper},
         world::World,
     };
     use alloc::{string::String, vec, vec::Vec};

crates/bevy_ecs/src/observer/mod.rs

@@ -9,7 +9,7 @@ pub use runner::*;
 use crate::{
     archetype::ArchetypeFlags,
     component::ComponentId,
-    entity::EntityHashMap,
+    entity::hash_map::EntityHashMap,
     prelude::*,
     system::IntoObserverSystem,
     world::{DeferredWorld, *},

crates/bevy_ecs/src/relationship/mod.rs

@@ -130,12 +130,22 @@ pub trait Relationship: Component + Sized {
     }
 }
 
+/// The iterator type for the source entities in a [`RelationshipTarget`] collection,
+/// as defined in the [`RelationshipSourceCollection`] trait.
+pub type SourceIter<'w, R> =
+    <<R as RelationshipTarget>::Collection as RelationshipSourceCollection>::SourceIter<'w>;
+
 /// A [`Component`] containing the collection of entities that relate to this [`Entity`] via the associated `Relationship` type.
 /// See the [`Relationship`] documentation for more information.
 pub trait RelationshipTarget: Component<Mutability = Mutable> + Sized {
     /// The [`Relationship`] that populates this [`RelationshipTarget`] collection.
     type Relationship: Relationship<RelationshipTarget = Self>;
     /// The collection type that stores the "source" entities for this [`RelationshipTarget`] component.
+    ///
+    /// Check the list of types which implement [`RelationshipSourceCollection`] for the data structures that can be used inside of your component.
+    /// If you need a new collection type, you can implement the [`RelationshipSourceCollection`] trait
+    /// for a type you own which wraps the collection you want to use (to avoid the orphan rule),
+    /// or open an issue on the Bevy repository to request first-party support for your collection type.
     type Collection: RelationshipSourceCollection;
 
     /// Returns a reference to the stored [`RelationshipTarget::Collection`].
@@ -210,7 +220,7 @@ pub trait RelationshipTarget: Component<Mutability = Mutable> + Sized {
 
     /// Iterates the entities stored in this collection.
     #[inline]
-    fn iter(&self) -> impl DoubleEndedIterator<Item = Entity> {
+    fn iter(&self) -> SourceIter<'_, Self> {
         self.collection().iter()
     }
 

crates/bevy_ecs/src/relationship/relationship_query.rs

@@ -7,6 +7,8 @@ use crate::{
 use alloc::collections::VecDeque;
 use smallvec::SmallVec;
 
+use super::SourceIter;
+
 impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> {
     /// If the given `entity` contains the `R` [`Relationship`] component, returns the
     /// target entity of that relationship.
@@ -59,6 +61,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> {
     ) -> impl Iterator<Item = Entity> + 'w
     where
         <D as QueryData>::ReadOnly: WorldQuery<Item<'w> = &'w S>,
+        SourceIter<'w, S>: DoubleEndedIterator,
     {
         self.iter_descendants_depth_first(entity).filter(|entity| {
             self.get(*entity)
@@ -114,6 +117,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> {
     ) -> DescendantDepthFirstIter<'w, 's, D, F, S>
     where
         D::ReadOnly: WorldQuery<Item<'w> = &'w S>,
+        SourceIter<'w, S>: DoubleEndedIterator,
     {
         DescendantDepthFirstIter::new(self, entity)
     }
@@ -195,6 +199,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter, S: RelationshipTarget>
     DescendantDepthFirstIter<'w, 's, D, F, S>
 where
     D::ReadOnly: WorldQuery<Item<'w> = &'w S>,
+    SourceIter<'w, S>: DoubleEndedIterator,
 {
     /// Returns a new [`DescendantDepthFirstIter`].
     pub fn new(children_query: &'w Query<'w, 's, D, F>, entity: Entity) -> Self {
@@ -211,6 +216,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter, S: RelationshipTarget> Iterator
     for DescendantDepthFirstIter<'w, 's, D, F, S>
 where
     D::ReadOnly: WorldQuery<Item<'w> = &'w S>,
+    SourceIter<'w, S>: DoubleEndedIterator,
 {
     type Item = Entity;