Track spawn Tick of entities, offer methods, query data SpawnDetails and query filter Spawned

crates/bevy_ecs/src/bundle.rs

@@ -1736,7 +1736,7 @@ impl<'w> BundleSpawner<'w> {
                 InsertMode::Replace,
                 caller,
             );
-            entities.set(entity.index(), location);
+            entities.set_spawn_despawn(entity.index(), location, caller, self.change_tick);
             (location, after_effect)
         };
 

crates/bevy_ecs/src/entity/mod.rs

@@ -76,11 +76,18 @@ pub use unique_vec::{UniqueEntityEquivalentVec, UniqueEntityVec};
 use crate::{
     archetype::{ArchetypeId, ArchetypeRow},
     change_detection::MaybeLocation,
+    component::Tick,
     storage::{SparseSetIndex, TableId, TableRow},
 };
 use alloc::vec::Vec;
 use bevy_platform::sync::atomic::Ordering;
-use core::{fmt, hash::Hash, mem, num::NonZero, panic::Location};
+use core::{
+    fmt,
+    hash::Hash,
+    mem::{self, MaybeUninit},
+    num::NonZero,
+    panic::Location,
+};
 use log::warn;
 
 #[cfg(feature = "serialize")]
@@ -899,7 +906,10 @@ impl Entities {
     }
 
     /// Updates the location of an [`Entity`]. This must be called when moving the components of
-    /// the entity around in storage.
+    /// the existing entity around in storage.
+    ///
+    /// For spawning and despawning entities, [`set_spawn_despawn`](Self::set_spawn_despawn) must
+    /// be used instead.
     ///
     /// # Safety
     ///  - `index` must be a valid entity index.
@@ -912,6 +922,27 @@ impl Entities {
         meta.location = location;
     }
 
+    /// Updates the location of an [`Entity`]. This must be called when moving the components of
+    /// the spawned or despawned entity around in storage.
+    ///
+    /// # Safety
+    ///  - `index` must be a valid entity index.
+    ///  - `location` must be valid for the entity at `index` or immediately made valid afterwards
+    ///    before handing control to unknown code.
+    #[inline]
+    pub(crate) unsafe fn set_spawn_despawn(
+        &mut self,
+        index: u32,
+        location: EntityLocation,
+        by: MaybeLocation,
+        at: Tick,
+    ) {
+        // SAFETY: Caller guarantees that `index` a valid entity index
+        let meta = unsafe { self.meta.get_unchecked_mut(index as usize) };
+        meta.location = location;
+        meta.spawned_or_despawned = MaybeUninit::new(SpawnedOrDespawned { by, at });
+    }
+
     /// Increments the `generation` of a freed [`Entity`]. The next entity ID allocated with this
     /// `index` will count `generation` starting from the prior `generation` + the specified
     /// value + 1.
@@ -1052,19 +1083,6 @@ impl Entities {
         self.len() == 0
     }
 
-    /// Sets the source code location from which this entity has last been spawned
-    /// or despawned.
-    #[inline]
-    pub(crate) fn set_spawned_or_despawned_by(&mut self, index: u32, caller: MaybeLocation) {
-        caller.map(|caller| {
-            let meta = self
-                .meta
-                .get_mut(index as usize)
-                .expect("Entity index invalid");
-            meta.spawned_or_despawned_by = MaybeLocation::new(Some(caller));
-        });
-    }
-
     /// Returns the source code location from which this entity has last been spawned
     /// or despawned. Returns `None` if its index has been reused by another entity
     /// or if this entity has never existed.
