diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index a9788252802d5..32007fec29c8b 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -14,7 +14,6 @@ use std::fmt::Debug; #[cfg(feature = "trace")] use bevy_utils::tracing::info_span; - bevy_utils::define_label!(AppLabel); #[allow(clippy::needless_doctest_main)] @@ -22,8 +21,9 @@ bevy_utils::define_label!(AppLabel); /// /// Bundles together the necessary elements, like [`World`] and [`Schedule`], to create /// an ECS-based application. It also stores a pointer to a -/// [runner function](App::set_runner), which by default executes the App schedule -/// once. Apps are constructed with the builder pattern. +/// [runner function](Self::set_runner). The runner is responsible for managing the application's +/// event loop and applying the [`Schedule`] to the [`World`] to drive application logic. +/// Apps are constructed with the builder pattern. /// /// ## Example /// Here is a simple "Hello World" Bevy app: @@ -42,12 +42,22 @@ bevy_utils::define_label!(AppLabel); /// } /// ``` pub struct App { + /// The main ECS [`World`] of the [`App`]. + /// This stores and provides access to all the main data of the application. + /// The systems of the [`App`] will run using this [`World`]. + /// If additional separate [`World`]-[`Schedule`] pairs are needed, you can use [`sub_app`][App::add_sub_app]s. pub world: World, + /// The [runner function](Self::set_runner) is primarily responsible for managing + /// the application's event loop and advancing the [`Schedule`]. + /// Typically, it is not configured manually, but set by one of Bevy's built-in plugins. + /// See `bevy::winit::WinitPlugin` and [`ScheduleRunnerPlugin`](crate::schedule_runner::ScheduleRunnerPlugin). pub runner: Box, + /// A container of [`Stage`]s set to be run in a linear order. pub schedule: Schedule, sub_apps: HashMap, SubApp>, } +/// Each [`SubApp`] has its own [`Schedule`] and [`World`], enabling a separation of concerns. struct SubApp { app: App, runner: Box, @@ -73,10 +83,15 @@ impl Default for App { } impl App { + /// Creates a new [`App`] with some default structure to enable core engine features. + /// This is the preferred constructor for most use cases. pub fn new() -> App { App::default() } + /// Creates a new empty [`App`] with minimal default configuration. + /// + /// This constructor should be used if you wish to provide a custom schedule, exit handling, cleanup, etc. pub fn empty() -> App { Self { world: Default::default(), @@ -837,6 +852,9 @@ impl App { self } + /// Adds a "sub app" to this [`App`]. + /// + /// Sub apps are a largely experimental feature: each `SubApp` has its own [`Schedule`] and [`World`]. pub fn add_sub_app( &mut self, label: impl AppLabel, diff --git a/crates/bevy_app/src/lib.rs b/crates/bevy_app/src/lib.rs index c54d79d90f6ec..a891c5957b786 100644 --- a/crates/bevy_app/src/lib.rs +++ b/crates/bevy_app/src/lib.rs @@ -1,3 +1,4 @@ +#![warn(missing_docs)] //! This crate is about everything concerning the highest-level, application layer of a Bevy //! app. @@ -16,6 +17,7 @@ pub use plugin::*; pub use plugin_group::*; pub use schedule_runner::*; +#[allow(missing_docs)] pub mod prelude { #[doc(hidden)] pub use crate::{app::App, CoreStage, DynamicPlugin, Plugin, PluginGroup, StartupStage}; diff --git a/crates/bevy_app/src/plugin.rs b/crates/bevy_app/src/plugin.rs index c1e791b1e08dd..4f00625fb55a2 100644 --- a/crates/bevy_app/src/plugin.rs +++ b/crates/bevy_app/src/plugin.rs @@ -6,10 +6,14 @@ use std::any::Any; /// Plugins configure an [`App`](crate::App). When an [`App`](crate::App) registers /// a plugin, the plugin's [`Plugin::build`] function is run. pub trait Plugin: Any + Send + Sync { + /// Configures the [`App`] to which this plugin is added. fn build(&self, app: &mut App); + /// Configures a name for the [`Plugin`]. Primarily for debugging. fn name(&self) -> &str { std::any::type_name::() } } +/// Type representing an unsafe function that returns a mutable pointer to a [`Plugin`]. +/// Used for dynamically loading plugins. See bevy_dynamic_plugin/src/loader.rs#dynamically_load_plugin pub type CreatePlugin = unsafe fn() -> *mut dyn Plugin; diff --git a/crates/bevy_app/src/plugin_group.rs b/crates/bevy_app/src/plugin_group.rs index 6bb41483bba89..aecb3dd05acda 100644 --- a/crates/bevy_app/src/plugin_group.rs +++ b/crates/bevy_app/src/plugin_group.rs @@ -2,7 +2,9 @@ use crate::{App, Plugin}; use bevy_utils::{tracing::debug, HashMap}; use std::any::TypeId; +/// Combines multiple [`Plugin`]s into a single unit. pub trait PluginGroup { + /// Configures the [`Plugin`]s that are to be added. fn build(&mut self, group: &mut PluginGroupBuilder); } @@ -11,6 +13,9 @@ struct PluginEntry { enabled: bool, } +/// Facilitates the creation and configuration of a [`PluginGroup`]. +/// Provides a build ordering to ensure that [`Plugin`]s which produce/require a resource +/// are built before/after dependent/depending [`Plugin`]s. #[derive(Default)] pub struct PluginGroupBuilder { plugins: HashMap, @@ -18,6 +23,7 @@ pub struct PluginGroupBuilder { } impl PluginGroupBuilder { + /// Appends a [`Plugin`] to the [`PluginGroupBuilder`]. pub fn add(&mut self, plugin: T) -> &mut Self { self.order.push(TypeId::of::()); self.plugins.insert( @@ -30,6 +36,7 @@ impl PluginGroupBuilder { self } + /// Configures a [`Plugin`] to be built before another plugin. pub fn add_before(&mut self, plugin: T) -> &mut Self { let target_index = self .order @@ -54,6 +61,7 @@ impl PluginGroupBuilder { self } + /// Configures a [`Plugin`] to be built after another plugin. pub fn add_after(&mut self, plugin: T) -> &mut Self { let target_index = self .order @@ -78,6 +86,10 @@ impl PluginGroupBuilder { self } + /// Enables a [`Plugin`] + /// + /// [`Plugin`]s within a [`PluginGroup`] are enabled by default. This function is used to + /// opt back in to a [`Plugin`] after [disabling](Self::disable) it. pub fn enable(&mut self) -> &mut Self { let mut plugin_entry = self .plugins @@ -87,6 +99,7 @@ impl PluginGroupBuilder { self } + /// Disables a [`Plugin`], preventing it from being added to the `App` with the rest of the [`PluginGroup`]. pub fn disable(&mut self) -> &mut Self { let mut plugin_entry = self .plugins @@ -96,6 +109,7 @@ impl PluginGroupBuilder { self } + /// Consumes the [`PluginGroupBuilder`] and [builds](Plugin::build) the contained [`Plugin`]s. pub fn finish(self, app: &mut App) { for ty in self.order.iter() { if let Some(entry) = self.plugins.get(ty) { diff --git a/crates/bevy_app/src/schedule_runner.rs b/crates/bevy_app/src/schedule_runner.rs index 526d4008f0344..3227826f70d06 100644 --- a/crates/bevy_app/src/schedule_runner.rs +++ b/crates/bevy_app/src/schedule_runner.rs @@ -11,10 +11,16 @@ use std::{cell::RefCell, rc::Rc}; #[cfg(target_arch = "wasm32")] use wasm_bindgen::{prelude::*, JsCast}; -/// Determines the method used to run an [App]'s `Schedule` +/// Determines the method used to run an [App]'s [`Schedule`](bevy_ecs::schedule::Schedule). #[derive(Copy, Clone, Debug)] pub enum RunMode { - Loop { wait: Option }, + /// Indicates that the [`App`]'s schedule should run repeatedly. + Loop { + /// Minimum duration to wait after a schedule has completed before repeating. + /// A value of [`None`] will not wait. + wait: Option, + }, + /// Indicates that the [`App`]'s schedule should run only once. Once, } @@ -24,18 +30,22 @@ impl Default for RunMode { } } +/// Configuration information for [`ScheduleRunnerPlugin`]. #[derive(Copy, Clone, Default)] pub struct ScheduleRunnerSettings { + /// Determines whether the [`Schedule`](bevy_ecs::schedule::Schedule) is run once or repeatedly. pub run_mode: RunMode, } impl ScheduleRunnerSettings { + /// [`RunMode::Once`] pub fn run_once() -> Self { ScheduleRunnerSettings { run_mode: RunMode::Once, } } + /// [`RunMode::Loop`] pub fn run_loop(wait_duration: Duration) -> Self { ScheduleRunnerSettings { run_mode: RunMode::Loop { diff --git a/crates/bevy_dynamic_plugin/src/loader.rs b/crates/bevy_dynamic_plugin/src/loader.rs index 20c543944ccc2..6cc33e1bd996b 100644 --- a/crates/bevy_dynamic_plugin/src/loader.rs +++ b/crates/bevy_dynamic_plugin/src/loader.rs @@ -2,7 +2,7 @@ use libloading::{Library, Symbol}; use bevy_app::{App, CreatePlugin, Plugin}; -/// Dynamically links a plugin a the given path. The plugin must export a function with the +/// Dynamically links a plugin at the given path. The plugin must export a function with the /// [`CreatePlugin`] signature named `_bevy_create_plugin`. /// /// # Safety diff --git a/crates/bevy_utils/src/label.rs b/crates/bevy_utils/src/label.rs index ed759f6a59886..7728ef8b947df 100644 --- a/crates/bevy_utils/src/label.rs +++ b/crates/bevy_utils/src/label.rs @@ -58,6 +58,7 @@ where #[macro_export] macro_rules! define_label { ($label_trait_name:ident) => { + /// Defines a set of strongly-typed labels for a class of objects pub trait $label_trait_name: ::bevy_utils::label::DynHash + ::std::fmt::Debug + Send + Sync + 'static { diff --git a/examples/asset/custom_asset_io.rs b/examples/asset/custom_asset_io.rs index b47975e02894b..5ce725d1a592a 100644 --- a/examples/asset/custom_asset_io.rs +++ b/examples/asset/custom_asset_io.rs @@ -80,7 +80,7 @@ fn main() { // `CorePlugin' and `AssetPlugin`. It needs to be after the // CorePlugin, so that the IO task pool has already been constructed. // And it must be before the `AssetPlugin` so that the asset plugin - // doesn't create another instance of an assert server. In general, + // doesn't create another instance of an asset server. In general, // the AssetPlugin should still run so that other aspects of the // asset system are initialized correctly. group.add_before::(CustomAssetIoPlugin)