From 7ec301c48d90e59f47eead9dee84ab16a776cf77 Mon Sep 17 00:00:00 2001
From: Lee-Orr <lee-orr@users.noreply.github.com>
Date: Mon, 10 Jun 2024 09:23:14 -0400
Subject: [PATCH] =?UTF-8?q?fix=20docs=20around=20`StateTransition`=20and?=
 =?UTF-8?q?=20remove=20references=20to=20`apply=5Fsta=E2=80=A6=20(#13772)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The documentation for the `State` resource still referenced the use of
`apply_state_transition` to manually force a state transition to occur,
and the question around how to force transitions had come up a few times
on discord.

This is a docs-only change, that does the following:
- Properly references `StateTransition` in the `MainSchedule` docs
- replace the explanations for applying `NextState` with ones that
explain the `StateTransition` schedule, and mentions the possibility of
calling it manually
- Add an example of calling `StateTransition` manually in the docs for
the state transition schedule itself.

---------

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
---
 crates/bevy_app/src/main_schedule.rs       |  2 +-
 crates/bevy_state/src/state/resources.rs   |  9 ++++++---
 crates/bevy_state/src/state/transitions.rs | 13 +++++++++++++
 3 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/crates/bevy_app/src/main_schedule.rs b/crates/bevy_app/src/main_schedule.rs
index 651708b36388d..1a22dc8a5cc5a 100644
--- a/crates/bevy_app/src/main_schedule.rs
+++ b/crates/bevy_app/src/main_schedule.rs
@@ -17,7 +17,7 @@ use bevy_ecs::{
 /// Then it will run:
 /// * [`First`]
 /// * [`PreUpdate`]
-/// * [`StateTransition`]
+/// * [`StateTransition`](bevy_state::transition::StateTransition)
 /// * [`RunFixedMainLoop`]
 ///     * This will run [`FixedMain`] zero to many times, based on how much time has elapsed.
 /// * [`Update`]
diff --git a/crates/bevy_state/src/state/resources.rs b/crates/bevy_state/src/state/resources.rs
index 66aa42bf14e08..d59b17c5ddde1 100644
--- a/crates/bevy_state/src/state/resources.rs
+++ b/crates/bevy_state/src/state/resources.rs
@@ -15,8 +15,11 @@ use bevy_ecs::prelude::ReflectResource;
 /// ([`OnEnter(state)`](crate::state::OnEnter) and [`OnExit(state)`](crate::state::OnExit)).
 ///
 /// The current state value can be accessed through this resource. To *change* the state,
-/// queue a transition in the [`NextState<S>`] resource, and it will be applied by the next
-/// [`apply_state_transition::<S>`](crate::state::apply_state_transition) system.
+/// queue a transition in the [`NextState<S>`] resource, and it will be applied during the
+/// [`StateTransition`](crate::transition::StateTransition) schedule - which by default runs after `PreUpdate`.
+///
+/// You can also manually trigger the [`StateTransition`](crate::transition::StateTransition) schedule to apply the changes
+/// at an arbitrary time.
 ///
 /// The starting state is defined via the [`Default`] implementation for `S`.
 ///
@@ -90,7 +93,7 @@ impl<S: States> Deref for State<S> {
 /// To queue a transition, call [`NextState::set`] or mutate the value to [`NextState::Pending`] directly.
 ///
 /// Note that these transitions can be overridden by other systems:
-/// only the actual value of this resource at the time of [`apply_state_transition`](crate::state::apply_state_transition) matters.
+/// only the actual value of this resource during the [`StateTransition`](crate::transition::StateTransition) schedule matters.
 ///
 /// ```
 /// use bevy_state::prelude::*;
diff --git a/crates/bevy_state/src/state/transitions.rs b/crates/bevy_state/src/state/transitions.rs
index 747e09d9dd874..dc2764df42e19 100644
--- a/crates/bevy_state/src/state/transitions.rs
+++ b/crates/bevy_state/src/state/transitions.rs
@@ -38,6 +38,19 @@ pub struct OnTransition<S: States> {
 }
 
 /// Runs [state transitions](States).
+///
+/// By default, it will be triggered after `PreUpdate`, but
+/// you can manually trigger it at arbitrary times by creating an exclusive
+/// system to run the schedule.
+///
+/// ```rust
+/// use bevy_state::prelude::*;
+/// use bevy_ecs::prelude::*;
+///
+/// fn run_state_transitions(world: &mut World) {
+///     let _ = world.try_run_schedule(StateTransition);
+/// }
+/// ```
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct StateTransition;