@@ -1073,16 +1091,67 @@ impl Entities {
         entity: Entity,
     ) -> MaybeLocation<Option<&'static Location<'static>>> {
         MaybeLocation::new_with_flattened(|| {
-            self.meta
-                .get(entity.index() as usize)
-                .filter(|meta|
-                // Generation is incremented immediately upon despawn
-                (meta.generation == entity.generation)
-                || (meta.location.archetype_id == ArchetypeId::INVALID)
-                && (meta.generation == entity.generation.after_versions(1)))
-                .map(|meta| meta.spawned_or_despawned_by)
+            self.entity_get_spawned_or_despawned(entity)
+                .map(|spawned_or_despawned| spawned_or_despawned.by)
         })
-        .map(Option::flatten)
+    }
+
+    /// Returns the [`Tick`] at which this entity has last been spawned or despawned.
+    /// Returns `None` if its index has been reused by another entity or if this entity
+    /// has never existed.
+    pub fn entity_get_spawned_or_despawned_at(&self, entity: Entity) -> Option<Tick> {
+        self.entity_get_spawned_or_despawned(entity)
+            .map(|spawned_or_despawned| spawned_or_despawned.at)
+    }
+
+    /// Returns the [`SpawnedOrDespawned`] related to the entity's last spawn or
+    /// respawn. Returns `None` if its index has been reused by another entity or if
+    /// this entity has never existed.
+    #[inline]
+    fn entity_get_spawned_or_despawned(&self, entity: Entity) -> Option<SpawnedOrDespawned> {
+        self.meta
+            .get(entity.index() as usize)
+            .filter(|meta|
+            // Generation is incremented immediately upon despawn
+            (meta.generation == entity.generation)
+            || (meta.location.archetype_id == ArchetypeId::INVALID)
+            && (meta.generation == entity.generation.after_versions(1)))
+            .map(|meta| {
+                // SAFETY: valid archetype or non-min generation is proof this is init
+                unsafe { meta.spawned_or_despawned.assume_init() }
+            })
+    }
+
+    /// Returns the source code location from which this entity has last been spawned
+    /// or despawned and the Tick of when that happened.
+    ///
+    /// # Safety
+    ///
+    /// The entity index must belong to an entity that is currently alive or, if it
+    /// despawned, was not overwritten by a new entity of the same index.
+    #[inline]
+    pub(crate) unsafe fn entity_get_spawned_or_despawned_unchecked(
+        &self,
+        entity: Entity,
+    ) -> (MaybeLocation, Tick) {
+        // SAFETY: caller ensures entity is allocated
+        let meta = unsafe { self.meta.get_unchecked(entity.index() as usize) };
+        // SAFETY: caller ensures entities of this index were at least spawned
+        let spawned_or_despawned = unsafe { meta.spawned_or_despawned.assume_init() };
+        (spawned_or_despawned.by, spawned_or_despawned.at)
+    }
+
+    #[inline]
+    pub(crate) fn check_change_ticks(&mut self, change_tick: Tick) {
+        for meta in &mut self.meta {
+            if meta.generation != EntityGeneration::FIRST
+                || meta.location.archetype_id != ArchetypeId::INVALID
+            {
+                // SAFETY: non-min generation or valid archetype is proof this is init
+                let spawned_or_despawned = unsafe { meta.spawned_or_despawned.assume_init_mut() };
+                spawned_or_despawned.at.check_tick(change_tick);
+            }
+        }
     }
 
     /// Constructs a message explaining why an entity does not exist, if known.
@@ -1145,15 +1214,21 @@ struct EntityMeta {
     /// The current location of the [`EntityRow`]
     pub location: EntityLocation,
     /// Location of the last spawn or despawn of this entity
-    spawned_or_despawned_by: MaybeLocation<Option<&'static Location<'static>>>,
+    spawned_or_despawned: MaybeUninit<SpawnedOrDespawned>,
+}
+
+#[derive(Copy, Clone, Debug)]
+struct SpawnedOrDespawned {
+    by: MaybeLocation,
+    at: Tick,
 }
 
 impl EntityMeta {
     /// meta for **pending entity**
     const EMPTY: EntityMeta = EntityMeta {
         generation: EntityGeneration::FIRST,
         location: EntityLocation::INVALID,
-        spawned_or_despawned_by: MaybeLocation::new(None),
+        spawned_or_despawned: MaybeUninit::uninit(),
     };
 }
 

crates/bevy_ecs/src/query/fetch.rs

@@ -31,6 +31,8 @@ use variadics_please::all_tuples;
 ///   Gets the identifier of the queried entity.
 /// - **[`EntityLocation`].**
 ///   Gets the location metadata of the queried entity.
+/// - **[`SpawnDetails`].**
+///   Gets the tick the entity was spawned at.
 /// - **[`EntityRef`].**
 ///   Read-only access to arbitrary components on the queried entity.
 /// - **[`EntityMut`].**
