From d20f8553bfcad64f9c476567c786ffb4959c3953 Mon Sep 17 00:00:00 2001 From: Nick Date: Fri, 28 Mar 2025 02:12:19 +0100 Subject: [PATCH] Fix misleading documentation of Main schedule (#18579) # Objective Fixes #18562. ## Solution - Specified that `StateTransition` is actually run before `PreStartup`. - Specified consequences of this and how to actually run systems before any game logic regardless of state. - Updated docs of `StateTransition` to reflect that it is run before `PreStartup` in addition to being run after `PreUpdate`. ## Testing - `cargo doc` - `cargo test --doc` --- crates/bevy_app/src/main_schedule.rs | 13 ++++++++++++- crates/bevy_state/src/state/transitions.rs | 5 ++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/crates/bevy_app/src/main_schedule.rs b/crates/bevy_app/src/main_schedule.rs index 483a828aab..509077705a 100644 --- a/crates/bevy_app/src/main_schedule.rs +++ b/crates/bevy_app/src/main_schedule.rs @@ -15,6 +15,13 @@ use bevy_ecs::{ /// By default, it will run the following schedules in the given order: /// /// On the first run of the schedule (and only on the first run), it will run: +/// * [`StateTransition`] [^1] +/// * This means that [`OnEnter(MyState::Foo)`] will be called *before* [`PreStartup`] +/// if `MyState` was added to the app with `MyState::Foo` as the initial state, +/// as well as [`OnEnter(MyComputedState)`] if it `compute`s to `Some(Self)` in `MyState::Foo`. +/// * If you want to run systems before any state transitions, regardless of which state is the starting state, +/// for example, for registering required components, you can add your own custom startup schedule +/// before [`StateTransition`]. See [`MainScheduleOrder::insert_startup_before`] for more details. /// * [`PreStartup`] /// * [`Startup`] /// * [`PostStartup`] @@ -22,7 +29,7 @@ use bevy_ecs::{ /// Then it will run: /// * [`First`] /// * [`PreUpdate`] -/// * [`StateTransition`] +/// * [`StateTransition`] [^1] /// * [`RunFixedMainLoop`] /// * This will run [`FixedMain`] zero to many times, based on how much time has elapsed. /// * [`Update`] @@ -37,7 +44,11 @@ use bevy_ecs::{ /// /// See [`RenderPlugin`] and [`PipelinedRenderingPlugin`] for more details. /// +/// [^1]: [`StateTransition`] is inserted only if you have `bevy_state` feature enabled. It is enabled in `default` features. +/// /// [`StateTransition`]: https://docs.rs/bevy/latest/bevy/prelude/struct.StateTransition.html +/// [`OnEnter(MyState::Foo)`]: https://docs.rs/bevy/latest/bevy/prelude/struct.OnEnter.html +/// [`OnEnter(MyComputedState)`]: https://docs.rs/bevy/latest/bevy/prelude/struct.OnEnter.html /// [`RenderPlugin`]: https://docs.rs/bevy/latest/bevy/render/struct.RenderPlugin.html /// [`PipelinedRenderingPlugin`]: https://docs.rs/bevy/latest/bevy/render/pipelined_rendering/struct.PipelinedRenderingPlugin.html /// [`SubApp`]: crate::SubApp diff --git a/crates/bevy_state/src/state/transitions.rs b/crates/bevy_state/src/state/transitions.rs index 4ce1e6b210..0fec0769dd 100644 --- a/crates/bevy_state/src/state/transitions.rs +++ b/crates/bevy_state/src/state/transitions.rs @@ -37,7 +37,7 @@ pub struct OnTransition { /// Runs [state transitions](States). /// -/// By default, it will be triggered after `PreUpdate`, but +/// By default, it will be triggered once before [`PreStartup`] and then each frame after [`PreUpdate`], but /// you can manually trigger it at arbitrary times by creating an exclusive /// system to run the schedule. /// @@ -49,6 +49,9 @@ pub struct OnTransition { /// let _ = world.try_run_schedule(StateTransition); /// } /// ``` +/// +/// [`PreStartup`]: https://docs.rs/bevy/latest/bevy/prelude/struct.PreStartup.html +/// [`PreUpdate`]: https://docs.rs/bevy/latest/bevy/prelude/struct.PreUpdate.html #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)] pub struct StateTransition;