Move EntityHash related types into bevy_ecs

CHANGELOG.md

@@ -574,7 +574,7 @@ current changes on git with [previous release tags][git_tag_comparison].
 - [Automatic batching/instancing of draw commands][9685]
 - [Directly copy data into uniform buffers][9865]
 - [Allow other plugins to create renderer resources][9925]
-- [Use EntityHashMap<Entity, T> for render world entity storage for better performance][9903]
+- [Use EntityHashMap<T> for render world entity storage for better performance][9903]
 - [Parallelize extract_meshes][9966]
 - [Fix comment grammar][9990]
 - [Allow overriding global wireframe setting.][7328]

crates/bevy_ecs/Cargo.toml

@@ -31,6 +31,7 @@ thiserror = "1.0"
 
 [dev-dependencies]
 rand = "0.8"
+static_assertions = "1.1.0"
 
 [[example]]
 name = "events"

crates/bevy_ecs/src/entity/hash.rs

@@ -0,0 +1,95 @@
+use std::hash::{BuildHasher, Hasher};
+
+use bevy_reflect::Reflect;
+use bevy_utils::hashbrown;
+
+use super::Entity;
+
+/// A [`BuildHasher`] that results in a [`EntityHasher`].
+#[derive(Default, Clone, Reflect)]
+pub struct EntityHash;
+
+impl BuildHasher for EntityHash {
+    type Hasher = EntityHasher;
+
+    fn build_hasher(&self) -> Self::Hasher {
+        EntityHasher::default()
+    }
+}
+
+/// A very fast hash that is only designed to work on generational indices
+/// like [`Entity`](super::Entity). It will panic if attempting to hash a type containing
+/// non-u64 fields.
+///
+/// This is heavily optimized for typical cases, where you have mostly live
+/// entities, and works particularly well for contiguous indices.
+///
+/// If you have an unusual case -- say all your indices are multiples of 256
+/// or most of the entities are dead generations -- then you might want also to
+/// try [`AHasher`](bevy_utils::AHasher) for a slower hash computation but fewer lookup conflicts.
+#[derive(Debug, Default)]
+pub struct EntityHasher {
+    hash: u64,
+}
+
+impl Hasher for EntityHasher {
+    #[inline]
+    fn finish(&self) -> u64 {
+        self.hash
+    }
+
+    fn write(&mut self, _bytes: &[u8]) {
+        panic!("can only hash u64 using EntityHasher");
+    }
+
+    #[inline]
+    fn write_u64(&mut self, bits: u64) {
+        // SwissTable (and thus `hashbrown`) cares about two things from the hash:
+        // - H1: low bits (masked by `2ⁿ-1`) to pick the slot in which to store the item
+        // - H2: high 7 bits are used to SIMD optimize hash collision probing
+        // For more see <https://abseil.io/about/design/swisstables#metadata-layout>
+
+        // This hash function assumes that the entity ids are still well-distributed,
+        // so for H1 leaves the entity id alone in the low bits so that id locality
+        // will also give memory locality for things spawned together.
+        // For H2, take advantage of the fact that while multiplication doesn't
+        // spread entropy to the low bits, it's incredibly good at spreading it
+        // upward, which is exactly where we need it the most.
+
+        // While this does include the generation in the output, it doesn't do so
+        // *usefully*.  H1 won't care until you have over 3 billion entities in
+        // the table, and H2 won't care until something hits generation 33 million.
+        // Thus the comment suggesting that this is best for live entities,
+        // where there won't be generation conflicts where it would matter.
+
+        // The high 32 bits of this are ⅟φ for Fibonacci hashing.  That works
+        // particularly well for hashing for the same reason as described in
+        // <https://extremelearning.com.au/unreasonable-effectiveness-of-quasirandom-sequences/>
+        // It loses no information because it has a modular inverse.
+        // (Specifically, `0x144c_bc89_u32 * 0x9e37_79b9_u32 == 1`.)
+        //
+        // The low 32 bits make that part of the just product a pass-through.
+        const UPPER_PHI: u64 = 0x9e37_79b9_0000_0001;
+
+        // This is `(MAGIC * index + generation) << 32 + index`, in a single instruction.
+        self.hash = bits.wrapping_mul(UPPER_PHI);
+    }
+}
+
+/// A [`HashMap`](hashbrown::HashMap) pre-configured to use [`EntityHash`] hashing.
+pub type EntityHashMap<V> = hashbrown::HashMap<Entity, V, EntityHash>;
+
+/// A [`HashSet`](hashbrown::HashSet) pre-configured to use [`EntityHash`] hashing.
+pub type EntityHashSet = hashbrown::HashSet<Entity, EntityHash>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use bevy_reflect::Reflect;
+    use static_assertions::assert_impl_all;
+
+    // Check that the HashMaps are Clone if the key/values are Clone
+    assert_impl_all!(EntityHashMap::<usize>: Clone);
+    // EntityHashMap should implement Reflect
+    assert_impl_all!(EntityHashMap::<i32>: Reflect);
+}

