Merge remote-tracking branch 'origin/main' into stage-yeet

Cargo.toml

@@ -48,7 +48,7 @@ default = [
 ]
 
 # Force dynamic linking, which improves iterative compile times
-dynamic = ["bevy_dylib", "bevy_internal/dynamic"]
+dynamic_linking = ["bevy_dylib", "bevy_internal/dynamic_linking"]
 
 # Optional bevy crates
 bevy_animation = ["bevy_internal/bevy_animation"]

crates/bevy_app/src/app.rs

@@ -1069,7 +1069,11 @@ fn run_once(mut app: App) {
 ///
 /// You can also use this event to detect that an exit was requested. In order to receive it, systems
 /// subscribing to this event should run after it was emitted and before the schedule of the same
-/// frame is over.
+/// frame is over. This is important since [`App::run()`] might never return.
+///
+/// If you don't require access to other components or resources, consider implementing the [`Drop`]
+/// trait on components/resources for code that runs on exit. That saves you from worrying about
+/// system schedule ordering, and is idiomatic Rust.
 #[derive(Debug, Clone, Default)]
 pub struct AppExit;
 

crates/bevy_app/src/schedule_runner.rs

@@ -61,6 +61,16 @@ impl ScheduleRunnerSettings {
 
 /// Configures an [`App`] to run its [`Schedule`](bevy_ecs::schedule::Schedule) according to a given
 /// [`RunMode`].
+///
+/// [`ScheduleRunnerPlugin`] is included in the
+/// [`MinimalPlugins`](https://docs.rs/bevy/latest/bevy/struct.MinimalPlugins.html) plugin group.
+///
+/// [`ScheduleRunnerPlugin`] is *not* included in the
+/// [`DefaultPlugins`](https://docs.rs/bevy/latest/bevy/struct.DefaultPlugins.html) plugin group
+/// which assumes that the [`Schedule`](bevy_ecs::schedule::Schedule) will be executed by other means:
+/// typically, the `winit` event loop
+/// (see [`WinitPlugin`](https://docs.rs/bevy/latest/bevy/winit/struct.WinitPlugin.html))
+/// executes the schedule making [`ScheduleRunnerPlugin`] unnecessary.
 #[derive(Default)]
 pub struct ScheduleRunnerPlugin;
 

crates/bevy_diagnostic/Cargo.toml

@@ -10,7 +10,7 @@ keywords = ["bevy"]
 
 [features]
 # Disables diagnostics that are unsupported when Bevy is dynamically linked
-dynamic = []
+dynamic_linking = []
 
 [dependencies]
 # bevy

crates/bevy_diagnostic/src/system_information_diagnostics_plugin.rs

@@ -34,7 +34,7 @@ impl SystemInformationDiagnosticsPlugin {
         target_os = "android",
         target_os = "macos"
     ),
-    not(feature = "dynamic")
+    not(feature = "dynamic_linking")
 ))]
 pub mod internal {
     use bevy_ecs::{prelude::ResMut, system::Local};
@@ -142,7 +142,7 @@ pub mod internal {
         target_os = "android",
         target_os = "macos"
     ),
-    not(feature = "dynamic")
+    not(feature = "dynamic_linking")
 )))]
 pub mod internal {
     pub(crate) fn setup_system() {

crates/bevy_dylib/src/lib.rs

@@ -15,21 +15,21 @@
 //!
 //! ## The recommended way
 //!
-//! The easiest way to enable dynamic linking is to use the `--features bevy/dynamic` flag when
+//! The easiest way to enable dynamic linking is to use the `--features bevy/dynamic_linking` flag when
 //! using the `cargo run` command:
 //!
-//! `cargo run --features bevy/dynamic`
+//! `cargo run --features bevy/dynamic_linking`
 //!
 //! ## The unrecommended way
 //!
-//! It is also possible to enable the `dynamic` feature inside of the `Cargo.toml` file. This is
+//! It is also possible to enable the `dynamic_linking` feature inside of the `Cargo.toml` file. This is
 //! unrecommended because it requires you to remove this feature every time you want to create a
 //! release build to avoid having to ship additional files with your game.
 //!
-//! To enable dynamic linking inside of the `Cargo.toml` file add the `dynamic` feature to the
+//! To enable dynamic linking inside of the `Cargo.toml` file add the `dynamic_linking` feature to the
 //! bevy dependency:
 //!
-//! `features = ["dynamic"]`
+//! `features = ["dynamic_linking"]`
 //!
 //! ## The manual way
 //!

crates/bevy_ecs/src/system/system_param.rs

@@ -1480,7 +1480,7 @@ mod tests {
         system::Query,
     };
 
-    // Compile test for #2838
+    // Compile test for https://github.com/bevyengine/bevy/pull/2838.
     #[derive(SystemParam)]
     pub struct SpecialQuery<
         'w,
@@ -1491,6 +1491,8 @@ mod tests {
         _query: Query<'w, 's, Q, F>,
     }
 
+    // Compile tests for https://github.com/bevyengine/bevy/pull/6694.
+
     #[derive(SystemParam)]
     pub struct SpecialRes<'w, T: Resource> {
         _res: Res<'w, T>,
@@ -1504,9 +1506,11 @@ mod tests {
     #[derive(Resource)]
     pub struct R<const I: usize>;
 
+    // Compile test for https://github.com/bevyengine/bevy/pull/7001.
     #[derive(SystemParam)]
     pub struct ConstGenericParam<'w, const I: usize>(Res<'w, R<I>>);
 
+    // Compile test for https://github.com/bevyengine/bevy/pull/6867.
     #[derive(SystemParam)]
     pub struct LongParam<'w> {
         _r0: Res<'w, R<0>>,
@@ -1533,13 +1537,16 @@ mod tests {
         crate::system::assert_is_system(long_system);
     }
 
+    // Compile test for https://github.com/bevyengine/bevy/pull/6919.
     #[derive(SystemParam)]
     struct MyParam<'w, T: Resource, Marker: 'static> {
         _foo: Res<'w, T>,
         #[system_param(ignore)]
         marker: PhantomData<Marker>,
     }
 
+    // Compile tests for https://github.com/bevyengine/bevy/pull/6957.
+
     #[derive(SystemParam)]
     pub struct UnitParam;
 
@@ -1552,6 +1559,7 @@ mod tests {
     #[derive(Resource)]
     struct PrivateResource;
 
+    // Regression test for https://github.com/bevyengine/bevy/issues/4200.
     #[derive(SystemParam)]
     pub struct EncapsulatedParam<'w>(Res<'w, PrivateResource>);
 

crates/bevy_internal/Cargo.toml

@@ -2,7 +2,7 @@
 name = "bevy_internal"
 version = "0.9.0"
 edition = "2021"
-description = "An internal Bevy crate used to facilitate optional dynamic linking via the 'dynamic' feature"
+description = "An internal Bevy crate used to facilitate optional dynamic linking via the 'dynamic_linking' feature"
 homepage = "https://bevyengine.org"
 repository = "https://github.com/bevyengine/bevy"
 license = "MIT OR Apache-2.0"
@@ -72,7 +72,7 @@ bevy_ci_testing = ["bevy_app/bevy_ci_testing", "bevy_render/ci_limits"]
 animation = ["bevy_animation", "bevy_gltf?/bevy_animation"]
 
 # Used to disable code that is unsupported when Bevy is dynamically linked
-dynamic = ["bevy_diagnostic/dynamic"]
+dynamic_linking = ["bevy_diagnostic/dynamic_linking"]
 
 [dependencies]
 # bevy

crates/bevy_internal/src/default_plugins.rs

@@ -1,6 +1,6 @@
 use bevy_app::{PluginGroup, PluginGroupBuilder};
 
-/// This plugin group will add all the default plugins:
+/// 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)
@@ -23,7 +23,13 @@ use bevy_app::{PluginGroup, PluginGroupBuilder};
 /// * [`GltfPlugin`](crate::gltf::GltfPlugin) - with feature `bevy_gltf`
 /// * [`WinitPlugin`](crate::winit::WinitPlugin) - with feature `bevy_winit`
 ///
-/// See also [`MinimalPlugins`] for a slimmed down option
+/// [`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 {
@@ -127,14 +133,21 @@ impl PluginGroup for DefaultPlugins {
     }
 }
 
-/// Minimal plugin group that will add the following plugins:
+/// 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)
 ///
-/// See also [`DefaultPlugins`] for a more complete set of plugins
+/// 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 {

docs/cargo_features.md

@@ -23,7 +23,7 @@
 |feature name|description|
 |-|-|
 |bevy_dynamic_plugin|Plugin for dynamic loading (using [libloading](https://crates.io/crates/libloading)).|
-|dynamic|Forces bevy to be dynamically linked, which improves iterative compile times.|
+|dynamic_linking|Forces bevy to be dynamically linked, which improves iterative compile times.|
 |trace|Enables system tracing.|
 |trace_chrome|Enables [tracing-chrome](https://github.com/thoren-d/tracing-chrome) as bevy_log output. This allows you to visualize system execution.|
 |trace_tracy|Enables [Tracy](https://github.com/wolfpld/tracy) as bevy_log output. This allows `Tracy` to connect to and capture profiling data as well as visualize system execution in real-time, present statistics about system execution times, and more.|

examples/stress_tests/many_foxes.rs

@@ -160,7 +160,7 @@ fn setup(
 
     // Plane
     commands.spawn(PbrBundle {
-        mesh: meshes.add(Mesh::from(shape::Plane { size: 500000.0 })),
+        mesh: meshes.add(Mesh::from(shape::Plane { size: 5000.0 })),
         material: materials.add(Color::rgb(0.3, 0.5, 0.3).into()),
         ..default()
     });

src/lib.rs

@@ -45,6 +45,6 @@
 
 pub use bevy_internal::*;
 
-#[cfg(feature = "dynamic")]
+#[cfg(feature = "dynamic_linking")]
 #[allow(unused_imports)]
 use bevy_dylib;