From 464d35aef56f2bc0b9140a213a3055d1f6af3413 Mon Sep 17 00:00:00 2001 From: Trevor Lovell Date: Mon, 27 Mar 2023 15:50:21 -0600 Subject: [PATCH] docs: update docs and comments that still refer to stages (#8156) # Objective Documentation should no longer be using pre-stageless terminology to avoid confusion. ## Solution - update all docs referring to stages to instead refer to sets/schedules where appropriate - also mention `apply_system_buffers` for anything system-buffer-related that previously referred to buffers being applied "at the end of a stage" --- crates/bevy_ecs/examples/resources.rs | 2 +- crates/bevy_ecs/src/event.rs | 4 ++-- crates/bevy_ecs/src/system/system_param.rs | 7 ++++--- crates/bevy_render/src/lib.rs | 2 +- crates/bevy_transform/src/commands.rs | 6 ++++-- crates/bevy_transform/src/components/global_transform.rs | 2 +- crates/bevy_transform/src/lib.rs | 4 ++-- crates/bevy_winit/src/lib.rs | 2 +- examples/shader/post_process_pass.rs | 2 +- 9 files changed, 17 insertions(+), 14 deletions(-) diff --git a/crates/bevy_ecs/examples/resources.rs b/crates/bevy_ecs/examples/resources.rs index 4030b5fee6b70..b1f170ef9d619 100644 --- a/crates/bevy_ecs/examples/resources.rs +++ b/crates/bevy_ecs/examples/resources.rs @@ -11,7 +11,7 @@ fn main() { // Add the counter resource world.insert_resource(Counter { value: 0 }); - // Create a schedule and a stage + // Create a schedule let mut schedule = Schedule::default(); // Add systems to increase the counter and to print out the current value diff --git a/crates/bevy_ecs/src/event.rs b/crates/bevy_ecs/src/event.rs index 3cdfc19445d57..c740f5e4e4782 100644 --- a/crates/bevy_ecs/src/event.rs +++ b/crates/bevy_ecs/src/event.rs @@ -283,8 +283,8 @@ impl<'a, 'w, 's, E: Event> IntoIterator for &'a mut EventReader<'w, 's, E> { /// // which allows one to do all kinds of clever things with type erasure, such as sending /// // custom events to unknown 3rd party plugins (modding API). /// // -/// // NOTE: the event won't actually be sent until commands get flushed -/// // at the end of the current stage. +/// // NOTE: the event won't actually be sent until commands get applied during +/// // apply_system_buffers. /// commands.add(|w: &mut World| { /// w.send_event(MyEvent); /// }); diff --git a/crates/bevy_ecs/src/system/system_param.rs b/crates/bevy_ecs/src/system/system_param.rs index d0668025c7029..e5b62b007970b 100644 --- a/crates/bevy_ecs/src/system/system_param.rs +++ b/crates/bevy_ecs/src/system/system_param.rs @@ -762,7 +762,8 @@ pub trait SystemBuffer: FromWorld + Send + 'static { fn apply(&mut self, system_meta: &SystemMeta, world: &mut World); } -/// A [`SystemParam`] that stores a buffer which gets applied to the [`World`] at the end of a stage. +/// A [`SystemParam`] that stores a buffer which gets applied to the [`World`] during +/// [`apply_system_buffers`](crate::schedule::apply_system_buffers). /// This is used internally by [`Commands`] to defer `World` mutations. /// /// [`Commands`]: crate::system::Commands @@ -805,7 +806,7 @@ pub trait SystemBuffer: FromWorld + Send + 'static { /// struct AlarmFlag(bool); /// /// impl AlarmFlag { -/// /// Sounds the alarm at the end of the current stage. +/// /// Sounds the alarm the next time buffers are applied via apply_system_buffers. /// pub fn flag(&mut self) { /// self.0 = true; /// } @@ -813,7 +814,7 @@ pub trait SystemBuffer: FromWorld + Send + 'static { /// /// impl SystemBuffer for AlarmFlag { /// // When `AlarmFlag` is used in a system, this function will get -/// // called at the end of the system's stage. +/// // called the next time buffers are applied via apply_system_buffers. /// fn apply(&mut self, system_meta: &SystemMeta, world: &mut World) { /// if self.0 { /// world.resource_mut::().0 = true; diff --git a/crates/bevy_render/src/lib.rs b/crates/bevy_render/src/lib.rs index 7101ba435f314..dd47d53212b6b 100644 --- a/crates/bevy_render/src/lib.rs +++ b/crates/bevy_render/src/lib.rs @@ -251,7 +251,7 @@ impl Plugin for RenderPlugin { .add_systems( Render, ( - // This set applies the commands from the extract stage while the render schedule + // This set applies the commands from the extract schedule while the render schedule // is running in parallel with the main app. apply_extract_commands.in_set(RenderSet::ExtractCommands), ( diff --git a/crates/bevy_transform/src/commands.rs b/crates/bevy_transform/src/commands.rs index 0fa7234ca099f..dc2a950b418b5 100644 --- a/crates/bevy_transform/src/commands.rs +++ b/crates/bevy_transform/src/commands.rs @@ -73,7 +73,8 @@ pub trait BuildChildrenTransformExt { /// [`Transform`]. /// /// Note that both the hierarchy and transform updates will only execute - /// at the end of the current stage. + /// the next time commands are applied + /// (during [`apply_system_buffers`](bevy_ecs::schedule::apply_system_buffers)). fn set_parent_in_place(&mut self, parent: Entity) -> &mut Self; /// Make this entity parentless while preserving this entity's [`GlobalTransform`] @@ -83,7 +84,8 @@ pub trait BuildChildrenTransformExt { /// [`Transform`]. /// /// Note that both the hierarchy and transform updates will only execute - /// at the end of the current stage. + /// the next time commands are applied + /// (during [`apply_system_buffers`](bevy_ecs::schedule::apply_system_buffers)). fn remove_parent_in_place(&mut self) -> &mut Self; } impl<'w, 's, 'a> BuildChildrenTransformExt for EntityCommands<'w, 's, 'a> { diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index a14c5d3dcc348..d82d7bdddcfe6 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -25,7 +25,7 @@ use bevy_reflect::{std_traits::ReflectDefault, FromReflect, Reflect}; /// [`TransformPropagate`](crate::TransformSystem::TransformPropagate). /// /// This system runs during [`PostUpdate`](bevy_app::PostUpdate). If you -/// update the [`Transform`] of an entity in this stage or after, you will notice a 1 frame lag +/// update the [`Transform`] of an entity in this schedule or after, you will notice a 1 frame lag /// before the [`GlobalTransform`] is updated. /// /// # Examples diff --git a/crates/bevy_transform/src/lib.rs b/crates/bevy_transform/src/lib.rs index 2293e0a888e19..130065e098089 100644 --- a/crates/bevy_transform/src/lib.rs +++ b/crates/bevy_transform/src/lib.rs @@ -41,7 +41,7 @@ use systems::{propagate_transforms, sync_simple_transforms}; /// [`TransformPropagate`](crate::TransformSystem::TransformPropagate). /// /// This system runs during [`PostUpdate`](bevy_app::PostUpdate). If you -/// update the [`Transform`] of an entity in this stage or after, you will notice a 1 frame lag +/// update the [`Transform`] of an entity in this schedule or after, you will notice a 1 frame lag /// before the [`GlobalTransform`] is updated. #[derive(Bundle, Clone, Copy, Debug, Default)] pub struct TransformBundle { @@ -61,7 +61,7 @@ impl TransformBundle { /// Creates a new [`TransformBundle`] from a [`Transform`]. /// /// This initializes [`GlobalTransform`] as identity, to be updated later by the - /// [`PostUpdate`](bevy_app::PostUpdate) stage. + /// [`PostUpdate`](bevy_app::PostUpdate) schedule. #[inline] pub const fn from_transform(transform: Transform) -> Self { TransformBundle { diff --git a/crates/bevy_winit/src/lib.rs b/crates/bevy_winit/src/lib.rs index 2dc414457798c..8992fc80db3ed 100644 --- a/crates/bevy_winit/src/lib.rs +++ b/crates/bevy_winit/src/lib.rs @@ -153,7 +153,7 @@ impl Plugin for WinitPlugin { ) = create_window_system_state.get_mut(&mut app.world); // Here we need to create a winit-window and give it a WindowHandle which the renderer can use. - // It needs to be spawned before the start of the startup-stage, so we cannot use a regular system. + // It needs to be spawned before the start of the startup schedule, so we cannot use a regular system. // Instead we need to create the window and spawn it using direct world access create_window( commands, diff --git a/examples/shader/post_process_pass.rs b/examples/shader/post_process_pass.rs index 63d0627f42d14..cc4e3275cbb55 100644 --- a/examples/shader/post_process_pass.rs +++ b/examples/shader/post_process_pass.rs @@ -176,7 +176,7 @@ impl Node for PostProcessNode { // The bind_group gets created each frame. // - // Normally, you would create a bind_group in the Queue stage, but this doesn't work with the post_process_write(). + // Normally, you would create a bind_group in the Queue set, but this doesn't work with the post_process_write(). // The reason it doesn't work is because each post_process_write will alternate the source/destination. // The only way to have the correct source/destination for the bind_group is to make sure you get it during the node execution. let bind_group = render_context