Allow tuples and single plugins in add_plugins, deprecate `add_plug…

…in` (bevyengine#8097)

# Objective

- Better consistency with `add_systems`.
- Deprecating `add_plugin` in favor of a more powerful `add_plugins`.
- Allow passing `Plugin` to `add_plugins`.
- Allow passing tuples to `add_plugins`.

## Solution

- `App::add_plugins` now takes an `impl Plugins` parameter.
- `App::add_plugin` is deprecated.
- `Plugins` is a new sealed trait that is only implemented for `Plugin`,
`PluginGroup` and tuples over `Plugins`.
- All examples, benchmarks and tests are changed to use `add_plugins`,
using tuples where appropriate.

---

## Changelog

### Changed

- `App::add_plugins` now accepts all types that implement `Plugins`,
which is implemented for:
  - Types that implement `Plugin`.
  - Types that implement `PluginGroup`.
  - Tuples (up to 16 elements) over types that implement `Plugins`.
- Deprecated `App::add_plugin` in favor of `App::add_plugins`.

## Migration Guide

- Replace `app.add_plugin(plugin)` calls with `app.add_plugins(plugin)`.

---------

Co-authored-by: Carter Anderson <mcanders1@gmail.com>

crates/bevy_app/src/app.rs

@@ -1,6 +1,4 @@
-use crate::{
-    First, Main, MainSchedulePlugin, Plugin, PluginGroup, Startup, StateTransition, Update,
-};
+use crate::{First, Main, MainSchedulePlugin, Plugin, Plugins, Startup, StateTransition, Update};
 pub use bevy_derive::AppLabel;
 use bevy_ecs::{
     prelude::*,
@@ -18,6 +16,7 @@ use std::{
 
 #[cfg(feature = "trace")]
 use bevy_utils::tracing::info_span;
+
 bevy_utils::define_label!(
     /// A strongly-typed class of labels used to identify an [`App`].
     AppLabel,
@@ -183,7 +182,7 @@ impl Default for App {
         #[cfg(feature = "bevy_reflect")]
         app.init_resource::<AppTypeRegistry>();
 
-        app.add_plugin(MainSchedulePlugin);
+        app.add_plugins(MainSchedulePlugin);
         app.add_event::<AppExit>();
 
         #[cfg(feature = "bevy_ci_testing")]
@@ -685,19 +684,16 @@ impl App {
     /// # Panics
     ///
     /// Panics if the plugin was already added to the application.
+    #[deprecated(since = "0.11.0", note = "Please use `add_plugins` instead.")]
     pub fn add_plugin<T>(&mut self, plugin: T) -> &mut Self
     where
         T: Plugin,
     {
-        match self.add_boxed_plugin(Box::new(plugin)) {
-            Ok(app) => app,
-            Err(AppError::DuplicatePlugin { plugin_name }) => panic!(
-                "Error adding plugin {plugin_name}: : plugin was already added in application"
-            ),
-        }
+        self.add_plugins(plugin)
     }
 
-    /// Boxed variant of [`add_plugin`](App::add_plugin) that can be used from a [`PluginGroup`]
+    /// Boxed variant of [`add_plugin`](App::add_plugin) that can be used from a
+    /// [`PluginGroup`](super::PluginGroup)
     pub(crate) fn add_boxed_plugin(
         &mut self,
         plugin: Box<dyn Plugin>,
@@ -752,7 +748,7 @@ impl App {
     /// #    fn build(&self, app: &mut App) {}
     /// # }
     /// # let mut app = App::new();
-    /// # app.add_plugin(ImagePlugin::default());
+    /// # app.add_plugins(ImagePlugin::default());
     /// let default_sampler = app.get_added_plugins::<ImagePlugin>()[0].default_sampler;
     /// ```
     pub fn get_added_plugins<T>(&self) -> Vec<&T>
@@ -765,31 +761,46 @@ impl App {
             .collect()
     }
 
-    /// Adds a group of [`Plugin`]s.
+    /// Adds one or more [`Plugin`]s.
+    ///
+    /// One of Bevy's core principles is modularity. All Bevy engine features are implemented
+    /// as [`Plugin`]s. This includes internal features like the renderer.
     ///
     /// [`Plugin`]s can be grouped into a set by using a [`PluginGroup`].
     ///
     /// There are built-in [`PluginGroup`]s that provide core engine functionality.
     /// The [`PluginGroup`]s available by default are `DefaultPlugins` and `MinimalPlugins`.
     ///
     /// To customize the plugins in the group (reorder, disable a plugin, add a new plugin
-    /// before / after another plugin), call [`build()`](PluginGroup::build) on the group,
+    /// before / after another plugin), call [`build()`](super::PluginGroup::build) on the group,
     /// which will convert it to a [`PluginGroupBuilder`](crate::PluginGroupBuilder).
     ///
+    /// You can also specify a group of [`Plugin`]s by using a tuple over [`Plugin`]s and
+    /// [`PluginGroup`]s. See [`Plugins`] for more details.
+    ///
     /// ## Examples
     /// ```
     /// # use bevy_app::{prelude::*, PluginGroupBuilder, NoopPluginGroup as MinimalPlugins};
     /// #
+    /// # // Dummies created to avoid using `bevy_log`,
+    /// # // which pulls in too many dependencies and breaks rust-analyzer
+    /// # pub struct LogPlugin;
+    /// # impl Plugin for LogPlugin {
+    /// #     fn build(&self, app: &mut App) {}
+    /// # }
     /// App::new()
     ///     .add_plugins(MinimalPlugins);
+    /// App::new()
+    ///     .add_plugins((MinimalPlugins, LogPlugin));
     /// ```
     ///
     /// # Panics
     ///
-    /// Panics if one of the plugin in the group was already added to the application.
-    pub fn add_plugins<T: PluginGroup>(&mut self, group: T) -> &mut Self {
-        let builder = group.build();
-        builder.finish(self);
+    /// Panics if one of the plugins was already added to the application.
+    ///
+    /// [`PluginGroup`]:super::PluginGroup
+    pub fn add_plugins<M>(&mut self, plugins: impl Plugins<M>) -> &mut Self {
+        plugins.add_to_app(self);
         self
     }
 
@@ -1006,23 +1017,23 @@ mod tests {
 
     #[test]
     fn can_add_two_plugins() {
-        App::new().add_plugin(PluginA).add_plugin(PluginB);
+        App::new().add_plugins((PluginA, PluginB));
     }
 
     #[test]
     #[should_panic]
     fn cant_add_twice_the_same_plugin() {
-        App::new().add_plugin(PluginA).add_plugin(PluginA);
+        App::new().add_plugins((PluginA, PluginA));
     }
 
     #[test]
     fn can_add_twice_the_same_plugin_with_different_type_param() {
-        App::new().add_plugin(PluginC(0)).add_plugin(PluginC(true));
+        App::new().add_plugins((PluginC(0), PluginC(true)));
     }
 
     #[test]
     fn can_add_twice_the_same_plugin_not_unique() {
-        App::new().add_plugin(PluginD).add_plugin(PluginD);
+        App::new().add_plugins((PluginD, PluginD));
     }
 
     #[test]
@@ -1035,10 +1046,10 @@ mod tests {
         }
         impl Plugin for PluginRun {
             fn build(&self, app: &mut crate::App) {
-                app.add_plugin(InnerPlugin).run();
+                app.add_plugins(InnerPlugin).run();
             }
         }
-        App::new().add_plugin(PluginRun);
+        App::new().add_plugins(PluginRun);
     }
 
     #[derive(States, PartialEq, Eq, Debug, Default, Hash, Clone)]

crates/bevy_app/src/plugin.rs

@@ -65,3 +65,61 @@ impl_downcast!(Plugin);
 ///
 /// See `bevy_dynamic_plugin/src/loader.rs#dynamically_load_plugin`.
 pub type CreatePlugin = unsafe fn() -> *mut dyn Plugin;
+
+/// Types that represent a set of [`Plugin`]s.
+///
+/// This is implemented for all types which implement [`Plugin`],
+/// [`PluginGroup`](super::PluginGroup), and tuples over [`Plugins`].
+pub trait Plugins<Marker>: sealed::Plugins<Marker> {}
+
+impl<Marker, T> Plugins<Marker> for T where T: sealed::Plugins<Marker> {}
+
+mod sealed {
+
+    use bevy_ecs::all_tuples;
+
+    use crate::{App, AppError, Plugin, PluginGroup};
+
+    pub trait Plugins<Marker> {
+        fn add_to_app(self, app: &mut App);
+    }
+
+    pub struct PluginMarker;
+    pub struct PluginGroupMarker;
+    pub struct PluginsTupleMarker;
+
+    impl<P: Plugin> Plugins<PluginMarker> for P {
+        fn add_to_app(self, app: &mut App) {
+            if let Err(AppError::DuplicatePlugin { plugin_name }) =
+                app.add_boxed_plugin(Box::new(self))
+            {
+                panic!(
+                    "Error adding plugin {plugin_name}: : plugin was already added in application"
+                )
+            }
+        }
+    }
+
+    impl<P: PluginGroup> Plugins<PluginGroupMarker> for P {
+        fn add_to_app(self, app: &mut App) {
+            self.build().finish(app);
+        }
+    }
+
+    macro_rules! impl_plugins_tuples {
+        ($(($param: ident, $plugins: ident)),*) => {
+            impl<$($param, $plugins),*> Plugins<(PluginsTupleMarker, $($param,)*)> for ($($plugins,)*)
+            where
+                $($plugins: Plugins<$param>),*
+            {
+                #[allow(non_snake_case, unused_variables)]
+                fn add_to_app(self, app: &mut App) {
+                    let ($($plugins,)*) = self;
+                    $($plugins.add_to_app(app);)*
+                }
+            }
+        }
+    }
+
+    all_tuples!(impl_plugins_tuples, 0, 15, P, S);
+}

crates/bevy_asset/src/asset_server.rs

@@ -85,7 +85,7 @@ pub struct AssetServerInternal {
 /// # use bevy_utils::Duration;
 /// # let mut app = App::new();
 /// // The asset plugin can be configured to watch for asset changes.
-/// app.add_plugin(AssetPlugin {
+/// app.add_plugins(AssetPlugin {
 ///     watch_for_changes: ChangeWatcher::with_delay(Duration::from_millis(200)),
 ///     ..Default::default()
 /// });

crates/bevy_asset/src/assets.rs

@@ -494,9 +494,11 @@ mod tests {
         #[uuid = "44115972-f31b-46e5-be5c-2b9aece6a52f"]
         struct MyAsset;
         let mut app = App::new();
-        app.add_plugin(bevy_core::TaskPoolPlugin::default())
-            .add_plugin(bevy_core::TypeRegistrationPlugin::default())
-            .add_plugin(crate::AssetPlugin::default());
+        app.add_plugins((
+            bevy_core::TaskPoolPlugin::default(),
+            bevy_core::TypeRegistrationPlugin::default(),
+            crate::AssetPlugin::default(),
+        ));
         app.add_asset::<MyAsset>();
         let mut assets_before = app.world.resource_mut::<Assets<MyAsset>>();
         let handle = assets_before.add(MyAsset);

crates/bevy_asset/src/debug_asset_server.rs

@@ -71,7 +71,7 @@ impl Plugin for DebugAssetServerPlugin {
                 .build()
         });
         let mut debug_asset_app = App::new();
-        debug_asset_app.add_plugin(AssetPlugin {
+        debug_asset_app.add_plugins(AssetPlugin {
             asset_folder: "crates".to_string(),
             watch_for_changes: ChangeWatcher::with_delay(Duration::from_millis(200)),
         });

crates/bevy_asset/src/reflect.rs

@@ -268,7 +268,7 @@ mod tests {
     #[test]
     fn test_reflect_asset_operations() {
         let mut app = App::new();
-        app.add_plugin(AssetPlugin::default())
+        app.add_plugins(AssetPlugin::default())
             .add_asset::<AssetType>()
             .register_asset_reflect::<AssetType>();
 

crates/bevy_audio/src/lib.rs

@@ -7,9 +7,7 @@
 //! # use bevy_app::{App, AppExit, NoopPluginGroup as MinimalPlugins, Startup};
 //! fn main() {
 //!    App::new()
-//!         .add_plugins(MinimalPlugins)
-//!         .add_plugin(AssetPlugin::default())
-//!         .add_plugin(AudioPlugin::default())
+//!         .add_plugins((MinimalPlugins, AssetPlugin::default(), AudioPlugin::default()))
 //!         .add_systems(Startup, play_background_audio)
 //!         .run();
 //! }

crates/bevy_core/src/lib.rs

@@ -165,8 +165,7 @@ mod tests {
     #[test]
     fn runs_spawn_local_tasks() {
         let mut app = App::new();
-        app.add_plugin(TaskPoolPlugin::default());
-        app.add_plugin(TypeRegistrationPlugin::default());
+        app.add_plugins((TaskPoolPlugin::default(), TypeRegistrationPlugin::default()));
 
         let (async_tx, async_rx) = crossbeam_channel::unbounded();
         AsyncComputeTaskPool::get()
@@ -199,9 +198,11 @@ mod tests {
     #[test]
     fn frame_counter_update() {
         let mut app = App::new();
-        app.add_plugin(TaskPoolPlugin::default());
-        app.add_plugin(TypeRegistrationPlugin::default());
-        app.add_plugin(FrameCountPlugin::default());
+        app.add_plugins((
+            TaskPoolPlugin::default(),
+            TypeRegistrationPlugin::default(),
+            FrameCountPlugin::default(),
+        ));
         app.update();
 
         let frame_count = app.world.resource::<FrameCount>();

crates/bevy_core_pipeline/src/bloom/mod.rs

@@ -52,8 +52,10 @@ impl Plugin for BloomPlugin {
         app.register_type::<BloomSettings>();
         app.register_type::<BloomPrefilterSettings>();
         app.register_type::<BloomCompositeMode>();
-        app.add_plugin(ExtractComponentPlugin::<BloomSettings>::default());
-        app.add_plugin(UniformComponentPlugin::<BloomUniforms>::default());
+        app.add_plugins((
+            ExtractComponentPlugin::<BloomSettings>::default(),
+            UniformComponentPlugin::<BloomUniforms>::default(),
+        ));
 
         let render_app = match app.get_sub_app_mut(RenderApp) {
             Ok(render_app) => render_app,

crates/bevy_core_pipeline/src/contrast_adaptive_sharpening/mod.rs

@@ -108,8 +108,10 @@ impl Plugin for CASPlugin {
         );
 
         app.register_type::<ContrastAdaptiveSharpeningSettings>();
-        app.add_plugin(ExtractComponentPlugin::<ContrastAdaptiveSharpeningSettings>::default());
-        app.add_plugin(UniformComponentPlugin::<CASUniform>::default());
+        app.add_plugins((
+            ExtractComponentPlugin::<ContrastAdaptiveSharpeningSettings>::default(),
+            UniformComponentPlugin::<CASUniform>::default(),
+        ));
 
         let render_app = match app.get_sub_app_mut(RenderApp) {
             Ok(render_app) => render_app,

crates/bevy_core_pipeline/src/core_2d/mod.rs

@@ -45,7 +45,7 @@ pub struct Core2dPlugin;
 impl Plugin for Core2dPlugin {
     fn build(&self, app: &mut App) {
         app.register_type::<Camera2d>()
-            .add_plugin(ExtractComponentPlugin::<Camera2d>::default());
+            .add_plugins(ExtractComponentPlugin::<Camera2d>::default());
 
         let render_app = match app.get_sub_app_mut(RenderApp) {
             Ok(render_app) => render_app,

crates/bevy_core_pipeline/src/core_3d/mod.rs

@@ -69,8 +69,7 @@ impl Plugin for Core3dPlugin {
     fn build(&self, app: &mut App) {
         app.register_type::<Camera3d>()
             .register_type::<Camera3dDepthLoadOp>()
-            .add_plugin(SkyboxPlugin)
-            .add_plugin(ExtractComponentPlugin::<Camera3d>::default());
+            .add_plugins((SkyboxPlugin, ExtractComponentPlugin::<Camera3d>::default()));
 
         let render_app = match app.get_sub_app_mut(RenderApp) {
             Ok(render_app) => render_app,

crates/bevy_core_pipeline/src/fxaa/mod.rs

@@ -87,7 +87,7 @@ impl Plugin for FxaaPlugin {
         load_internal_asset!(app, FXAA_SHADER_HANDLE, "fxaa.wgsl", Shader::from_wgsl);
 
         app.register_type::<Fxaa>();
-        app.add_plugin(ExtractComponentPlugin::<Fxaa>::default());
+        app.add_plugins(ExtractComponentPlugin::<Fxaa>::default());
 
         let render_app = match app.get_sub_app_mut(RenderApp) {
             Ok(render_app) => render_app,

crates/bevy_core_pipeline/src/lib.rs

@@ -68,15 +68,17 @@ impl Plugin for CorePipelinePlugin {
             .register_type::<DepthPrepass>()
             .register_type::<NormalPrepass>()
             .init_resource::<ClearColor>()
-            .add_plugin(ExtractResourcePlugin::<ClearColor>::default())
-            .add_plugin(Core2dPlugin)
-            .add_plugin(Core3dPlugin)
-            .add_plugin(BlitPlugin)
-            .add_plugin(MsaaWritebackPlugin)
-            .add_plugin(TonemappingPlugin)
-            .add_plugin(UpscalingPlugin)
-            .add_plugin(BloomPlugin)
-            .add_plugin(FxaaPlugin)
-            .add_plugin(CASPlugin);
+            .add_plugins((
+                ExtractResourcePlugin::<ClearColor>::default(),
+                Core2dPlugin,
+                Core3dPlugin,
+                BlitPlugin,
+                MsaaWritebackPlugin,
+                TonemappingPlugin,
+                UpscalingPlugin,
+                BloomPlugin,
+                FxaaPlugin,
+                CASPlugin,
+            ));
     }
 }

crates/bevy_core_pipeline/src/skybox/mod.rs

@@ -34,7 +34,7 @@ impl Plugin for SkyboxPlugin {
     fn build(&self, app: &mut App) {
         load_internal_asset!(app, SKYBOX_SHADER_HANDLE, "skybox.wgsl", Shader::from_wgsl);
 
-        app.add_plugin(ExtractComponentPlugin::<Skybox>::default());
+        app.add_plugins(ExtractComponentPlugin::<Skybox>::default());
 
         let render_app = match app.get_sub_app_mut(RenderApp) {
             Ok(render_app) => render_app,