From 55c84cc7226aac4fab3310b8e8281167f5c7c03b Mon Sep 17 00:00:00 2001 From: Wybe Westra Date: Thu, 19 Sep 2024 18:44:43 +0200 Subject: [PATCH] Added `HeadlessPlugins` (#15203) (#15260) Added a `HeadlessPlugins` plugin group, that adds more default functionality (like logging) than the `MinimumPlugins`. Fixes #15203 Changed the headless example to use the new plugin group. I am not entirely sure if the list of plugins is correct. Are there ones that should be added / removed? ---- The `TerminalCtrlCHandlerPlugin` has interesting effects in the headless example: Installing it a second time it will give a log message about skipping installation, because it is already installed. Ctrl+C will terminate the application in that case. However, _not_ installing it the second time (so only on the app that runs once) has the effect that the app that runs continuously cannot be stopped using Ctrl+C. This implies that, even though the second app did not install the Ctrl+C handler, it did _something_ because it was keeping the one from the first app alive. Not sure if this is a problem or issue, or can be labeled a wierd quirk of having multiple Apps in one executable. --- crates/bevy_dev_tools/src/ci_testing/mod.rs | 5 +- crates/bevy_internal/src/default_plugins.rs | 63 ++++++++++++++++++--- crates/bevy_internal/src/prelude.rs | 3 +- examples/app/headless.rs | 15 +++-- 4 files changed, 71 insertions(+), 15 deletions(-) diff --git a/crates/bevy_dev_tools/src/ci_testing/mod.rs b/crates/bevy_dev_tools/src/ci_testing/mod.rs index d6d5c6d4be..39b9bee6da 100644 --- a/crates/bevy_dev_tools/src/ci_testing/mod.rs +++ b/crates/bevy_dev_tools/src/ci_testing/mod.rs @@ -17,8 +17,9 @@ use std::time::Duration; /// (`ci_testing_config.ron` by default) and executes its specified actions. For a reference of the /// allowed configuration, see [`CiTestingConfig`]. /// -/// This plugin is included within `DefaultPlugins` and `MinimalPlugins` when the `bevy_ci_testing` -/// feature is enabled. It is recommended to only used this plugin during testing (manual or +/// This plugin is included within `DefaultPlugins`, `HeadlessPlugins` and `MinimalPlugins` +/// when the `bevy_ci_testing` feature is enabled. +/// It is recommended to only used this plugin during testing (manual or /// automatic), and disable it during regular development and for production builds. #[derive(Default)] pub struct CiTestingPlugin; diff --git a/crates/bevy_internal/src/default_plugins.rs b/crates/bevy_internal/src/default_plugins.rs index 7aadcb50fb..74008dafaf 100644 --- a/crates/bevy_internal/src/default_plugins.rs +++ b/crates/bevy_internal/src/default_plugins.rs @@ -71,7 +71,56 @@ plugin_group! { /// /// [`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`]. + /// For *headless* cases – without a *window* or presentation, see [`HeadlessPlugins`]. + /// For the absolute minimum number of plugins needed to run a Bevy application, see [`MinimalPlugins`]. +} + +plugin_group! { + /// This plugin group will add all the default plugins for a headless (no *window* or rendering) *Bevy* application: + pub struct HeadlessPlugins { + bevy_app:::PanicHandlerPlugin, + 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_app:::ScheduleRunnerPlugin, + #[custom(cfg(not(target_arch = "wasm32")))] + bevy_app:::TerminalCtrlCHandlerPlugin, + #[cfg(feature = "bevy_asset")] + bevy_asset:::AssetPlugin, + #[cfg(feature = "bevy_scene")] + bevy_scene:::ScenePlugin, + #[cfg(feature = "bevy_animation")] + bevy_animation:::AnimationPlugin, + #[cfg(feature = "bevy_state")] + bevy_state::app:::StatesPlugin, + #[cfg(feature = "bevy_ci_testing")] + bevy_dev_tools::ci_testing:::CiTestingPlugin, + #[doc(hidden)] + :IgnoreAmbiguitiesPlugin, + } + /// This group of plugins is intended for use for *headless* programs, for example: dedicated game servers. + /// See the [*Bevy* *headless* example](https://github.com/bevyengine/bevy/blob/main/examples/app/headless.rs) + /// + /// [`HeadlessPlugins`] 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. + /// + /// [`HeadlessPlugins`] contains all the plugins typically required to build + /// a *Bevy* application. In contrast with [`DefaultPlugins`], it leaves out *window* and presentation components. + /// This allows applications built using this plugin group to run on devices that do not have a screen or rendering + /// capabilities. + /// It 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. + /// For the absolute minimum number of plugins needed to run a Bevy application, see [`MinimalPlugins`]. } #[derive(Default)] @@ -110,12 +159,12 @@ plugin_group! { #[cfg(feature = "bevy_ci_testing")] bevy_dev_tools::ci_testing:::CiTestingPlugin, } - /// 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) + /// This plugin group represents the absolute minimum, bare-bones, bevy application. + /// Use this if you want to have absolute control over the plugins used. + /// If you are looking to make a *headless* application - without a *window* or rendering, + /// it is usually best to use [`HeadlessPlugins`]. + /// + /// It 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. } diff --git a/crates/bevy_internal/src/prelude.rs b/crates/bevy_internal/src/prelude.rs index 812a674ed9..bec80694fd 100644 --- a/crates/bevy_internal/src/prelude.rs +++ b/crates/bevy_internal/src/prelude.rs @@ -2,7 +2,8 @@ pub use crate::{ app::prelude::*, core::prelude::*, ecs::prelude::*, hierarchy::prelude::*, input::prelude::*, log::prelude::*, math::prelude::*, reflect::prelude::*, time::prelude::*, - transform::prelude::*, utils::prelude::*, window::prelude::*, DefaultPlugins, MinimalPlugins, + transform::prelude::*, utils::prelude::*, window::prelude::*, DefaultPlugins, HeadlessPlugins, + MinimalPlugins, }; pub use bevy_derive::{bevy_main, Deref, DerefMut}; diff --git a/examples/app/headless.rs b/examples/app/headless.rs index 329a28bf6e..c6ee157b37 100644 --- a/examples/app/headless.rs +++ b/examples/app/headless.rs @@ -8,21 +8,26 @@ //! # replace "*" with the most recent version of bevy //! ``` -use bevy::{app::ScheduleRunnerPlugin, prelude::*, utils::Duration}; +use bevy::{app::ScheduleRunnerPlugin, log::LogPlugin, prelude::*, utils::Duration}; fn main() { // This app runs once App::new() - .add_plugins(MinimalPlugins.set(ScheduleRunnerPlugin::run_once())) + .add_plugins(HeadlessPlugins.set(ScheduleRunnerPlugin::run_once())) .add_systems(Update, hello_world_system) .run(); // This app loops forever at 60 fps App::new() .add_plugins( - MinimalPlugins.set(ScheduleRunnerPlugin::run_loop(Duration::from_secs_f64( - 1.0 / 60.0, - ))), + HeadlessPlugins + .set(ScheduleRunnerPlugin::run_loop(Duration::from_secs_f64( + 1.0 / 60.0, + ))) + // The log and ctrl+c plugin can only be registered once globally, + // which means we need to disable it here, because it was already registered with the + // app that runs once. + .disable::(), ) .add_systems(Update, counter) .run();