diff --git a/crates/bevy_app/src/main_schedule.rs b/crates/bevy_app/src/main_schedule.rs index 651708b363..1a22dc8a5c 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 66aa42bf14..d59b17c5dd 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`] resource, and it will be applied by the next -/// [`apply_state_transition::`](crate::state::apply_state_transition) system. +/// queue a transition in the [`NextState`] 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 Deref for State { /// 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 747e09d9dd..dc2764df42 100644 --- a/crates/bevy_state/src/state/transitions.rs +++ b/crates/bevy_state/src/state/transitions.rs @@ -38,6 +38,19 @@ pub struct OnTransition { } /// 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;