Component Lifecycle Hooks and a Deferred World

Cargo.toml

@@ -1400,6 +1400,17 @@ description = "Change detection on components"
 category = "ECS (Entity Component System)"
 wasm = false
 
+[[example]]
+name = "component_hooks"
+path = "examples/ecs/component_hooks.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.component_hooks]
+name = "Component Hooks"
+description = "Define component hooks to manage component lifecycle events"
+category = "ECS (Entity Component System)"
+wasm = false
+
 [[example]]
 name = "custom_schedule"
 path = "examples/ecs/custom_schedule.rs"

crates/bevy_ecs/Cargo.toml

@@ -23,6 +23,9 @@ bevy_utils = { path = "../bevy_utils", version = "0.13.0" }
 bevy_ecs_macros = { path = "macros", version = "0.13.0" }
 
 async-channel = "2.1.0"
+bitflags = "2.3"
+event-listener = "2.5"
+thread_local = "1.1.4"
 fixedbitset = "0.4.2"
 rustc-hash = "1.1"
 downcast-rs = "1.2"

crates/bevy_ecs/src/archetype.rs

@@ -21,7 +21,7 @@
 
 use crate::{
     bundle::BundleId,
-    component::{ComponentId, StorageType},
+    component::{ComponentId, Components, StorageType},
     entity::{Entity, EntityLocation},
     storage::{ImmutableSparseSet, SparseArray, SparseSet, SparseSetIndex, TableId, TableRow},
 };
@@ -107,7 +107,7 @@ impl ArchetypeId {
     }
 }
 
-#[derive(Copy, Clone)]
+#[derive(Copy, Clone, Eq, PartialEq)]
 pub(crate) enum ComponentStatus {
     Added,
     Mutated,
@@ -298,6 +298,18 @@ struct ArchetypeComponentInfo {
     archetype_component_id: ArchetypeComponentId,
 }
 
+bitflags::bitflags! {
+    /// Flags used to keep track of metadata about the component in this [`Archetype`]
+    ///
+    /// Used primarily to early-out when there are no [`ComponentHook`] registered for any contained components.
+    #[derive(Clone, Copy)]
+    pub(crate) struct ArchetypeFlags: u32 {
+        const ON_ADD_HOOK    = (1 << 0);
+        const ON_INSERT_HOOK = (1 << 1);
+        const ON_REMOVE_HOOK = (1 << 2);
+    }
+}
+
 /// Metadata for a single archetype within a [`World`].
 ///
 /// For more information, see the *[module level documentation]*.
@@ -310,20 +322,26 @@ pub struct Archetype {
     edges: Edges,
     entities: Vec<ArchetypeEntity>,
     components: ImmutableSparseSet<ComponentId, ArchetypeComponentInfo>,
+    flags: ArchetypeFlags,
 }
 
 impl Archetype {
     pub(crate) fn new(
+        components: &Components,
         id: ArchetypeId,
         table_id: TableId,
         table_components: impl Iterator<Item = (ComponentId, ArchetypeComponentId)>,
         sparse_set_components: impl Iterator<Item = (ComponentId, ArchetypeComponentId)>,
     ) -> Self {
         let (min_table, _) = table_components.size_hint();
         let (min_sparse, _) = sparse_set_components.size_hint();
-        let mut components = SparseSet::with_capacity(min_table + min_sparse);
+        let mut flags = ArchetypeFlags::empty();
+        let mut archetype_components = SparseSet::with_capacity(min_table + min_sparse);
         for (component_id, archetype_component_id) in table_components {
-            components.insert(
+            // SAFETY: We are creating an archetype that includes this component so it must exist
+            let info = unsafe { components.get_info_unchecked(component_id) };
+            info.update_archetype_flags(&mut flags);
+            archetype_components.insert(
                 component_id,
                 ArchetypeComponentInfo {
                     storage_type: StorageType::Table,
@@ -333,7 +351,10 @@ impl Archetype {
         }
 
         for (component_id, archetype_component_id) in sparse_set_components {
-            components.insert(
+            // SAFETY: We are creating an archetype that includes this component so it must exist
+            let info = unsafe { components.get_info_unchecked(component_id) };
+            info.update_archetype_flags(&mut flags);
+            archetype_components.insert(
                 component_id,
                 ArchetypeComponentInfo {
                     storage_type: StorageType::SparseSet,
@@ -345,8 +366,9 @@ impl Archetype {
             id,
             table_id,
             entities: Vec::new(),
-            components: components.into_immutable(),
+            components: archetype_components.into_immutable(),
             edges: Default::default(),
+            flags,
         }
     }
 
@@ -356,6 +378,12 @@ impl Archetype {
         self.id
     }
 
+    /// Fetches the flags for the archetype.
+    #[inline]
+    pub(crate) fn flags(&self) -> ArchetypeFlags {
+        self.flags
+    }
+
     /// Fetches the archetype's [`Table`] ID.
     ///
     /// [`Table`]: crate::storage::Table
@@ -536,6 +564,24 @@ impl Archetype {
     pub(crate) fn clear_entities(&mut self) {
         self.entities.clear();
     }
+
+    /// Returns true if any of the components in this archetype have `on_add` hooks
+    #[inline]
+    pub fn has_on_add(&self) -> bool {
+        self.flags().contains(ArchetypeFlags::ON_ADD_HOOK)
+    }
+
+    /// Returns true if any of the components in this archetype have `on_insert` hooks
+    #[inline]
+    pub fn has_on_insert(&self) -> bool {
+        self.flags().contains(ArchetypeFlags::ON_INSERT_HOOK)
+    }
+
+    /// Returns true if any of the components in this archetype have `on_remove` hooks
+    #[inline]
+    pub fn has_on_remove(&self) -> bool {
+        self.flags().contains(ArchetypeFlags::ON_REMOVE_HOOK)
+    }
 }
 
 /// The next [`ArchetypeId`] in an [`Archetypes`] collection.
@@ -618,7 +664,12 @@ impl Archetypes {
             by_components: Default::default(),
             archetype_component_count: 0,
         };
-        archetypes.get_id_or_insert(TableId::empty(), Vec::new(), Vec::new());
+        archetypes.get_id_or_insert(
+            &Components::default(),
+            TableId::empty(),
+            Vec::new(),
+            Vec::new(),
+        );
         archetypes
     }
 
@@ -713,6 +764,7 @@ impl Archetypes {
     /// [`TableId`] must exist in tables
     pub(crate) fn get_id_or_insert(
         &mut self,
+        components: &Components,
         table_id: TableId,
         table_components: Vec<ComponentId>,
         sparse_set_components: Vec<ComponentId>,
@@ -738,6 +790,7 @@ impl Archetypes {
                 let sparse_set_archetype_components =
                     (sparse_start..*archetype_component_count).map(ArchetypeComponentId);
                 archetypes.push(Archetype::new(
+                    components,
                     id,
                     table_id,
                     table_components.into_iter().zip(table_archetype_components),