Implement WorldQuery for EntityRef

crates/bevy_ecs/src/lib.rs

@@ -43,7 +43,7 @@ pub mod prelude {
             Commands, In, IntoPipeSystem, IntoSystem, Local, NonSend, NonSendMut, ParallelCommands,
             ParamSet, Query, RemovedComponents, Res, ResMut, Resource, System, SystemParamFunction,
         },
-        world::{FromWorld, Mut, World},
+        world::{EntityRef, FromWorld, Mut, World},
     };
 }
 
@@ -61,7 +61,7 @@ mod tests {
             Added, ChangeTrackers, Changed, FilteredAccess, ReadOnlyWorldQuery, With, Without,
         },
         system::Resource,
-        world::{Mut, World},
+        world::{EntityRef, Mut, World},
     };
     use bevy_tasks::{ComputeTaskPool, TaskPool};
     use std::{
@@ -1329,13 +1329,27 @@ mod tests {
         world.query::<(&A, &mut A)>();
     }
 
+    #[test]
+    #[should_panic]
+    fn entity_ref_and_mut_query_panic() {
+        let mut world = World::new();
+        world.query::<(EntityRef, &mut A)>();
+    }
+
     #[test]
     #[should_panic]
     fn mut_and_ref_query_panic() {
         let mut world = World::new();
         world.query::<(&mut A, &A)>();
     }
 
+    #[test]
+    #[should_panic]
+    fn mut_and_entity_ref_query_panic() {
+        let mut world = World::new();
+        world.query::<(&mut A, EntityRef)>();
+    }
+
     #[test]
     #[should_panic]
     fn mut_and_mut_query_panic() {

crates/bevy_ecs/src/query/access.rs

@@ -113,6 +113,11 @@ impl<T: SparseSetIndex> Access<T> {
         self.writes.contains(index.sparse_set_index())
     }
 
+    /// Returns `true` if this accesses anything mutably.
+    pub fn has_any_write(&self) -> bool {
+        !self.writes.is_clear()
+    }
+
     /// Sets this as having access to all indexed elements (i.e. `&World`).
     pub fn read_all(&mut self) {
         self.reads_all = true;

crates/bevy_ecs/src/query/fetch.rs

@@ -5,7 +5,7 @@ use crate::{
     entity::Entity,
     query::{Access, DebugCheckedUnwrap, FilteredAccess},
     storage::{ComponentSparseSet, Table, TableRow},
-    world::{Mut, World},
+    world::{EntityRef, Mut, World},
 };
 use bevy_ecs_macros::all_tuples;
 pub use bevy_ecs_macros::WorldQuery;
@@ -515,6 +515,87 @@ unsafe impl WorldQuery for Entity {
 /// SAFETY: access is read only
 unsafe impl ReadOnlyWorldQuery for Entity {}
 
+/// SAFETY: `Self` is the same as `Self::ReadOnly`
+unsafe impl<'a> WorldQuery for EntityRef<'a> {
+    type Fetch<'w> = &'w World;
+    type Item<'w> = EntityRef<'w>;
+    type ReadOnly = Self;
+    type State = ();
+
+    fn shrink<'wlong: 'wshort, 'wshort>(item: Self::Item<'wlong>) -> Self::Item<'wshort> {
+        item
+    }
+
+    const IS_DENSE: bool = true;
+
+    const IS_ARCHETYPAL: bool = true;
+
+    unsafe fn init_fetch<'w>(
+        world: &'w World,
+        _state: &Self::State,
+        _last_change_tick: u32,
+        _change_tick: u32,
+    ) -> Self::Fetch<'w> {
+        world
+    }
+
+    unsafe fn clone_fetch<'w>(world: &Self::Fetch<'w>) -> Self::Fetch<'w> {
+        world
+    }
+
+    #[inline]
+    unsafe fn set_archetype<'w>(
+        _fetch: &mut Self::Fetch<'w>,
+        _state: &Self::State,
+        _archetype: &'w Archetype,
+        _table: &Table,
+    ) {
+    }
+
+    #[inline]
+    unsafe fn set_table<'w>(_fetch: &mut Self::Fetch<'w>, _state: &Self::State, _table: &'w Table) {
+    }
+
+    #[inline(always)]
+    unsafe fn fetch<'w>(
+        world: &mut Self::Fetch<'w>,
+        entity: Entity,
+        _table_row: TableRow,
+    ) -> Self::Item<'w> {
+        world.get_entity(entity).debug_checked_unwrap()
+    }
+
+    fn update_component_access(_state: &Self::State, access: &mut FilteredAccess<ComponentId>) {
+        assert!(
+            !access.access().has_any_write(),
+            "EntityRef conflicts with a previous access in this query. Shared access cannot coincide with exclusive access.",
+        );
+        access.read_all();
+    }
+
+    fn update_archetype_component_access(
+        _state: &Self::State,
+        archetype: &Archetype,
+        access: &mut Access<ArchetypeComponentId>,
+    ) {
+        for component_id in archetype.components() {
+            access.add_read(archetype.get_archetype_component_id(component_id).unwrap());
+        }
+    }
+
+    fn init_state(_world: &mut World) {}
+
+    fn matches_component_set(
+        _state: &Self::State,
+        _set_contains_id: &impl Fn(ComponentId) -> bool,
+    ) -> bool {
+        true
+    }
+}
+
+/// SAFETY: access is read only
+unsafe impl<'a> ReadOnlyWorldQuery for EntityRef<'a> {}
+
 #[doc(hidden)]
 pub struct ReadFetch<'w, T> {
     // T::Storage = TableStorage

