diff --git a/crates/bevy_app/src/app_builder.rs b/crates/bevy_app/src/app_builder.rs index 954e87ade6..fe7b5fb3d7 100644 --- a/crates/bevy_app/src/app_builder.rs +++ b/crates/bevy_app/src/app_builder.rs @@ -207,6 +207,10 @@ impl AppBuilder { .add_stage(CoreStage::Last, SystemStage::parallel()) } + /// Setup the application to manage events of type `T`. + /// + /// This is done by adding a `Resource` of type `Events::`, + /// and inserting a `Events::::update_system` system into `CoreStage::First`. pub fn add_event(&mut self) -> &mut Self where T: Component, diff --git a/crates/bevy_app/src/event.rs b/crates/bevy_app/src/event.rs index 03dcf530f5..63e8cfcfba 100644 --- a/crates/bevy_app/src/event.rs +++ b/crates/bevy_app/src/event.rs @@ -56,11 +56,23 @@ enum State { } /// An event collection that represents the events that occurred within the last two -/// [Events::update] calls. Events can be cheaply read using an [EventReader]. This collection is -/// meant to be paired with a system that calls [Events::update] exactly once per update/frame. -/// [Events::update_system] is a system that does this. [EventReader]s are expected to read events -/// from this collection at least once per update/frame. If events are not handled within one -/// frame/update, they will be dropped. +/// [`Events::update`] calls. +/// Events can be written to using an [`EventWriter`] +/// and are typically cheaply read using an [`EventReader`]. +/// +/// Each event can be consumed by multiple systems, in parallel, +/// with consumption tracked by the [`EventReader`] on a per-system basis. +/// +/// This collection is meant to be paired with a system that calls +/// [`Events::update`] exactly once per update/frame. +/// +/// [`Events::update_system`] is a system that does this, typically intialized automatically using +/// [`AppBuilder::add_event`]. [EventReader]s are expected to read events from this collection at +/// least once per loop/frame. +/// Events will persist across a single frame boundary and so ordering of event producers and +/// consumers is not critical (although poorly-planned ordering may cause accumulating lag). +/// If events are not handled by the end of the frame after they are updated, they will be +/// dropped silently. /// /// # Example /// ``` @@ -100,7 +112,9 @@ enum State { /// The buffers in [Events] will grow indefinitely if [Events::update] is never called. /// /// An alternative call pattern would be to call [Events::update] manually across frames to control -/// when events are cleared. However this complicates consumption +/// when events are cleared. +/// This complicates consumption and risks ever-expanding memory usage if not cleaned up, +/// but can be done by adding your event as a resource instead of using [`AppBuilder::add_event`]. #[derive(Debug)] pub struct Events { events_a: Vec>, diff --git a/crates/bevy_ecs/src/schedule/stage.rs b/crates/bevy_ecs/src/schedule/stage.rs index 2970c8050e..bdc37a1f95 100644 --- a/crates/bevy_ecs/src/schedule/stage.rs +++ b/crates/bevy_ecs/src/schedule/stage.rs @@ -173,18 +173,21 @@ impl SystemStage { pub fn parallel_systems(&self) -> &[impl SystemContainer] { &self.parallel } + /// Topologically sorted exclusive systems that want to be run at the start of the stage. /// /// Note that systems won't be fully-formed until the stage has been run at least once. pub fn exclusive_at_start_systems(&self) -> &[impl SystemContainer] { &self.exclusive_at_start } + /// Topologically sorted exclusive systems that want to be run at the end of the stage. /// /// Note that systems won't be fully-formed until the stage has been run at least once. pub fn exclusive_at_end_systems(&self) -> &[impl SystemContainer] { &self.exclusive_at_end } + /// Topologically sorted exclusive systems that want to be run after parallel systems but /// before the application of their command buffers. /// diff --git a/crates/bevy_ecs/src/schedule/state.rs b/crates/bevy_ecs/src/schedule/state.rs index 2622aafc95..4d959c4fb2 100644 --- a/crates/bevy_ecs/src/schedule/state.rs +++ b/crates/bevy_ecs/src/schedule/state.rs @@ -188,7 +188,8 @@ impl State { /// Creates a driver set for the State. /// - /// Important note: this set must be inserted **before** all other state-dependant sets to work properly! + /// Important note: this set must be inserted **before** all other state-dependant sets to work + /// properly! pub fn make_driver() -> SystemSet { SystemSet::default().with_run_criteria(state_cleaner::.system()) } @@ -203,7 +204,8 @@ impl State { } /// Schedule a state change that replaces the full stack with the given state. - /// This will fail if there is a scheduled operation, or if the given `state` matches the current state + /// This will fail if there is a scheduled operation, or if the given `state` matches the + /// current state pub fn set_next(&mut self, state: T) -> Result<(), StateError> { if self.stack.last().unwrap() == &state { return Err(StateError::AlreadyInState); @@ -217,7 +219,8 @@ impl State { Ok(()) } - /// Same as [Self::set_next], but if there is already a next state, it will be overwritten instead of failing + /// Same as [Self::set_next], but if there is already a next state, it will be overwritten + /// instead of failing pub fn overwrite_next(&mut self, state: T) -> Result<(), StateError> { if self.stack.last().unwrap() == &state { return Err(StateError::AlreadyInState); @@ -241,7 +244,8 @@ impl State { Ok(()) } - /// Same as [Self::set_push], but if there is already a next state, it will be overwritten instead of failing + /// Same as [Self::set_push], but if there is already a next state, it will be overwritten + /// instead of failing pub fn overwrite_push(&mut self, state: T) -> Result<(), StateError> { if self.stack.last().unwrap() == &state { return Err(StateError::AlreadyInState); @@ -265,7 +269,8 @@ impl State { Ok(()) } - /// Same as [Self::set_pop], but if there is already a next state, it will be overwritten instead of failing + /// Same as [Self::set_pop], but if there is already a next state, it will be overwritten + /// instead of failing pub fn overwrite_pop(&mut self) -> Result<(), StateError> { if self.stack.len() == 1 { return Err(StateError::StackEmpty); diff --git a/crates/bevy_render/src/texture/texture_descriptor.rs b/crates/bevy_render/src/texture/texture_descriptor.rs index 0261be89b8..5d7d349fe1 100644 --- a/crates/bevy_render/src/texture/texture_descriptor.rs +++ b/crates/bevy_render/src/texture/texture_descriptor.rs @@ -58,7 +58,8 @@ pub enum StorageTextureAccess { /// ``` WriteOnly, /// The texture can be both read and written in the shader. - /// `wgpu::Features::STORAGE_TEXTURE_ACCESS_READ_WRITE` must be enabled to use this access mode. + /// `wgpu::Features::STORAGE_TEXTURE_ACCESS_READ_WRITE` must be enabled to use this access + /// mode. /// /// Example GLSL syntax: /// ```cpp,ignore