plugin_group! macro

crates/bevy_a11y/src/lib.rs

@@ -98,6 +98,7 @@ pub enum AccessibilitySystem {
 }
 
 /// Plugin managing non-GUI aspects of integrating with accessibility APIs.
+#[derive(Default)]
 pub struct AccessibilityPlugin;
 
 impl Plugin for AccessibilityPlugin {

crates/bevy_app/src/plugin_group.rs

@@ -2,6 +2,123 @@ use crate::{App, AppError, Plugin};
 use bevy_utils::{tracing::debug, tracing::warn, TypeIdMap};
 use std::any::TypeId;
 
+/// A macro for generating a well-documented [`PluginGroup`] from a list of [`Plugin`] paths.
+///
+/// Every plugin must implement the [`Default`] trait.
+///
+/// # Example
+///
+/// ```
+/// # use bevy_app::*;
+/// # mod velocity {
+/// #   use bevy_app::*;
+/// #   #[derive(Default)] pub struct VelocityPlugin;
+/// #   impl Plugin for VelocityPlugin { fn build(&self, _: &mut App) {} }
+/// # }
+/// # mod collision { pub mod capsule {
+/// #   use bevy_app::*;
+/// #   #[derive(Default)] pub struct CapsuleCollisionPlugin;
+/// #   impl Plugin for CapsuleCollisionPlugin { fn build(&self, _: &mut App) {} }
+/// # } }
+/// # #[derive(Default)] pub struct TickratePlugin;
+/// # impl Plugin for TickratePlugin { fn build(&self, _: &mut App) {} }
+/// # mod features {
+/// #   use bevy_app::*;
+/// #   #[derive(Default)] pub struct ForcePlugin;
+/// #   impl Plugin for ForcePlugin { fn build(&self, _: &mut App) {} }
+/// # }
+/// # mod web {
+/// #   use bevy_app::*;
+/// #   #[derive(Default)] pub struct WebCompatibilityPlugin;
+/// #   impl Plugin for WebCompatibilityPlugin { fn build(&self, _: &mut App) {} }
+/// # }
+/// # mod internal {
+/// #   use bevy_app::*;
+/// #   #[derive(Default)] pub struct InternalPlugin;
+/// #   impl Plugin for InternalPlugin { fn build(&self, _: &mut App) {} }
+/// # }
+/// plugin_group!(
+///     PhysicsPlugins {
+///         // Due to local ambiguity issues, you have to
+///         // use a colon before the plugin's name.
+///         :TickratePlugin,
+///         // Due to local ambiguity issues, you have to
+///         // use 3 colons for the last part of the path.
+///         collision::capsule:::CapsuleCollisionPlugin,
+///         velocity:::VelocityPlugin,
+///         // Add a documented feature restriction.
+///         #[cfg(feature = "external_forces")]
+///         features:::ForcePlugin,
+///         // You can add any attribute you want like this, but it won't be documented.
+///         #[custom(cfg(target_arch = "wasm32"))]
+///         web:::WebCompatibilityPlugin,
+///         // You can hide plugins from documentation.
+///         // NOTE: Due to macro limitations, you can only use
+///         //       #[doc(hidden)] for plugins at the bottom of the macro.
+///         #[doc(hidden)]
+///         internal:::InternalPlugin
+///     }
+/// );
+/// ```
+#[macro_export]
+macro_rules! plugin_group {
+    (
+        $(#[$group_meta:meta])*
+        $group:ident {
+            $(
+                $(#[cfg(feature = $plugin_feature:literal)])?
+                $(#[custom($plugin_meta:meta)])*
+                $($plugin_path:ident::)* : $plugin_name:ident
+            ),*
+            $(
+                ,$(
+                    #[doc(hidden)]
+                    $(#[cfg(feature = $hidden_plugin_feature:literal)])?
+                    $(#[custom($hidden_plugin_meta:meta)])*
+                    $($hidden_plugin_path:ident::)* : $hidden_plugin_name:ident
+                ),+
+            )?
+
+            $(,)?
+        }
+        $($(#[doc = $post_doc:literal])+)?
+    ) => {
+        $(#[$group_meta])*
+        ///
+        $(#[doc = concat!(
+            "* [`", stringify!($plugin_name), "`](" $(, stringify!($plugin_path), "::")*, stringify!($plugin_name), ")"
+            $(, " - with feature `", $plugin_feature, "`")?
+        )])*
+        $(
+            ///
+            $(#[doc = $post_doc])+
+        )?
+        pub struct $group;
+        impl PluginGroup for $group {
+            fn build(self) -> PluginGroupBuilder {
+                let mut group = PluginGroupBuilder::start::<Self>();
+
+                $(
+                    $(#[cfg(feature = $plugin_feature)])?
+                    $(#[$plugin_meta])*
+                    {
+                        group = group.add(<$($plugin_path::)*$plugin_name>::default());
+                    }
+                )*
+                $($(
+                    $(#[cfg(feature = $hidden_plugin_feature)])?
+                    $(#[$hidden_plugin_meta])*
+                    {
+                        group = group.add(<$($hidden_plugin_path::)*$hidden_plugin_name>::default());
+                    }
+                )+)?
+
+                group
+            }
+        }
+    };
+}
+
 /// Combines multiple [`Plugin`]s into a single unit.
 pub trait PluginGroup: Sized {
     /// Configures the [`Plugin`]s that are to be added.

crates/bevy_gizmos/src/lib.rs

@@ -87,6 +87,7 @@ use std::{any::TypeId, mem};
 const LINE_SHADER_HANDLE: Handle<Shader> = Handle::weak_from_u128(7414812689238026784);
 
 /// A [`Plugin`] that provides an immediate mode drawing api for visual debugging.
+#[derive(Default)]
 pub struct GizmoPlugin;
 
 impl Plugin for GizmoPlugin {

crates/bevy_internal/src/default_plugins.rs

@@ -1,145 +1,70 @@
-use bevy_app::{Plugin, PluginGroup, PluginGroupBuilder};
-
-/// This plugin group will add all the default plugins for a *Bevy* application:
-/// * [`LogPlugin`](crate::log::LogPlugin)
-/// * [`TaskPoolPlugin`](crate::core::TaskPoolPlugin)
-/// * [`TypeRegistrationPlugin`](crate::core::TypeRegistrationPlugin)
-/// * [`FrameCountPlugin`](crate::core::FrameCountPlugin)
-/// * [`TimePlugin`](crate::time::TimePlugin)
-/// * [`TransformPlugin`](crate::transform::TransformPlugin)
-/// * [`HierarchyPlugin`](crate::hierarchy::HierarchyPlugin)
-/// * [`DiagnosticsPlugin`](crate::diagnostic::DiagnosticsPlugin)
-/// * [`InputPlugin`](crate::input::InputPlugin)
-/// * [`WindowPlugin`](crate::window::WindowPlugin)
-/// * [`AccessibilityPlugin`](crate::a11y::AccessibilityPlugin)
-/// * [`AssetPlugin`](crate::asset::AssetPlugin) - with feature `bevy_asset`
-/// * [`ScenePlugin`](crate::scene::ScenePlugin) - with feature `bevy_scene`
-/// * [`WinitPlugin`](crate::winit::WinitPlugin) - with feature `bevy_winit`
-/// * [`RenderPlugin`](crate::render::RenderPlugin) - with feature `bevy_render`
-/// * [`ImagePlugin`](crate::render::texture::ImagePlugin) - with feature `bevy_render`
-/// * [`PipelinedRenderingPlugin`](crate::render::pipelined_rendering::PipelinedRenderingPlugin) - with feature `bevy_render` when not targeting `wasm32`
-/// * [`CorePipelinePlugin`](crate::core_pipeline::CorePipelinePlugin) - with feature `bevy_core_pipeline`
-/// * [`SpritePlugin`](crate::sprite::SpritePlugin) - with feature `bevy_sprite`
-/// * [`TextPlugin`](crate::text::TextPlugin) - with feature `bevy_text`
-/// * [`UiPlugin`](crate::ui::UiPlugin) - with feature `bevy_ui`
-/// * [`PbrPlugin`](crate::pbr::PbrPlugin) - with feature `bevy_pbr`
-/// * [`GltfPlugin`](crate::gltf::GltfPlugin) - with feature `bevy_gltf`
-/// * [`AudioPlugin`](crate::audio::AudioPlugin) - with feature `bevy_audio`
-/// * [`GilrsPlugin`](crate::gilrs::GilrsPlugin) - with feature `bevy_gilrs`
-/// * [`AnimationPlugin`](crate::animation::AnimationPlugin) - with feature `bevy_animation`
-///
-/// [`DefaultPlugins`] obeys *Cargo* *feature* flags. Users may exert control over this plugin group
-/// by disabling `default-features` in their `Cargo.toml` and enabling only those features
-/// that they wish to use.
-///
-/// [`DefaultPlugins`] contains all the plugins typically required to build
-/// a *Bevy* application which includes a *window* and presentation components.
-/// For *headless* cases – without a *window* or presentation, see [`MinimalPlugins`].
-pub struct DefaultPlugins;
-
-impl PluginGroup for DefaultPlugins {
-    fn build(self) -> PluginGroupBuilder {
-        let mut group = PluginGroupBuilder::start::<Self>();
-        group = group
-            .add(bevy_log::LogPlugin::default())
-            .add(bevy_core::TaskPoolPlugin::default())
-            .add(bevy_core::TypeRegistrationPlugin)
-            .add(bevy_core::FrameCountPlugin)
-            .add(bevy_time::TimePlugin)
-            .add(bevy_transform::TransformPlugin)
-            .add(bevy_hierarchy::HierarchyPlugin)
-            .add(bevy_diagnostic::DiagnosticsPlugin)
-            .add(bevy_input::InputPlugin)
-            .add(bevy_window::WindowPlugin::default())
-            .add(bevy_a11y::AccessibilityPlugin);
-
+#![allow(dead_code)]
+use bevy_app::{plugin_group, Plugin, PluginGroup, PluginGroupBuilder};
+
+plugin_group!(
+    /// This plugin group will add all the default plugins for a *Bevy* application:
+    DefaultPlugins {
+        bevy_log:::LogPlugin,
+        bevy_core:::TaskPoolPlugin,
+        bevy_core:::TypeRegistrationPlugin,
+        bevy_core:::FrameCountPlugin,
+        bevy_time:::TimePlugin,
+        bevy_transform:::TransformPlugin,
+        bevy_hierarchy:::HierarchyPlugin,
+        bevy_diagnostic:::DiagnosticsPlugin,
+        bevy_input:::InputPlugin,
+        bevy_window:::WindowPlugin,
+        bevy_a11y:::AccessibilityPlugin,
         #[cfg(feature = "bevy_asset")]
-        {
-            group = group.add(bevy_asset::AssetPlugin::default());
-        }
-
+        bevy_asset:::AssetPlugin,
         #[cfg(feature = "bevy_scene")]
-        {
-            group = group.add(bevy_scene::ScenePlugin);
-        }
-
+        bevy_scene:::ScenePlugin,
         #[cfg(feature = "bevy_winit")]
-        {
-            group = group.add(bevy_winit::WinitPlugin::default());
-        }
-
+        bevy_winit:::WinitPlugin,
         #[cfg(feature = "bevy_render")]
-        {
-            group = group
-                .add(bevy_render::RenderPlugin::default())
-                // NOTE: Load this after renderer initialization so that it knows about the supported
-                // compressed texture formats
-                .add(bevy_render::texture::ImagePlugin::default());
-
-            #[cfg(all(not(target_arch = "wasm32"), feature = "multi-threaded"))]
-            {
-                group = group.add(bevy_render::pipelined_rendering::PipelinedRenderingPlugin);
-            }
-        }
-
+        bevy_render:::RenderPlugin,
+        // NOTE: Load this after renderer initialization so that it knows about the supported
+        // compressed texture formats
+        #[cfg(feature = "bevy_render")]
+        bevy_render::texture:::ImagePlugin,
+        #[cfg(feature = "bevy_render")]
+        #[custom(cfg(all(not(target_arch = "wasm32"), feature = "multi-threaded")))]
+        bevy_render::pipelined_rendering:::PipelinedRenderingPlugin,
         #[cfg(feature = "bevy_core_pipeline")]
-        {
-            group = group.add(bevy_core_pipeline::CorePipelinePlugin);
-        }
-
+        bevy_core_pipeline:::CorePipelinePlugin,
         #[cfg(feature = "bevy_sprite")]
-        {
-            group = group.add(bevy_sprite::SpritePlugin);
-        }
-
+        bevy_sprite:::SpritePlugin,
         #[cfg(feature = "bevy_text")]
-        {
-            group = group.add(bevy_text::TextPlugin);
-        }
-
+        bevy_text:::TextPlugin,
         #[cfg(feature = "bevy_ui")]
-        {
-            group = group.add(bevy_ui::UiPlugin);
-        }
-
-        #[cfg(feature = "bevy_pbr")]
-        {
-            group = group.add(bevy_pbr::PbrPlugin::default());
-        }
-
+        bevy_ui:::UiPlugin,
         // NOTE: Load this after renderer initialization so that it knows about the supported
         // compressed texture formats
+        #[cfg(feature = "bevy_pbr")]
+        bevy_pbr:::PbrPlugin,
         #[cfg(feature = "bevy_gltf")]
-        {
-            group = group.add(bevy_gltf::GltfPlugin::default());
-        }
-
+        bevy_gltf:::GltfPlugin,
         #[cfg(feature = "bevy_audio")]
-        {
-            group = group.add(bevy_audio::AudioPlugin::default());
-        }
-
+        bevy_audio:::AudioPlugin,
         #[cfg(feature = "bevy_gilrs")]
-        {
-            group = group.add(bevy_gilrs::GilrsPlugin);
-        }
-
+        bevy_gilrs:::GilrsPlugin,
         #[cfg(feature = "bevy_animation")]
-        {
-            group = group.add(bevy_animation::AnimationPlugin);
-        }
-
+        bevy_animation:::AnimationPlugin,
         #[cfg(feature = "bevy_gizmos")]
-        {
-            group = group.add(bevy_gizmos::GizmoPlugin);
-        }
-
-        group = group.add(IgnoreAmbiguitiesPlugin);
-
-        group
+        bevy_gizmos:::GizmoPlugin,
+        #[doc(hidden)]
+        :IgnoreAmbiguitiesPlugin,
     }
-}
-
+    /// [`DefaultPlugins`] obeys *Cargo feature* flags. Users may exert control over this plugin group
+    /// by disabling `default-features` in their `Cargo.toml` and enabling only those features
+    /// that they wish to use.
+    ///
+    /// [`DefaultPlugins`] contains all the plugins typically required to build
+    /// a *Bevy* application which includes a *window* and presentation components.
+    /// For *headless* cases – without a *window* or presentation, see [`MinimalPlugins`].
+);
+
+#[derive(Default)]
 struct IgnoreAmbiguitiesPlugin;
 
 impl Plugin for IgnoreAmbiguitiesPlugin {
@@ -180,30 +105,21 @@ impl Plugin for IgnoreAmbiguitiesPlugin {
     }
 }
 
-/// This plugin group will add the minimal plugins for a *Bevy* application:
-/// * [`TaskPoolPlugin`](crate::core::TaskPoolPlugin)
-/// * [`TypeRegistrationPlugin`](crate::core::TypeRegistrationPlugin)
-/// * [`FrameCountPlugin`](crate::core::FrameCountPlugin)
-/// * [`TimePlugin`](crate::time::TimePlugin)
-/// * [`ScheduleRunnerPlugin`](crate::app::ScheduleRunnerPlugin)
-///
-/// This group of plugins is intended for use for minimal, *headless* programs –
-/// see the [*Bevy* *headless* example](https://github.com/bevyengine/bevy/blob/main/examples/app/headless.rs)
-/// – and includes a [schedule runner (`ScheduleRunnerPlugin`)](crate::app::ScheduleRunnerPlugin)
-/// to provide functionality that would otherwise be driven by a windowed application's
-/// *event loop* or *message loop*.
-///
-/// Windowed applications that wish to use a reduced set of plugins should consider the
-/// [`DefaultPlugins`] plugin group which can be controlled with *Cargo* *feature* flags.
-pub struct MinimalPlugins;
-
-impl PluginGroup for MinimalPlugins {
-    fn build(self) -> PluginGroupBuilder {
-        PluginGroupBuilder::start::<Self>()
-            .add(bevy_core::TaskPoolPlugin::default())
-            .add(bevy_core::TypeRegistrationPlugin)
-            .add(bevy_core::FrameCountPlugin)
-            .add(bevy_time::TimePlugin)
-            .add(bevy_app::ScheduleRunnerPlugin::default())
+plugin_group!(
+    /// This plugin group will add the minimal plugins for a *Bevy* application:
+    MinimalPlugins {
+        bevy_core:::TaskPoolPlugin,
+        bevy_core:::TypeRegistrationPlugin,
+        bevy_core:::FrameCountPlugin,
+        bevy_time:::TimePlugin,
+        bevy_app:::ScheduleRunnerPlugin,
     }
-}
+    /// This group of plugins is intended for use for minimal, *headless* programs –
+    /// see the [*Bevy* *headless* example](https://github.com/bevyengine/bevy/blob/main/examples/app/headless.rs)
+    /// – and includes a [schedule runner (`ScheduleRunnerPlugin`)](crate::app::ScheduleRunnerPlugin)
+    /// to provide functionality that would otherwise be driven by a windowed application's
+    /// *event loop* or *message loop*.
+    ///
+    /// Windowed applications that wish to use a reduced set of plugins should consider the
+    /// [`DefaultPlugins`] plugin group which can be controlled with *Cargo* *feature* flags.
+);