crates/bevy_ecs/src/system/query.rs

@@ -181,6 +181,39 @@ use std::{any::TypeId, borrow::Borrow, fmt::Debug};
 ///
 /// An alternative to this idiom is to wrap the conflicting queries into a [`ParamSet`](super::ParamSet).
 ///
+/// ## Whole Entity Access
+///
+/// [`EntityRef`]s can be fetched from a query. This will give read-only access to any component on the entity,
+/// and can be use to dynamically fetch any component without baking it into the query type. Due to this global
+/// access to the entity, this will block any other system from parallelizing with it. As such these queries
+/// should be sparingly used.
+///
+/// ```
+/// # use bevy_ecs::prelude::*;
+/// # #[derive(Component)]
+/// # struct ComponentA;
+/// # fn system(
+/// query: Query<(EntityRef, &ComponentA)>
+/// # ) {}
+/// # bevy_ecs::system::assert_is_system(system);
+/// ```
+///
+/// As `EntityRef` can read any component on an entity, a query using it will conflict with *any* mutable
+/// access. It is strongly advised to couple `EntityRef` queries with the use of either `With`/`Without`
+/// filters or `ParamSets`. This also limits the scope of the query, which will improve iteration performance
+/// and also allows it to parallelize with other non-conflicting systems.
+///
+/// ```
+/// # use bevy_ecs::prelude::*;
+/// # #[derive(Component)]
+/// # struct ComponentA;
+/// # fn system(
+/// // This will panic!
+/// query: Query<(EntityRef, &mut ComponentA)>
+/// # ) {}
+/// # bevy_ecs::system::assert_is_system(system);
+/// ```
+///
 /// # Accessing query items
 ///
 /// The following table summarizes the behavior of the safe methods that can be used to get query items.
@@ -246,6 +279,7 @@ use std::{any::TypeId, borrow::Borrow, fmt::Debug};
 /// [`Changed`]: crate::query::Changed
 /// [components]: crate::component::Component
 /// [entity identifiers]: crate::entity::Entity
+/// [`EntityRef`]: crate::world::EntityRef
 /// [`for_each`]: Self::for_each
 /// [`for_each_mut`]: Self::for_each_mut
 /// [`get`]: Self::get

crates/bevy_ecs/src/world/entity_ref.rs

@@ -48,11 +48,6 @@ impl<'w> EntityRef<'w> {
         &self.world.archetypes[self.location.archetype_id]
     }
 
-    #[inline]
-    pub fn world(&self) -> &'w World {
-        self.world
-    }
-
     #[inline]
     pub fn contains<T: Component>(&self) -> bool {
         self.contains_type_id(TypeId::of::<T>())