crates/bevy_ecs/src/entity/map_entities.rs

@@ -3,13 +3,14 @@ use crate::{
     identifier::masks::{IdentifierMask, HIGH_MASK},
     world::World,
 };
-use bevy_utils::EntityHashMap;
+
+use super::EntityHashMap;
 
 /// Operation to map all contained [`Entity`] fields in a type to new values.
 ///
 /// As entity IDs are valid only for the [`World`] they're sourced from, using [`Entity`]
 /// as references in components copied from another world will be invalid. This trait
-/// allows defining custom mappings for these references via [`EntityHashMap<Entity, Entity>`]
+/// allows defining custom mappings for these references via [`EntityHashMap<Entity>`]
 ///
 /// Implementing this trait correctly is required for properly loading components
 /// with entity references from scenes.
@@ -42,7 +43,7 @@ pub trait MapEntities {
     fn map_entities(&mut self, entity_mapper: &mut EntityMapper);
 }
 
-/// A wrapper for [`EntityHashMap<Entity, Entity>`], augmenting it with the ability to allocate new [`Entity`] references in a destination
+/// A wrapper for [`EntityHashMap<Entity>`], augmenting it with the ability to allocate new [`Entity`] references in a destination
 /// world. These newly allocated references are guaranteed to never point to any living entity in that world.
 ///
 /// References are allocated by returning increasing generations starting from an internally initialized base
@@ -55,9 +56,9 @@ pub struct EntityMapper<'m> {
     /// or over the network. This is required as [`Entity`] identifiers are opaque; you cannot and do not want to reuse
     /// identifiers directly.
     ///
-    /// On its own, a [`EntityHashMap<Entity, Entity>`] is not capable of allocating new entity identifiers, which is needed to map references
+    /// On its own, a [`EntityHashMap<Entity>`] is not capable of allocating new entity identifiers, which is needed to map references
     /// to entities that lie outside the source entity set. This functionality can be accessed through [`EntityMapper::world_scope()`].
-    map: &'m mut EntityHashMap<Entity, Entity>,
+    map: &'m mut EntityHashMap<Entity>,
     /// A base [`Entity`] used to allocate new references.
     dead_start: Entity,
     /// The number of generations this mapper has allocated thus far.
@@ -85,18 +86,18 @@ impl<'m> EntityMapper<'m> {
         new
     }
 
