Required Components

crates/bevy_ecs/macros/src/component.rs

@@ -1,7 +1,16 @@
 use proc_macro::TokenStream;
 use proc_macro2::{Span, TokenStream as TokenStream2};
-use quote::quote;
-use syn::{parse_macro_input, parse_quote, DeriveInput, ExprPath, Ident, LitStr, Path, Result};
+use quote::{quote, ToTokens};
+use std::collections::HashSet;
+use syn::{
+    parenthesized,
+    parse::Parse,
+    parse_macro_input, parse_quote,
+    punctuated::Punctuated,
+    spanned::Spanned,
+    token::{Comma, Paren},
+    DeriveInput, ExprPath, Ident, LitStr, Path, Result,
+};
 
 pub fn derive_event(input: TokenStream) -> TokenStream {
     let mut ast = parse_macro_input!(input as DeriveInput);
@@ -66,12 +75,55 @@ pub fn derive_component(input: TokenStream) -> TokenStream {
         .predicates
         .push(parse_quote! { Self: Send + Sync + 'static });
 
+    let requires = &attrs.requires;
+    let mut register_required = Vec::with_capacity(attrs.requires.iter().len());
+    let mut register_recursive_requires = Vec::with_capacity(attrs.requires.iter().len());
+    if let Some(requires) = requires {
+        for require in requires {
+            let ident = &require.path;
+            register_recursive_requires.push(quote! {
+                <#ident as Component>::register_required_components(components, storages, required_components);
+            });
+            if let Some(func) = &require.func {
+                register_required.push(quote! {
+                    required_components.register(components, storages, || { let x: #ident = #func().into(); x });
+                });
+            } else {
+                register_required.push(quote! {
+                    required_components.register(components, storages, <#ident as Default>::default);
+                });
+            }
+        }
+    }
     let struct_name = &ast.ident;
     let (impl_generics, type_generics, where_clause) = &ast.generics.split_for_impl();
 
+    let required_component_docs = attrs.requires.map(|r| {
+        let paths = r
+            .iter()
+            .map(|r| format!("[`{}`]", r.path.to_token_stream()))
+            .collect::<Vec<_>>()
+            .join(", ");
+        let doc = format!("Required Components: {paths}. \n\n A component's Required Components are inserted whenever it is inserted. Note that this will also insert the required components _of_ the required components, recursively, in depth-first order.");
+        quote! {
+            #[doc = #doc]
+        }
+    });
+
+    // This puts `register_required` before `register_recursive_requires` to ensure that the constructors of _all_ top
+    // level components are initialized first, giving them precedence over recursively defined constructors for the same component type
     TokenStream::from(quote! {
+        #required_component_docs
         impl #impl_generics #bevy_ecs_path::component::Component for #struct_name #type_generics #where_clause {
             const STORAGE_TYPE: #bevy_ecs_path::component::StorageType = #storage;
+            fn register_required_components(
+                components: &mut #bevy_ecs_path::component::Components,
+                storages: &mut #bevy_ecs_path::storage::Storages,
+                required_components: &mut #bevy_ecs_path::component::RequiredComponents
+            ) {
+                #(#register_required)*
+                #(#register_recursive_requires)*
+            }
 
             #[allow(unused_variables)]
             fn register_component_hooks(hooks: &mut #bevy_ecs_path::component::ComponentHooks) {
@@ -86,13 +138,16 @@ pub fn derive_component(input: TokenStream) -> TokenStream {
 
 pub const COMPONENT: &str = "component";
 pub const STORAGE: &str = "storage";
+pub const REQUIRE: &str = "require";
+
 pub const ON_ADD: &str = "on_add";
 pub const ON_INSERT: &str = "on_insert";
 pub const ON_REPLACE: &str = "on_replace";
 pub const ON_REMOVE: &str = "on_remove";
 
 struct Attrs {
     storage: StorageTy,
+    requires: Option<Punctuated<Require, Comma>>,
     on_add: Option<ExprPath>,
     on_insert: Option<ExprPath>,
     on_replace: Option<ExprPath>,
@@ -105,6 +160,11 @@ enum StorageTy {
     SparseSet,
 }
 
+struct Require {
+    path: Path,
+    func: Option<Path>,
+}
+
 // values for `storage` attribute
 const TABLE: &str = "Table";
 const SPARSE_SET: &str = "SparseSet";
@@ -116,42 +176,77 @@ fn parse_component_attr(ast: &DeriveInput) -> Result<Attrs> {
         on_insert: None,
         on_replace: None,
         on_remove: None,
+        requires: None,
     };
 
-    for meta in ast.attrs.iter().filter(|a| a.path().is_ident(COMPONENT)) {
-        meta.parse_nested_meta(|nested| {
-            if nested.path.is_ident(STORAGE) {
-                attrs.storage = match nested.value()?.parse::<LitStr>()?.value() {
-                    s if s == TABLE => StorageTy::Table,
-                    s if s == SPARSE_SET => StorageTy::SparseSet,
-                    s => {
-                        return Err(nested.error(format!(
-                            "Invalid storage type `{s}`, expected '{TABLE}' or '{SPARSE_SET}'.",
-                        )));
-                    }
-                };
-                Ok(())
-            } else if nested.path.is_ident(ON_ADD) {
-                attrs.on_add = Some(nested.value()?.parse::<ExprPath>()?);
-                Ok(())
-            } else if nested.path.is_ident(ON_INSERT) {
-                attrs.on_insert = Some(nested.value()?.parse::<ExprPath>()?);
-                Ok(())
-            } else if nested.path.is_ident(ON_REPLACE) {
-                attrs.on_replace = Some(nested.value()?.parse::<ExprPath>()?);
-                Ok(())
-            } else if nested.path.is_ident(ON_REMOVE) {
-                attrs.on_remove = Some(nested.value()?.parse::<ExprPath>()?);
-                Ok(())
+    let mut require_paths = HashSet::new();
+    for attr in ast.attrs.iter() {
+        if attr.path().is_ident(COMPONENT) {
+            attr.parse_nested_meta(|nested| {
+                if nested.path.is_ident(STORAGE) {
+                    attrs.storage = match nested.value()?.parse::<LitStr>()?.value() {
+                        s if s == TABLE => StorageTy::Table,
+                        s if s == SPARSE_SET => StorageTy::SparseSet,
+                        s => {
+                            return Err(nested.error(format!(
+                                "Invalid storage type `{s}`, expected '{TABLE}' or '{SPARSE_SET}'.",
+                            )));
+                        }
+                    };
+                    Ok(())
+                } else if nested.path.is_ident(ON_ADD) {
+                    attrs.on_add = Some(nested.value()?.parse::<ExprPath>()?);
+                    Ok(())
+                } else if nested.path.is_ident(ON_INSERT) {
+                    attrs.on_insert = Some(nested.value()?.parse::<ExprPath>()?);
+                    Ok(())
+                } else if nested.path.is_ident(ON_REPLACE) {
+                    attrs.on_replace = Some(nested.value()?.parse::<ExprPath>()?);
+                    Ok(())
+                } else if nested.path.is_ident(ON_REMOVE) {
+                    attrs.on_remove = Some(nested.value()?.parse::<ExprPath>()?);
+                    Ok(())
+                } else {
+                    Err(nested.error("Unsupported attribute"))
+                }
+            })?;
+        } else if attr.path().is_ident(REQUIRE) {
+            let punctuated =
+                attr.parse_args_with(Punctuated::<Require, Comma>::parse_terminated)?;
+            for require in punctuated.iter() {
+                if !require_paths.insert(require.path.to_token_stream().to_string()) {
+                    return Err(syn::Error::new(
+                        require.path.span(),
+                        "Duplicate required components are not allowed.",
+                    ));
+                }
+            }
+            if let Some(current) = &mut attrs.requires {
+                current.extend(punctuated);
             } else {
-                Err(nested.error("Unsupported attribute"))
+                attrs.requires = Some(punctuated);
             }
-        })?;
+        }
     }
 
     Ok(attrs)
 }
 
+impl Parse for Require {
+    fn parse(input: syn::parse::ParseStream) -> Result<Self> {
+        let path = input.parse::<Path>()?;
+        let func = if input.peek(Paren) {
+            let content;
+            parenthesized!(content in input);
+            let func = content.parse::<Path>()?;
+            Some(func)
+        } else {
+            None
+        };
+        Ok(Require { path, func })
+    }
+}
+
 fn storage_path(bevy_ecs_path: &Path, ty: StorageTy) -> TokenStream2 {
     let storage_type = match ty {
         StorageTy::Table => Ident::new("Table", Span::call_site()),

crates/bevy_ecs/macros/src/lib.rs

@@ -77,6 +77,7 @@ pub fn derive_bundle(input: TokenStream) -> TokenStream {
     let mut field_get_component_ids = Vec::new();
     let mut field_get_components = Vec::new();
     let mut field_from_components = Vec::new();
+    let mut field_required_components = Vec::new();
     for (((i, field_type), field_kind), field) in field_type
         .iter()
         .enumerate()
@@ -88,6 +89,9 @@ pub fn derive_bundle(input: TokenStream) -> TokenStream {
                 field_component_ids.push(quote! {
                 <#field_type as #ecs_path::bundle::Bundle>::component_ids(components, storages, &mut *ids);
                 });
+                field_required_components.push(quote! {
+                    <#field_type as #ecs_path::bundle::Bundle>::register_required_components(components, storages, required_components);
+                });
                 field_get_component_ids.push(quote! {
                     <#field_type as #ecs_path::bundle::Bundle>::get_component_ids(components, &mut *ids);
                 });
@@ -153,6 +157,14 @@ pub fn derive_bundle(input: TokenStream) -> TokenStream {
                     #(#field_from_components)*
                 }
             }
+
+            fn register_required_components(
+                components: &mut #ecs_path::component::Components,
+                storages: &mut #ecs_path::storage::Storages,
+                required_components: &mut #ecs_path::component::RequiredComponents
+            ){
+                #(#field_required_components)*
+            }
         }
 
         impl #impl_generics #ecs_path::bundle::DynamicBundle for #struct_name #ty_generics #where_clause {
@@ -527,7 +539,7 @@ pub fn derive_resource(input: TokenStream) -> TokenStream {
     component::derive_resource(input)
 }
 
-#[proc_macro_derive(Component, attributes(component))]
+#[proc_macro_derive(Component, attributes(component, require))]
 pub fn derive_component(input: TokenStream) -> TokenStream {
     component::derive_component(input)
 }

crates/bevy_ecs/src/archetype.rs

@@ -21,7 +21,7 @@
 
 use crate::{
     bundle::BundleId,
-    component::{ComponentId, Components, StorageType},
+    component::{ComponentId, Components, RequiredComponentConstructor, StorageType},
     entity::{Entity, EntityLocation},
     observer::Observers,
     storage::{ImmutableSparseSet, SparseArray, SparseSet, SparseSetIndex, TableId, TableRow},
@@ -123,10 +123,31 @@ pub(crate) struct AddBundle {
     /// For each component iterated in the same order as the source [`Bundle`](crate::bundle::Bundle),
     /// indicate if the component is newly added to the target archetype or if it already existed
     pub bundle_status: Vec<ComponentStatus>,
+    /// The set of additional required components that must be initialized immediately when adding this Bundle.
+    ///
+    /// The initial values are determined based on the provided constructor, falling back to the `Default` trait if none is given.
+    pub required_components: Vec<RequiredComponentConstructor>,
+    /// The components added by this bundle. This includes any Required Components that are inserted when adding this bundle.
     pub added: Vec<ComponentId>,
+    /// The components that were explicitly contributed by this bundle, but already existed in the archetype. This _does not_ include any
+    /// Required Components.
     pub existing: Vec<ComponentId>,
 }
 
+impl AddBundle {
+    pub(crate) fn iter_inserted(&self) -> impl Iterator<Item = ComponentId> + '_ {
+        self.added.iter().chain(self.existing.iter()).copied()
+    }
+
+    pub(crate) fn iter_added(&self) -> impl Iterator<Item = ComponentId> + '_ {
+        self.added.iter().copied()
+    }
+
+    pub(crate) fn iter_existing(&self) -> impl Iterator<Item = ComponentId> + '_ {
+        self.existing.iter().copied()
+    }
+}
+
 /// This trait is used to report the status of [`Bundle`](crate::bundle::Bundle) components
 /// being added to a given entity, relative to that entity's original archetype.
 /// See [`crate::bundle::BundleInfo::write_components`] for more info.
@@ -208,6 +229,7 @@ impl Edges {
         bundle_id: BundleId,
         archetype_id: ArchetypeId,
         bundle_status: Vec<ComponentStatus>,
+        required_components: Vec<RequiredComponentConstructor>,
         added: Vec<ComponentId>,
         existing: Vec<ComponentId>,
     ) {
@@ -216,6 +238,7 @@ impl Edges {
             AddBundle {
                 archetype_id,
                 bundle_status,
+                required_components,
                 added,
                 existing,
             },