@@ -486,6 +488,166 @@ unsafe impl QueryData for EntityLocation {
 /// SAFETY: access is read only
 unsafe impl ReadOnlyQueryData for EntityLocation {}
 
+/// The `SpawnDetails` query parameter fetches the [`Tick`] the entity was spawned at.
+///
+/// To evaluate whether the spawn happened since the last time the system ran, the system
+/// param [`SystemChangeTick`](bevy_ecs::system::SystemChangeTick) needs to be used.
+///
+/// If the query should filter for spawned entities instead, use the
+/// [`Spawned`](bevy_ecs::query::Spawned) query filter instead.
+///
+/// # Examples
+///
+/// ```
+/// # use bevy_ecs::component::Component;
+/// # use bevy_ecs::entity::Entity;
+/// # use bevy_ecs::system::Query;
+/// # use bevy_ecs::query::Spawned;
+/// # use bevy_ecs::query::SpawnDetails;
+///
+/// fn print_spawn_details(query: Query<(Entity, SpawnDetails)>) {
+///     for (entity, spawn_details) in &query {
+///         if spawn_details.is_spawned() {
+///             print!("new ");
+///         }
+///         print!(
+///             "entity {:?} spawned at {:?}",
+///             entity,
+///             spawn_details.spawned_at()
+///         );
+///         match spawn_details.spawned_by().into_option() {
+///             Some(location) => println!(" by {:?}", location),
+///             None => println!()
+///         }    
+///     }
+/// }
+///
+/// # bevy_ecs::system::assert_is_system(print_spawn_details);
+/// ```
+#[derive(Clone, Copy, Debug)]
+pub struct SpawnDetails {
+    spawned_by: MaybeLocation,
+    spawned_at: Tick,
+    last_run: Tick,
+    this_run: Tick,
+}
+
+impl SpawnDetails {
+    /// Returns `true` if the entity spawned since the last time this system ran.
+    /// Otherwise, returns `false`.
+    pub fn is_spawned(self) -> bool {
+        self.spawned_at.is_newer_than(self.last_run, self.this_run)
+    }
+
+    /// Returns the `Tick` this entity spawned at.
+    pub fn spawned_at(self) -> Tick {
+        self.spawned_at
+    }
+
+    /// Returns the source code location from which this entity has been spawned.
+    pub fn spawned_by(self) -> MaybeLocation {
+        self.spawned_by
+    }
+}
+
+#[doc(hidden)]
+#[derive(Clone)]
+pub struct SpawnDetailsFetch<'w> {
+    entities: &'w Entities,
+    last_run: Tick,
+    this_run: Tick,
+}
+
+// SAFETY:
+// No components are accessed.
+unsafe impl WorldQuery for SpawnDetails {
+    type Fetch<'w> = SpawnDetailsFetch<'w>;
+    type State = ();
+
+    fn shrink_fetch<'wlong: 'wshort, 'wshort>(fetch: Self::Fetch<'wlong>) -> Self::Fetch<'wshort> {
+        fetch
+    }
+
+    unsafe fn init_fetch<'w>(
+        world: UnsafeWorldCell<'w>,
+        _state: &Self::State,
+        last_run: Tick,
+        this_run: Tick,
+    ) -> Self::Fetch<'w> {
+        SpawnDetailsFetch {
+            entities: world.entities(),
+            last_run,
+            this_run,
+        }
+    }
+
+    const IS_DENSE: bool = true;
+
+    #[inline]
+    unsafe fn set_archetype<'w>(
+        _fetch: &mut Self::Fetch<'w>,
+        _state: &Self::State,
+        _archetype: &'w Archetype,
+        _table: &'w Table,
+    ) {
+    }
+
+    #[inline]
+    unsafe fn set_table<'w>(_fetch: &mut Self::Fetch<'w>, _state: &Self::State, _table: &'w Table) {
+    }
+
+    fn update_component_access(_state: &Self::State, _access: &mut FilteredAccess<ComponentId>) {}
+
+    fn init_state(_world: &mut World) {}
+
+    fn get_state(_components: &Components) -> Option<()> {
+        Some(())
+    }
+
+    fn matches_component_set(
+        _state: &Self::State,
+        _set_contains_id: &impl Fn(ComponentId) -> bool,
+    ) -> bool {
+        true
+    }
+}
+
+// SAFETY:
+// No components are accessed.
+// Is its own ReadOnlyQueryData.
+unsafe impl QueryData for SpawnDetails {
+    const IS_READ_ONLY: bool = true;
+    type ReadOnly = Self;
+    type Item<'w> = Self;
+
+    fn shrink<'wlong: 'wshort, 'wshort>(item: Self::Item<'wlong>) -> Self::Item<'wshort> {
+        item
+    }
+
+    #[inline(always)]
+    unsafe fn fetch<'w>(
+        fetch: &mut Self::Fetch<'w>,
+        entity: Entity,
+        _table_row: TableRow,
+    ) -> Self::Item<'w> {
+        // SAFETY: only living entities are queried
+        let (spawned_by, spawned_at) = unsafe {
+            fetch
+                .entities
+                .entity_get_spawned_or_despawned_unchecked(entity)
+        };
+        Self {
+            spawned_by,
+            spawned_at,
+            last_run: fetch.last_run,
+            this_run: fetch.this_run,
+        }
+    }
+}
+
+/// SAFETY: access is read only
+unsafe impl ReadOnlyQueryData for SpawnDetails {}
+
 /// The [`WorldQuery::Fetch`] type for WorldQueries that can fetch multiple components from an entity
 /// ([`EntityRef`], [`EntityMut`], etc.)
 #[derive(Copy, Clone)]