Runtime required components

crates/bevy_app/src/app.rs

@@ -4,6 +4,7 @@ use crate::{
 };
 pub use bevy_derive::AppLabel;
 use bevy_ecs::{
+    component::RequiredComponentsError,
     event::{event_update_system, EventCursor},
     intern::Interned,
     prelude::*,
@@ -753,6 +754,260 @@ impl App {
         self
     }
 
+    /// Registers the given component `R` as a [required component] for `T`.
+    ///
+    /// When `T` is added to an entity, `R` and its own required components will also be added
+    /// if `R` was not already provided. The [`Default`] `constructor` will be used for the creation of `R`.
+    /// If a custom constructor is desired, use [`App::register_required_components_with`] instead.
+    ///
+    /// For the non-panicking version, see [`App::try_register_required_components`].
+    ///
+    /// Note that requirements must currently be registered before `T` is inserted into the world
+    /// for the first time. Commonly, this is done in plugins. This limitation may be fixed in the future.
+    ///
+    /// [required component]: Component#required-components
+    ///
+    /// # Panics
+    ///
+    /// Panics if `R` is already a directly required component for `T`, or if `T` has ever been added
+    /// on an entity before the registration.
+    ///
+    /// Indirect requirements through other components are allowed. In those cases, any existing requirements
+    /// will only be overwritten if the new requirement is more specific.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use bevy_app::{App, NoopPluginGroup as MinimalPlugins, Startup};
+    /// # use bevy_ecs::prelude::*;
+    /// #[derive(Component)]
+    /// struct A;
+    ///
+    /// #[derive(Component, Default, PartialEq, Eq, Debug)]
+    /// struct B(usize);
+    ///
+    /// #[derive(Component, Default, PartialEq, Eq, Debug)]
+    /// struct C(u32);
+    ///
+    /// # let mut app = App::new();
+    /// # app.add_plugins(MinimalPlugins).add_systems(Startup, setup);
+    /// // Register B as required by A and C as required by B.
+    /// app.register_required_components::<A, B>();
+    /// app.register_required_components::<B, C>();
+    ///
+    /// fn setup(mut commands: Commands) {
+    ///     // This will implicitly also insert B and C with their Default constructors.
+    ///     commands.spawn(A);
+    /// }
+    ///
+    /// fn validate(query: Query<(&A, &B, &C)>) {
+    ///     let (a, b, c) = query.single();
+    ///     assert_eq!(b, &B(0));
+    ///     assert_eq!(c, &C(0));
+    /// }
+    /// # app.update();
+    /// ```
+    pub fn register_required_components<T: Component, R: Component + Default>(
+        &mut self,
+    ) -> &mut Self {
+        self.world_mut().register_required_components::<T, R>();
+        self
+    }
+
+    /// Registers the given component `R` as a [required component] for `T`.
+    ///
+    /// When `T` is added to an entity, `R` and its own required components will also be added
+    /// if `R` was not already provided. The given `constructor` will be used for the creation of `R`.
+    /// If a [`Default`] constructor is desired, use [`App::register_required_components`] instead.
+    ///
+    /// For the non-panicking version, see [`App::try_register_required_components_with`].
+    ///
+    /// Note that requirements must currently be registered before `T` is inserted into the world
+    /// for the first time. Commonly, this is done in plugins. This limitation may be fixed in the future.
+    ///
+    /// [required component]: Component#required-components
+    ///
+    /// # Panics
+    ///
+    /// Panics if `R` is already a directly required component for `T`, or if `T` has ever been added
+    /// on an entity before the registration.
+    ///
+    /// Indirect requirements through other components are allowed. In those cases, any existing requirements
+    /// will only be overwritten if the new requirement is more specific.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use bevy_app::{App, NoopPluginGroup as MinimalPlugins, Startup};
+    /// # use bevy_ecs::prelude::*;
+    /// #[derive(Component)]
+    /// struct A;
+    ///
+    /// #[derive(Component, Default, PartialEq, Eq, Debug)]
+    /// struct B(usize);
+    ///
+    /// #[derive(Component, Default, PartialEq, Eq, Debug)]
+    /// struct C(u32);
+    ///
+    /// # let mut app = App::new();
+    /// # app.add_plugins(MinimalPlugins).add_systems(Startup, setup);
+    /// // Register B and C as required by A and C as required by B.
+    /// // A requiring C directly will overwrite the indirect requirement through B.
+    /// app.register_required_components::<A, B>();
+    /// app.register_required_components_with::<B, C>(|| C(1));
+    /// app.register_required_components_with::<A, C>(|| C(2));
+    ///
+    /// fn setup(mut commands: Commands) {
+    ///     // This will implicitly also insert B with its Default constructor and C
+    ///     // with the custom constructor defined by A.
+    ///     commands.spawn(A);
+    /// }
+    ///
+    /// fn validate(query: Query<(&A, &B, &C)>) {
+    ///     let (a, b, c) = query.single();
+    ///     assert_eq!(b, &B(0));
+    ///     assert_eq!(c, &C(2));
+    /// }
+    /// # app.update();
+    /// ```
+    pub fn register_required_components_with<T: Component, R: Component>(
+        &mut self,
+        constructor: fn() -> R,
+    ) -> &mut Self {
+        self.world_mut()
+            .register_required_components_with::<T, R>(constructor);
+        self
+    }
+
+    /// Tries to register the given component `R` as a [required component] for `T`.
+    ///
+    /// When `T` is added to an entity, `R` and its own required components will also be added
+    /// if `R` was not already provided. The [`Default`] `constructor` will be used for the creation of `R`.
+    /// If a custom constructor is desired, use [`App::register_required_components_with`] instead.
+    ///
+    /// For the panicking version, see [`App::register_required_components`].
+    ///
+    /// Note that requirements must currently be registered before `T` is inserted into the world
+    /// for the first time. Commonly, this is done in plugins. This limitation may be fixed in the future.
+    ///
+    /// [required component]: Component#required-components
+    ///
+    /// # Errors
+    ///
+    /// Returns a [`RequiredComponentsError`] if `R` is already a directly required component for `T`, or if `T` has ever been added
+    /// on an entity before the registration.
+    ///
+    /// Indirect requirements through other components are allowed. In those cases, any existing requirements
+    /// will only be overwritten if the new requirement is more specific.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use bevy_app::{App, NoopPluginGroup as MinimalPlugins, Startup};
+    /// # use bevy_ecs::prelude::*;
+    /// #[derive(Component)]
+    /// struct A;
+    ///
+    /// #[derive(Component, Default, PartialEq, Eq, Debug)]
+    /// struct B(usize);
+    ///
+    /// #[derive(Component, Default, PartialEq, Eq, Debug)]
+    /// struct C(u32);
+    ///
+    /// # let mut app = App::new();
+    /// # app.add_plugins(MinimalPlugins).add_systems(Startup, setup);
+    /// // Register B as required by A and C as required by B.
+    /// app.register_required_components::<A, B>();
+    /// app.register_required_components::<B, C>();
+    ///
+    /// // Duplicate registration! This will fail.
+    /// assert!(app.try_register_required_components::<A, B>().is_err());
+    ///
+    /// fn setup(mut commands: Commands) {
+    ///     // This will implicitly also insert B and C with their Default constructors.
+    ///     commands.spawn(A);
+    /// }
+    ///
+    /// fn validate(query: Query<(&A, &B, &C)>) {
+    ///     let (a, b, c) = query.single();
+    ///     assert_eq!(b, &B(0));
+    ///     assert_eq!(c, &C(0));
+    /// }
+    /// # app.update();
+    /// ```
+    pub fn try_register_required_components<T: Component, R: Component + Default>(
+        &mut self,
+    ) -> Result<(), RequiredComponentsError> {
+        self.world_mut().try_register_required_components::<T, R>()
+    }
+
+    /// Tries to register the given component `R` as a [required component] for `T`.
+    ///
+    /// When `T` is added to an entity, `R` and its own required components will also be added
+    /// if `R` was not already provided. The given `constructor` will be used for the creation of `R`.
+    /// If a [`Default`] constructor is desired, use [`App::register_required_components`] instead.
+    ///
+    /// For the panicking version, see [`App::register_required_components_with`].
+    ///
+    /// Note that requirements must currently be registered before `T` is inserted into the world
+    /// for the first time. Commonly, this is done in plugins. This limitation may be fixed in the future.
+    ///
+    /// [required component]: Component#required-components
+    ///
+    /// # Errors
+    ///
+    /// Returns a [`RequiredComponentsError`] if `R` is already a directly required component for `T`, or if `T` has ever been added
+    /// on an entity before the registration.
+    ///
+    /// Indirect requirements through other components are allowed. In those cases, any existing requirements
+    /// will only be overwritten if the new requirement is more specific.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use bevy_app::{App, NoopPluginGroup as MinimalPlugins, Startup};
+    /// # use bevy_ecs::prelude::*;
+    /// #[derive(Component)]
+    /// struct A;
+    ///
+    /// #[derive(Component, Default, PartialEq, Eq, Debug)]
+    /// struct B(usize);
+    ///
+    /// #[derive(Component, Default, PartialEq, Eq, Debug)]
+    /// struct C(u32);
+    ///
+    /// # let mut app = App::new();
+    /// # app.add_plugins(MinimalPlugins).add_systems(Startup, setup);
+    /// // Register B and C as required by A and C as required by B.
+    /// // A requiring C directly will overwrite the indirect requirement through B.
+    /// app.register_required_components::<A, B>();
+    /// app.register_required_components_with::<B, C>(|| C(1));
+    /// app.register_required_components_with::<A, C>(|| C(2));
+    ///
+    /// // Duplicate registration! Even if the constructors were different, this would fail.
+    /// assert!(app.try_register_required_components_with::<B, C>(|| C(1)).is_err());
+    ///
+    /// fn setup(mut commands: Commands) {
+    ///     // This will implicitly also insert B with its Default constructor and C
+    ///     // with the custom constructor defined by A.
+    ///     commands.spawn(A);
+    /// }
+    ///
+    /// fn validate(query: Query<(&A, &B, &C)>) {
+    ///     let (a, b, c) = query.single();
+    ///     assert_eq!(b, &B(0));
+    ///     assert_eq!(c, &C(2));
+    /// }
+    /// # app.update();
+    /// ```
+    pub fn try_register_required_components_with<T: Component, R: Component>(
+        &mut self,
+        constructor: fn() -> R,
+    ) -> Result<(), RequiredComponentsError> {
+        self.world_mut()
+            .try_register_required_components_with::<T, R>(constructor)
+    }
+
     /// Returns a reference to the [`World`].
     pub fn world(&self) -> &World {
         self.main().world()

crates/bevy_ecs/macros/src/component.rs

@@ -82,15 +82,31 @@ pub fn derive_component(input: TokenStream) -> TokenStream {
         for require in requires {
             let ident = &require.path;
             register_recursive_requires.push(quote! {
-                <#ident as Component>::register_required_components(components, storages, required_components);
+                <#ident as Component>::register_required_components(
+                    requiree,
+                    components,
+                    storages,
+                    required_components,
+                    inheritance_depth + 1
+                );
             });
             if let Some(func) = &require.func {
                 register_required.push(quote! {
-                    required_components.register(components, storages, || { let x: #ident = #func().into(); x });
+                    components.register_required_components_manual::<Self, #ident>(
+                        storages,
+                        required_components,
+                        || { let x: #ident = #func().into(); x },
+                        inheritance_depth
+                    );
                 });
             } else {
                 register_required.push(quote! {
-                    required_components.register(components, storages, <#ident as Default>::default);
+                    components.register_required_components_manual::<Self, #ident>(
+                        storages,
+                        required_components,
+                        <#ident as Default>::default,
+                        inheritance_depth
+                    );
                 });
             }
         }
@@ -117,9 +133,11 @@ pub fn derive_component(input: TokenStream) -> TokenStream {
         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(
+                requiree: #bevy_ecs_path::component::ComponentId,
                 components: &mut #bevy_ecs_path::component::Components,
                 storages: &mut #bevy_ecs_path::storage::Storages,
-                required_components: &mut #bevy_ecs_path::component::RequiredComponents
+                required_components: &mut #bevy_ecs_path::component::RequiredComponents,
+                inheritance_depth: u16,
             ) {
                 #(#register_required)*
                 #(#register_recursive_requires)*

crates/bevy_ecs/src/bundle.rs

@@ -224,7 +224,14 @@ unsafe impl<C: Component> Bundle for C {
         storages: &mut Storages,
         required_components: &mut RequiredComponents,
     ) {
-        <C as Component>::register_required_components(components, storages, required_components);
+        let component_id = components.register_component::<C>(storages);
+        <C as Component>::register_required_components(
+            component_id,
+            components,
+            storages,
+            required_components,
+            0,
+        );
     }
 
     fn get_component_ids(components: &Components, ids: &mut impl FnMut(Option<ComponentId>)) {
@@ -412,7 +419,7 @@ impl BundleInfo {
                 // This adds required components to the component_ids list _after_ using that list to remove explicitly provided
                 // components. This ordering is important!
                 component_ids.push(component_id);
-                v
+                v.constructor
             })
             .collect();