-    /// Gets a reference to the underlying [`EntityHashMap<Entity, Entity>`].
-    pub fn get_map(&'m self) -> &'m EntityHashMap<Entity, Entity> {
+    /// Gets a reference to the underlying [`EntityHashMap<Entity>`].
+    pub fn get_map(&'m self) -> &'m EntityHashMap<Entity> {
         self.map
     }
 
-    /// Gets a mutable reference to the underlying [`EntityHashMap<Entity, Entity>`].
-    pub fn get_map_mut(&'m mut self) -> &'m mut EntityHashMap<Entity, Entity> {
+    /// Gets a mutable reference to the underlying [`EntityHashMap<Entity>`].
+    pub fn get_map_mut(&'m mut self) -> &'m mut EntityHashMap<Entity> {
         self.map
     }
 
     /// Creates a new [`EntityMapper`], spawning a temporary base [`Entity`] in the provided [`World`]
-    fn new(map: &'m mut EntityHashMap<Entity, Entity>, world: &mut World) -> Self {
+    fn new(map: &'m mut EntityHashMap<Entity>, world: &mut World) -> Self {
         Self {
             map,
             // SAFETY: Entities data is kept in a valid state via `EntityMapper::world_scope`
@@ -116,14 +117,14 @@ impl<'m> EntityMapper<'m> {
         assert!(entities.reserve_generations(self.dead_start.index(), self.generations));
     }
 
-    /// Creates an [`EntityMapper`] from a provided [`World`] and [`EntityHashMap<Entity, Entity>`], then calls the
+    /// Creates an [`EntityMapper`] from a provided [`World`] and [`EntityHashMap<Entity>`], then calls the
     /// provided function with it. This allows one to allocate new entity references in this [`World`] that are
     /// guaranteed to never point at a living entity now or in the future. This functionality is useful for safely
     /// mapping entity identifiers that point at entities outside the source world. The passed function, `f`, is called
     /// within the scope of this world. Its return value is then returned from `world_scope` as the generic type
     /// parameter `R`.
     pub fn world_scope<R>(
-        entity_map: &'m mut EntityHashMap<Entity, Entity>,
+        entity_map: &'m mut EntityHashMap<Entity>,
         world: &mut World,
         f: impl FnOnce(&mut World, &mut Self) -> R,
     ) -> R {
@@ -136,12 +137,9 @@ impl<'m> EntityMapper<'m> {
 
 #[cfg(test)]
 mod tests {
-    use bevy_utils::EntityHashMap;
+    use super::{Entity, EntityHashMap, EntityMapper};
 
-    use crate::{
-        entity::{Entity, EntityMapper},
-        world::World,
-    };
+    use crate::world::World;
 
     #[test]
     fn entity_mapper() {

crates/bevy_ecs/src/entity/mod.rs

@@ -36,9 +36,13 @@
 //! [`EntityWorldMut::insert`]: crate::world::EntityWorldMut::insert
 //! [`EntityWorldMut::remove`]: crate::world::EntityWorldMut::remove
 mod map_entities;
+use bevy_reflect::{Reflect, ReflectDeserialize, ReflectSerialize};
+pub use map_entities::*;
+
+mod hash;
+pub use hash::*;
 
 use bevy_utils::tracing::warn;
-pub use map_entities::*;
 
 use crate::{
     archetype::{ArchetypeId, ArchetypeRow},
@@ -122,7 +126,8 @@ type IdCursor = isize;
 /// [`EntityCommands`]: crate::system::EntityCommands
 /// [`Query::get`]: crate::system::Query::get
 /// [`World`]: crate::world::World
-#[derive(Clone, Copy)]
+#[derive(Clone, Copy, Reflect)]
+#[reflect_value(Hash, PartialEq, Serialize, Deserialize)]
 // Alignment repr necessary to allow LLVM to better output
 // optimised codegen for `to_bits`, `PartialEq` and `Ord`.
 #[repr(C, align(8))]
@@ -1092,7 +1097,7 @@ mod tests {
     #[test]
     fn entity_hash_keeps_similar_ids_together() {
         use std::hash::BuildHasher;
-        let hash = bevy_utils::EntityHash;
+        let hash = EntityHash;
 
         let first_id = 0xC0FFEE << 8;
         let first_hash = hash.hash_one(Entity::from_raw(first_id));
@@ -1107,7 +1112,8 @@ mod tests {
     #[test]
     fn entity_hash_id_bitflip_affects_high_7_bits() {
         use std::hash::BuildHasher;
-        let hash = bevy_utils::EntityHash;
+
+        let hash = EntityHash;
 
         let first_id = 0xC0FFEE;
         let first_hash = hash.hash_one(Entity::from_raw(first_id)) >> 57;

crates/bevy_ecs/src/reflect/map_entities.rs

@@ -1,10 +1,9 @@
 use crate::{
     component::Component,
-    entity::{Entity, EntityMapper, MapEntities},
+    entity::{Entity, EntityHashMap, EntityMapper, MapEntities},
     world::World,
 };
 use bevy_reflect::FromType;
-use bevy_utils::EntityHashMap;
 
 /// For a specific type of component, this maps any fields with values of type [`Entity`] to a new world.
 /// Since a given `Entity` ID is only valid for the world it came from, when performing deserialization
@@ -18,33 +17,29 @@ pub struct ReflectMapEntities {
 }
 
 impl ReflectMapEntities {
-    /// A general method for applying [`MapEntities`] behavior to all elements in an [`EntityHashMap<Entity, Entity>`].
+    /// A general method for applying [`MapEntities`] behavior to all elements in an [`EntityHashMap<Entity>`].
     ///
-    /// Be mindful in its usage: Works best in situations where the entities in the [`EntityHashMap<Entity, Entity>`] are newly
+    /// Be mindful in its usage: Works best in situations where the entities in the [`EntityHashMap<Entity>`] are newly
     /// created, before systems have a chance to add new components. If some of the entities referred to
-    /// by the [`EntityHashMap<Entity, Entity>`] might already contain valid entity references, you should use [`map_entities`](Self::map_entities).
+    /// by the [`EntityHashMap<Entity>`] might already contain valid entity references, you should use [`map_entities`](Self::map_entities).
     ///
     /// An example of this: A scene can be loaded with `Parent` components, but then a `Parent` component can be added
     /// to these entities after they have been loaded. If you reload the scene using [`map_all_entities`](Self::map_all_entities), those `Parent`
     /// components with already valid entity references could be updated to point at something else entirely.
-    pub fn map_all_entities(
-        &self,
-        world: &mut World,
-        entity_map: &mut EntityHashMap<Entity, Entity>,
-    ) {
+    pub fn map_all_entities(&self, world: &mut World, entity_map: &mut EntityHashMap<Entity>) {
         EntityMapper::world_scope(entity_map, world, self.map_all_entities);
     }
 
-    /// A general method for applying [`MapEntities`] behavior to elements in an [`EntityHashMap<Entity, Entity>`]. Unlike
+    /// A general method for applying [`MapEntities`] behavior to elements in an [`EntityHashMap<Entity>`]. Unlike
     /// [`map_all_entities`](Self::map_all_entities), this is applied to specific entities, not all values
-    /// in the [`EntityHashMap<Entity, Entity>`].
+    /// in the [`EntityHashMap<Entity>`].
     ///
     /// This is useful mostly for when you need to be careful not to update components that already contain valid entity
     /// values. See [`map_all_entities`](Self::map_all_entities) for more details.
     pub fn map_entities(
         &self,
         world: &mut World,
-        entity_map: &mut EntityHashMap<Entity, Entity>,
+        entity_map: &mut EntityHashMap<Entity>,
         entities: &[Entity],
     ) {
         EntityMapper::world_scope(entity_map, world, |world, mapper| {

crates/bevy_ecs/src/reflect/mod.rs

@@ -3,8 +3,8 @@
 use std::ops::{Deref, DerefMut};
 
 use crate as bevy_ecs;
-use crate::{entity::Entity, system::Resource};
-use bevy_reflect::{impl_reflect_value, ReflectDeserialize, ReflectSerialize, TypeRegistryArc};
+use crate::system::Resource;
+use bevy_reflect::TypeRegistryArc;
 
 mod bundle;
 mod component;
@@ -40,5 +40,3 @@ impl DerefMut for AppTypeRegistry {
         &mut self.0
     }
 }
-
-impl_reflect_value!((in bevy_ecs) Entity(Hash, PartialEq, Serialize, Deserialize));

crates/bevy_gltf/src/loader.rs

@@ -4,6 +4,7 @@ use bevy_asset::{
 };
 use bevy_core::Name;
 use bevy_core_pipeline::prelude::Camera3dBundle;
+use bevy_ecs::entity::EntityHashMap;
 use bevy_ecs::{entity::Entity, world::World};
 use bevy_hierarchy::{BuildWorldChildren, WorldChildBuilder};
 use bevy_log::{error, warn};
@@ -33,7 +34,7 @@ use bevy_scene::Scene;
 #[cfg(not(target_arch = "wasm32"))]
 use bevy_tasks::IoTaskPool;
 use bevy_transform::components::Transform;
-use bevy_utils::{EntityHashMap, HashMap, HashSet};
+use bevy_utils::{HashMap, HashSet};
 use gltf::{
     accessor::Iter,
     mesh::{util::ReadIndices, Mode},
@@ -922,7 +923,7 @@ fn load_node(
     load_context: &mut LoadContext,
     settings: &GltfLoaderSettings,
     node_index_to_entity_map: &mut HashMap<usize, Entity>,
-    entity_to_skin_index_map: &mut EntityHashMap<Entity, usize>,
+    entity_to_skin_index_map: &mut EntityHashMap<usize>,
     active_camera_found: &mut bool,
     parent_transform: &Transform,
 ) -> Result<(), GltfError> {

crates/bevy_pbr/src/bundle.rs

@@ -3,15 +3,15 @@ use crate::{
     StandardMaterial,
 };
 use bevy_asset::Handle;
-use bevy_ecs::{bundle::Bundle, component::Component, prelude::Entity, reflect::ReflectComponent};
+use bevy_ecs::entity::EntityHashMap;
+use bevy_ecs::{bundle::Bundle, component::Component, reflect::ReflectComponent};
 use bevy_reflect::Reflect;
 use bevy_render::{
     mesh::Mesh,
     primitives::{CascadesFrusta, CubemapFrusta, Frustum},
     view::{InheritedVisibility, ViewVisibility, Visibility, VisibleEntities},
 };
 use bevy_transform::components::{GlobalTransform, Transform};
-use bevy_utils::EntityHashMap;
 
 /// A component bundle for PBR entities with a [`Mesh`] and a [`StandardMaterial`].
 pub type PbrBundle = MaterialMeshBundle<StandardMaterial>;
@@ -75,7 +75,7 @@ impl CubemapVisibleEntities {
 pub struct CascadesVisibleEntities {
     /// Map of view entity to the visible entities for each cascade frustum.
     #[reflect(ignore)]
-    pub entities: EntityHashMap<Entity, Vec<VisibleEntities>>,
+    pub entities: EntityHashMap<Vec<VisibleEntities>>,
 }
 
 /// A component bundle for [`PointLight`] entities.

crates/bevy_pbr/src/light.rs

@@ -1,5 +1,6 @@
 use std::collections::HashSet;
 
+use bevy_ecs::entity::EntityHashMap;
 use bevy_ecs::prelude::*;
 use bevy_math::{
     AspectRatio, Mat4, UVec2, UVec3, Vec2, Vec3, Vec3A, Vec3Swizzles, Vec4, Vec4Swizzles,
@@ -16,7 +17,7 @@ use bevy_render::{
     view::{InheritedVisibility, RenderLayers, ViewVisibility, VisibleEntities},
 };
 use bevy_transform::components::{GlobalTransform, Transform};
-use bevy_utils::{tracing::warn, EntityHashMap};
+use bevy_utils::tracing::warn;
 
 use crate::*;
 
@@ -381,7 +382,7 @@ impl From<CascadeShadowConfigBuilder> for CascadeShadowConfig {
 #[reflect(Component)]
 pub struct Cascades {
     /// Map from a view to the configuration of each of its [`Cascade`]s.
-    pub(crate) cascades: EntityHashMap<Entity, Vec<Cascade>>,
+    pub(crate) cascades: EntityHashMap<Vec<Cascade>>,
 }
 
 #[derive(Clone, Debug, Default, Reflect)]