From 9c9c9465b6c51c9ddbc73c293855db46944d51a7 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Mon, 3 Jun 2024 16:27:09 +0200
Subject: [PATCH 01/19] state bound module

---
 crates/bevy_state/Cargo.toml               |  4 +-
 crates/bevy_state/src/lib.rs               | 10 +++-
 crates/bevy_state/src/state/states.rs      |  8 +--
 crates/bevy_state/src/state/transitions.rs | 11 ++++
 crates/bevy_state/src/state_bound.rs       | 65 ++++++++++++++++++++++
 5 files changed, 91 insertions(+), 7 deletions(-)
 create mode 100644 crates/bevy_state/src/state_bound.rs

diff --git a/crates/bevy_state/Cargo.toml b/crates/bevy_state/Cargo.toml
index 6919f9f0cb19e..39e8623e861ab 100644
--- a/crates/bevy_state/Cargo.toml
+++ b/crates/bevy_state/Cargo.toml
@@ -12,9 +12,10 @@ categories = ["game-engines", "data-structures"]
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [features]
-default = ["bevy_reflect", "bevy_app"]
+default = ["bevy_reflect", "bevy_app", "bevy_hierarchy"]
 bevy_reflect = ["dep:bevy_reflect", "bevy_ecs/bevy_reflect"]
 bevy_app = ["dep:bevy_app"]
+bevy_hierarchy = ["dep:bevy_hierarchy"]
 
 [dependencies]
 bevy_ecs = { path = "../bevy_ecs", version = "0.14.0-dev" }
@@ -22,6 +23,7 @@ bevy_state_macros = { path = "macros", version = "0.14.0-dev" }
 bevy_utils = { path = "../bevy_utils", version = "0.14.0-dev" }
 bevy_reflect = { path = "../bevy_reflect", version = "0.14.0-dev", optional = true }
 bevy_app = { path = "../bevy_app", version = "0.14.0-dev", optional = true }
+bevy_hierarchy = { path = "../bevy_hierarchy", version = "0.14.0-dev", optional = true }
 
 [lints]
 workspace = true
diff --git a/crates/bevy_state/src/lib.rs b/crates/bevy_state/src/lib.rs
index 408ee9963b12e..2fc55ae3d35cb 100644
--- a/crates/bevy_state/src/lib.rs
+++ b/crates/bevy_state/src/lib.rs
@@ -34,6 +34,9 @@ pub mod app;
 pub mod condition;
 /// Provides definitions for the basic traits required by the state system
 pub mod state;
+#[cfg(feature = "bevy_hierarchy")]
+/// Provides [`StateBound`] and [`clear_state_bound_entities`] for managing lifetime of entities.
+pub mod state_bound;
 
 /// Most commonly used re-exported types.
 pub mod prelude {
@@ -44,7 +47,10 @@ pub mod prelude {
     pub use crate::condition::*;
     #[doc(hidden)]
     pub use crate::state::{
-        ComputedStates, NextState, OnEnter, OnExit, OnTransition, State, StateSet, StateTransition,
-        StateTransitionEvent, States, SubStates,
+        log_transitions, ComputedStates, NextState, OnEnter, OnExit, OnTransition, State, StateSet,
+        StateTransition, StateTransitionEvent, States, SubStates,
     };
+    #[cfg(feature = "bevy_hierarchy")]
+    #[doc(hidden)]
+    pub use crate::state_bound::*;
 }
diff --git a/crates/bevy_state/src/state/states.rs b/crates/bevy_state/src/state/states.rs
index 6f2be17cd5759..cde092e68a9f1 100644
--- a/crates/bevy_state/src/state/states.rs
+++ b/crates/bevy_state/src/state/states.rs
@@ -27,10 +27,10 @@ use std::hash::Hash;
 ///
 /// #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default, States)]
 /// enum GameState {
-///  #[default]
-///   MainMenu,
-///   SettingsMenu,
-///   InGame,
+///     #[default]
+///     MainMenu,
+///     SettingsMenu,
+///     InGame,
 /// }
 ///
 /// fn handle_escape_pressed(mut next_state: ResMut<NextState<GameState>>) {
diff --git a/crates/bevy_state/src/state/transitions.rs b/crates/bevy_state/src/state/transitions.rs
index b816b4ad173a3..e3a861b99f15b 100644
--- a/crates/bevy_state/src/state/transitions.rs
+++ b/crates/bevy_state/src/state/transitions.rs
@@ -8,6 +8,7 @@ use bevy_ecs::{
     system::{Commands, In, ResMut},
     world::World,
 };
+use bevy_utils::tracing::info;
 
 use super::{resources::State, states::States};
 
@@ -206,3 +207,13 @@ pub(crate) fn run_transition<S: States>(
 
     let _ = world.try_run_schedule(OnTransition { exited, entered });
 }
+
+/// Logs state transitions into console.
+pub fn log_transitions<S: States>(mut transitions: EventReader<StateTransitionEvent<S>>) {
+    for transition in transitions.read() {
+        info!(
+            "Transition: {:?} => {:?}",
+            transition.exited, transition.entered
+        );
+    }
+}
diff --git a/crates/bevy_state/src/state_bound.rs b/crates/bevy_state/src/state_bound.rs
new file mode 100644
index 0000000000000..6fe9b8526f5a0
--- /dev/null
+++ b/crates/bevy_state/src/state_bound.rs
@@ -0,0 +1,65 @@
+use bevy_ecs::{
+    component::Component,
+    entity::Entity,
+    system::{Commands, Query},
+};
+use bevy_hierarchy::DespawnRecursiveExt;
+
+use crate::state::States;
+
+/// Entities marked with this component will be removed
+/// when the provided value no longer matches the world state.
+///
+/// To enable this feature, register the [`clear_state_bound_entities`]
+/// system for selected states.
+///
+/// ```
+/// use bevy_state::prelude::*;
+/// use bevy_ecs::prelude::IntoSystemConfigs;
+/// use bevy_ecs::system::ResMut;
+///
+///
+/// #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default, States)]
+/// enum GameState {
+///     #[default]
+///     MainMenu,
+///     SettingsMenu,
+///     InGame,
+/// }
+///
+/// # #[derive(Component)]
+/// # struct Player;
+///
+/// fn spawn_player(mut commands: Commands) {
+///     commands.spawn((
+///         StateBound(GameState::InGame),
+///         Player
+///     ));
+/// }
+///
+/// # struct AppMock;
+/// # impl AppMock {
+/// #     fn add_systems<S, M>(&mut self, schedule: S, systems: impl IntoSystemConfigs<M>) {}
+/// # }
+/// # struct Update;
+/// # let mut app = AppMock;
+///
+/// app.add_systems(Update, clear_state_bound_entities::<GameState>);
+/// app.add_systems(OnEnter(GameState::InGame), spawn_player);
+/// ```
+#[derive(Component)]
+pub struct StateBound<S: States>(pub S);
+
+/// Removes entities marked with [`StateBound<S>`]
+/// when their state no longer matches the world state.
+pub fn clear_state_bound_entities<S: States>(
+    state: S,
+) -> impl Fn(Commands, Query<(Entity, &StateBound<S>)>) {
+    move |mut commands, query| {
+        for (entity, bound) in &query {
+            if bound.0 == state {
+                commands.entity(entity).despawn_recursive();
+            }
+        }
+    }
+}

From 0ad7eb73003b9c919a38c3d8780842371c484150 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Mon, 3 Jun 2024 16:30:19 +0200
Subject: [PATCH 02/19] use moved features in examples

---
 examples/state/computed_states.rs | 43 +++++--------------------------
 examples/state/state.rs           | 13 +---------
 examples/state/sub_states.rs      | 27 +------------------
 3 files changed, 9 insertions(+), 74 deletions(-)

diff --git a/examples/state/computed_states.rs b/examples/state/computed_states.rs
index 77f99ad0c27ea..a1d62a0132f97 100644
--- a/examples/state/computed_states.rs
+++ b/examples/state/computed_states.rs
@@ -219,7 +219,13 @@ fn main() {
             OnExit(Tutorial::PauseInstructions),
             clear_state_bound_entities(Tutorial::PauseInstructions),
         )
-        .add_systems(Update, log_transitions)
+        .add_systems(
+            Update,
+            (
+                log_transitions::<AppState>,
+                log_transitions::<TutorialState>,
+            ),
+        )
         .run();
 }
 
@@ -277,22 +283,6 @@ fn menu(
     }
 }
 
-#[derive(Component)]
-struct StateBound<S: States>(S);
-
-fn clear_state_bound_entities<S: States>(
-    state: S,
-) -> impl Fn(Commands, Query<(Entity, &StateBound<S>)>) {
-    info!("Clearing entities for {state:?}");
-    move |mut commands, query| {
-        for (entity, bound) in &query {
-            if bound.0 == state {
-                commands.entity(entity).despawn_recursive();
-            }
-        }
-    }
-}
-
 fn toggle_pause(
     input: Res<ButtonInput<KeyCode>>,
     current_state: Res<State<AppState>>,
@@ -329,25 +319,6 @@ fn quit_to_menu(input: Res<ButtonInput<KeyCode>>, mut next_state: ResMut<NextSta
     }
 }
 
-/// print when either an `AppState` transition or a `TutorialState` transition happens
-fn log_transitions(
-    mut transitions: EventReader<StateTransitionEvent<AppState>>,
-    mut tutorial_transitions: EventReader<StateTransitionEvent<TutorialState>>,
-) {
-    for transition in transitions.read() {
-        info!(
-            "transition: {:?} => {:?}",
-            transition.exited, transition.entered
-        );
-    }
-    for transition in tutorial_transitions.read() {
-        info!(
-            "tutorial transition: {:?} => {:?}",
-            transition.exited, transition.entered
-        );
-    }
-}
-
 mod ui {
     use crate::*;
 
diff --git a/examples/state/state.rs b/examples/state/state.rs
index d695e82e4a75b..776f913543941 100644
--- a/examples/state/state.rs
+++ b/examples/state/state.rs
@@ -25,7 +25,7 @@ fn main() {
             Update,
             (movement, change_color).run_if(in_state(AppState::InGame)),
         )
-        .add_systems(Update, log_transitions)
+        .add_systems(Update, log_transitions::<AppState>)
         .run();
 }
 
@@ -163,14 +163,3 @@ fn change_color(time: Res<Time>, mut query: Query<&mut Sprite>) {
         sprite.color = new_color.into();
     }
 }
-
-/// print when an `AppState` transition happens
-/// also serves as an example of how to use `StateTransitionEvent`
-fn log_transitions(mut transitions: EventReader<StateTransitionEvent<AppState>>) {
-    for transition in transitions.read() {
-        info!(
-            "transition: {:?} => {:?}",
-            transition.exited, transition.entered
-        );
-    }
-}
diff --git a/examples/state/sub_states.rs b/examples/state/sub_states.rs
index 704df87fbb31f..6f0fcd4900777 100644
--- a/examples/state/sub_states.rs
+++ b/examples/state/sub_states.rs
@@ -59,7 +59,7 @@ fn main() {
                 toggle_pause.run_if(in_state(AppState::InGame)),
             ),
         )
-        .add_systems(Update, log_transitions)
+        .add_systems(Update, log_transitions::<AppState>)
         .run();
 }
 
@@ -142,31 +142,6 @@ fn toggle_pause(
     }
 }
 
-#[derive(Component)]
-struct StateBound<S: States>(S);
-
-fn clear_state_bound_entities<S: States>(
-    state: S,
-) -> impl Fn(Commands, Query<(Entity, &StateBound<S>)>) {
-    move |mut commands, query| {
-        for (entity, bound) in &query {
-            if bound.0 == state {
-                commands.entity(entity).despawn_recursive();
-            }
-        }
-    }
-}
-
-/// print when an `AppState` transition happens
-fn log_transitions(mut transitions: EventReader<StateTransitionEvent<AppState>>) {
-    for transition in transitions.read() {
-        info!(
-            "transition: {:?} => {:?}",
-            transition.exited, transition.entered
-        );
-    }
-}
-
 mod ui {
     use crate::*;
 

From ee17b642c878efe0589547ec1c79c10ea9da6f65 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Mon, 3 Jun 2024 17:08:18 +0200
Subject: [PATCH 03/19] refactor statebound and add app method

---
 crates/bevy_state/src/app.rs         | 32 ++++++++++++++++++++++++----
 crates/bevy_state/src/state_bound.rs | 27 ++++++++++++++---------
 examples/state/computed_states.rs    | 18 ++++------------
 examples/state/sub_states.rs         |  5 +----
 4 files changed, 50 insertions(+), 32 deletions(-)

diff --git a/crates/bevy_state/src/app.rs b/crates/bevy_state/src/app.rs
index 47c4f08405197..329f5e028a725 100644
--- a/crates/bevy_state/src/app.rs
+++ b/crates/bevy_state/src/app.rs
@@ -1,9 +1,16 @@
 use bevy_app::{App, MainScheduleOrder, Plugin, PreUpdate, Startup, SubApp};
-use bevy_ecs::{event::Events, schedule::ScheduleLabel, world::FromWorld};
+use bevy_ecs::{
+    event::Events,
+    schedule::{IntoSystemConfigs, ScheduleLabel},
+    world::FromWorld,
+};
 
-use crate::state::{
-    setup_state_transitions_in_world, ComputedStates, FreelyMutableState, NextState, State,
-    StateTransition, StateTransitionEvent, SubStates,
+use crate::{
+    state::{
+        setup_state_transitions_in_world, ComputedStates, FreelyMutableState, NextState, State,
+        StateTransition, StateTransitionEvent, StateTransitionSteps, States, SubStates,
+    },
+    state_bound::clear_state_bound_entities,
 };
 
 /// State installation methods for [`App`](bevy_app::App) and [`SubApp`](bevy_app::SubApp).
@@ -44,6 +51,11 @@ pub trait AppExtStates {
     ///
     /// This method is idempotent: it has no effect when called again using the same generic type.
     fn add_sub_state<S: SubStates>(&mut self) -> &mut Self;
+
+    /// Register state bound entity clearing for state `S`.
+    ///
+    /// For more information refer to [`StateBound`](crate::state_bound::StateBound).
+    fn add_state_bound<S: States>(&mut self) -> &mut Self;
 }
 
 impl AppExtStates for SubApp {
@@ -120,6 +132,13 @@ impl AppExtStates for SubApp {
 
         self
     }
+
+    fn add_state_bound<S: States>(&mut self) -> &mut Self {
+        self.add_systems(
+            StateTransition,
+            clear_state_bound_entities::<S>.in_set(StateTransitionSteps::ExitSchedules),
+        )
+    }
 }
 
 impl AppExtStates for App {
@@ -142,6 +161,11 @@ impl AppExtStates for App {
         self.main_mut().add_sub_state::<S>();
         self
     }
+
+    fn add_state_bound<S: States>(&mut self) -> &mut Self {
+        self.main_mut().add_state_bound::<S>();
+        self
+    }
 }
 
 /// Registers the [`StateTransition`] schedule in the [`MainScheduleOrder`] to enable state processing.
diff --git a/crates/bevy_state/src/state_bound.rs b/crates/bevy_state/src/state_bound.rs
index 6fe9b8526f5a0..c2893d105ff20 100644
--- a/crates/bevy_state/src/state_bound.rs
+++ b/crates/bevy_state/src/state_bound.rs
@@ -1,11 +1,12 @@
 use bevy_ecs::{
     component::Component,
     entity::Entity,
+    event::EventReader,
     system::{Commands, Query},
 };
 use bevy_hierarchy::DespawnRecursiveExt;
 
-use crate::state::States;
+use crate::state::{StateTransitionEvent, States};
 
 /// Entities marked with this component will be removed
 /// when the provided value no longer matches the world state.
@@ -16,7 +17,6 @@ use crate::state::States;
 /// ```
 /// use bevy_state::prelude::*;
 /// use bevy_ecs::prelude::IntoSystemConfigs;
-/// use bevy_ecs::system::ResMut;
 ///
 ///
 /// #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default, States)]
@@ -44,7 +44,8 @@ use crate::state::States;
 /// # struct Update;
 /// # let mut app = AppMock;
 ///
-/// app.add_systems(Update, clear_state_bound_entities::<GameState>);
+/// app.init_state::<GameState>();
+/// app.add_state_bound::<GameState>();
 /// app.add_systems(OnEnter(GameState::InGame), spawn_player);
 /// ```
 #[derive(Component)]
@@ -53,13 +54,19 @@ pub struct StateBound<S: States>(pub S);
 /// Removes entities marked with [`StateBound<S>`]
 /// when their state no longer matches the world state.
 pub fn clear_state_bound_entities<S: States>(
-    state: S,
-) -> impl Fn(Commands, Query<(Entity, &StateBound<S>)>) {
-    move |mut commands, query| {
-        for (entity, bound) in &query {
-            if bound.0 == state {
-                commands.entity(entity).despawn_recursive();
-            }
+    mut commands: Commands,
+    mut transitions: EventReader<StateTransitionEvent<S>>,
+    query: Query<(Entity, &StateBound<S>)>,
+) {
+    let Some(transition) = transitions.read().last() else {
+        return;
+    };
+    let Some(exited) = &transition.exited else {
+        return;
+    };
+    for (entity, binding) in &query {
+        if binding.0 == *exited {
+            commands.entity(entity).despawn_recursive();
         }
     }
 }
diff --git a/examples/state/computed_states.rs b/examples/state/computed_states.rs
index a1d62a0132f97..8a4d59585d524 100644
--- a/examples/state/computed_states.rs
+++ b/examples/state/computed_states.rs
@@ -186,7 +186,7 @@ fn main() {
         .add_systems(OnEnter(InGame), setup_game)
         // And we only want to run the [`clear_game`] function when we leave the [`AppState::InGame`] state, regardless
         // of whether we're paused.
-        .add_systems(OnExit(InGame), clear_state_bound_entities(InGame))
+        .add_state_bound::<InGame>()
         // We want the color change, toggle_pause and quit_to_menu systems to ignore the paused condition, so we can use the [`InGame`] derived
         // state here as well.
         .add_systems(
@@ -200,25 +200,15 @@ fn main() {
         )
         // We can continue setting things up, following all the same patterns used above and in the `states` example.
         .add_systems(OnEnter(IsPaused::Paused), setup_paused_screen)
-        .add_systems(
-            OnExit(IsPaused::Paused),
-            clear_state_bound_entities(IsPaused::Paused),
-        )
+        .add_state_bound::<IsPaused>()
         .add_systems(OnEnter(TurboMode), setup_turbo_text)
-        .add_systems(OnExit(TurboMode), clear_state_bound_entities(TurboMode))
+        .add_state_bound::<TurboMode>()
         .add_systems(
             OnEnter(Tutorial::MovementInstructions),
             movement_instructions,
         )
         .add_systems(OnEnter(Tutorial::PauseInstructions), pause_instructions)
-        .add_systems(
-            OnExit(Tutorial::MovementInstructions),
-            clear_state_bound_entities(Tutorial::MovementInstructions),
-        )
-        .add_systems(
-            OnExit(Tutorial::PauseInstructions),
-            clear_state_bound_entities(Tutorial::PauseInstructions),
-        )
+        .add_state_bound::<Tutorial>()
         .add_systems(
             Update,
             (
diff --git a/examples/state/sub_states.rs b/examples/state/sub_states.rs
index 6f0fcd4900777..ddb3db3461cc7 100644
--- a/examples/state/sub_states.rs
+++ b/examples/state/sub_states.rs
@@ -43,10 +43,7 @@ fn main() {
         .add_systems(OnExit(AppState::Menu), cleanup_menu)
         .add_systems(OnEnter(AppState::InGame), setup_game)
         .add_systems(OnEnter(IsPaused::Paused), setup_paused_screen)
-        .add_systems(
-            OnExit(IsPaused::Paused),
-            clear_state_bound_entities(IsPaused::Paused),
-        )
+        .add_state_bound::<IsPaused>()
         .add_systems(
             Update,
             (

From 918e55aa2219fe725fbc6e8a1ef9aa6c1a4166f8 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Mon, 3 Jun 2024 17:09:51 +0200
Subject: [PATCH 04/19] feature gate

---
 crates/bevy_state/src/app.rs | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/crates/bevy_state/src/app.rs b/crates/bevy_state/src/app.rs
index 329f5e028a725..50de30c2b4501 100644
--- a/crates/bevy_state/src/app.rs
+++ b/crates/bevy_state/src/app.rs
@@ -5,13 +5,12 @@ use bevy_ecs::{
     world::FromWorld,
 };
 
-use crate::{
-    state::{
-        setup_state_transitions_in_world, ComputedStates, FreelyMutableState, NextState, State,
-        StateTransition, StateTransitionEvent, StateTransitionSteps, States, SubStates,
-    },
-    state_bound::clear_state_bound_entities,
+use crate::state::{
+    setup_state_transitions_in_world, ComputedStates, FreelyMutableState, NextState, State,
+    StateTransition, StateTransitionEvent, StateTransitionSteps, States, SubStates,
 };
+#[cfg(feature = "bevy_hierarchy")]
+use crate::state_bound::clear_state_bound_entities;
 
 /// State installation methods for [`App`](bevy_app::App) and [`SubApp`](bevy_app::SubApp).
 pub trait AppExtStates {
@@ -52,6 +51,7 @@ pub trait AppExtStates {
     /// This method is idempotent: it has no effect when called again using the same generic type.
     fn add_sub_state<S: SubStates>(&mut self) -> &mut Self;
 
+    #[cfg(feature = "bevy_hierarchy")]
     /// Register state bound entity clearing for state `S`.
     ///
     /// For more information refer to [`StateBound`](crate::state_bound::StateBound).
@@ -133,6 +133,7 @@ impl AppExtStates for SubApp {
         self
     }
 
+    #[cfg(feature = "bevy_hierarchy")]
     fn add_state_bound<S: States>(&mut self) -> &mut Self {
         self.add_systems(
             StateTransition,
@@ -162,6 +163,7 @@ impl AppExtStates for App {
         self
     }
 
+    #[cfg(feature = "bevy_hierarchy")]
     fn add_state_bound<S: States>(&mut self) -> &mut Self {
         self.main_mut().add_state_bound::<S>();
         self

From 6686d5f37966a2d309b6c8308f91279d9b1372a2 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Mon, 3 Jun 2024 17:17:31 +0200
Subject: [PATCH 05/19] remove state bound system from prelude

---
 crates/bevy_state/src/lib.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/bevy_state/src/lib.rs b/crates/bevy_state/src/lib.rs
index 2fc55ae3d35cb..497196970f898 100644
--- a/crates/bevy_state/src/lib.rs
+++ b/crates/bevy_state/src/lib.rs
@@ -52,5 +52,5 @@ pub mod prelude {
     };
     #[cfg(feature = "bevy_hierarchy")]
     #[doc(hidden)]
-    pub use crate::state_bound::*;
+    pub use crate::state_bound::StateBound;
 }

From 2e536770e27f26e35050888816e5aab125b4b594 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Mon, 3 Jun 2024 17:30:34 +0200
Subject: [PATCH 06/19] pray the docs are fixed

---
 crates/bevy_state/src/state_bound.rs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_state/src/state_bound.rs b/crates/bevy_state/src/state_bound.rs
index c2893d105ff20..6c74e5bd268fa 100644
--- a/crates/bevy_state/src/state_bound.rs
+++ b/crates/bevy_state/src/state_bound.rs
@@ -16,8 +16,7 @@ use crate::state::{StateTransitionEvent, States};
 ///
 /// ```
 /// use bevy_state::prelude::*;
-/// use bevy_ecs::prelude::IntoSystemConfigs;
-///
+/// use bevy_ecs::prelude::*;
 ///
 /// #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default, States)]
 /// enum GameState {
@@ -39,6 +38,8 @@ use crate::state::{StateTransitionEvent, States};
 ///
 /// # struct AppMock;
 /// # impl AppMock {
+/// #     fn init_state<S>(&mut self) {}
+/// #     fn add_state_bound<S>(&mut self) {}
 /// #     fn add_systems<S, M>(&mut self, schedule: S, systems: impl IntoSystemConfigs<M>) {}
 /// # }
 /// # struct Update;

From 40b60051ea65f29d73b016e1857796471a4c3d8d Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Mon, 3 Jun 2024 18:07:43 +0200
Subject: [PATCH 07/19] Apply suggestions from code review

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

diff --git a/crates/bevy_state/src/app.rs b/crates/bevy_state/src/app.rs
index 50de30c2b4501..5e538d797a37f 100644
--- a/crates/bevy_state/src/app.rs
+++ b/crates/bevy_state/src/app.rs
@@ -52,7 +52,7 @@ pub trait AppExtStates {
     fn add_sub_state<S: SubStates>(&mut self) -> &mut Self;
 
     #[cfg(feature = "bevy_hierarchy")]
-    /// Register state bound entity clearing for state `S`.
+    /// Enable state bound entity clearing for state `S`.
     ///
     /// For more information refer to [`StateBound`](crate::state_bound::StateBound).
     fn add_state_bound<S: States>(&mut self) -> &mut Self;
diff --git a/crates/bevy_state/src/state/transitions.rs b/crates/bevy_state/src/state/transitions.rs
index e3a861b99f15b..6536558be00b6 100644
--- a/crates/bevy_state/src/state/transitions.rs
+++ b/crates/bevy_state/src/state/transitions.rs
@@ -209,6 +209,8 @@ pub(crate) fn run_transition<S: States>(
 }
 
 /// Logs state transitions into console.
+///
+/// This system is provided to make debugging easier for Bevy developers.
 pub fn log_transitions<S: States>(mut transitions: EventReader<StateTransitionEvent<S>>) {
     for transition in transitions.read() {
         info!(
diff --git a/crates/bevy_state/src/state_bound.rs b/crates/bevy_state/src/state_bound.rs
index 6c74e5bd268fa..b7ac2aad4b23e 100644
--- a/crates/bevy_state/src/state_bound.rs
+++ b/crates/bevy_state/src/state_bound.rs
@@ -9,7 +9,7 @@ use bevy_hierarchy::DespawnRecursiveExt;
 use crate::state::{StateTransitionEvent, States};
 
 /// Entities marked with this component will be removed
-/// when the provided value no longer matches the world state.
+/// when the world's state of the matching type no longer matches the supplied value.
 ///
 /// To enable this feature, register the [`clear_state_bound_entities`]
 /// system for selected states.

From 9f36f98979bf1f85ef1c24923194ebb0ac2fdf29 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Mon, 3 Jun 2024 18:14:52 +0200
Subject: [PATCH 08/19] more PR suggestions

---
 crates/bevy_state/src/app.rs         | 8 ++++----
 crates/bevy_state/src/state_bound.rs | 4 ++--
 examples/state/computed_states.rs    | 8 ++++----
 examples/state/sub_states.rs         | 2 +-
 4 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/crates/bevy_state/src/app.rs b/crates/bevy_state/src/app.rs
index 5e538d797a37f..2f320ca359956 100644
--- a/crates/bevy_state/src/app.rs
+++ b/crates/bevy_state/src/app.rs
@@ -55,7 +55,7 @@ pub trait AppExtStates {
     /// Enable state bound entity clearing for state `S`.
     ///
     /// For more information refer to [`StateBound`](crate::state_bound::StateBound).
-    fn add_state_bound<S: States>(&mut self) -> &mut Self;
+    fn enable_state_bound_entities<S: States>(&mut self) -> &mut Self;
 }
 
 impl AppExtStates for SubApp {
@@ -134,7 +134,7 @@ impl AppExtStates for SubApp {
     }
 
     #[cfg(feature = "bevy_hierarchy")]
-    fn add_state_bound<S: States>(&mut self) -> &mut Self {
+    fn enable_state_bound_entities<S: States>(&mut self) -> &mut Self {
         self.add_systems(
             StateTransition,
             clear_state_bound_entities::<S>.in_set(StateTransitionSteps::ExitSchedules),
@@ -164,8 +164,8 @@ impl AppExtStates for App {
     }
 
     #[cfg(feature = "bevy_hierarchy")]
-    fn add_state_bound<S: States>(&mut self) -> &mut Self {
-        self.main_mut().add_state_bound::<S>();
+    fn enable_state_bound_entities<S: States>(&mut self) -> &mut Self {
+        self.main_mut().enable_state_bound_entities::<S>();
         self
     }
 }
diff --git a/crates/bevy_state/src/state_bound.rs b/crates/bevy_state/src/state_bound.rs
index b7ac2aad4b23e..36414dabe6cfc 100644
--- a/crates/bevy_state/src/state_bound.rs
+++ b/crates/bevy_state/src/state_bound.rs
@@ -11,8 +11,8 @@ use crate::state::{StateTransitionEvent, States};
 /// Entities marked with this component will be removed
 /// when the world's state of the matching type no longer matches the supplied value.
 ///
-/// To enable this feature, register the [`clear_state_bound_entities`]
-/// system for selected states.
+/// To enable this feature remember configure your application
+/// with [`enable_state_bound_entities`](crate::app::AppExtStates::enable_state_bound_entities) on your state(s) of choice.
 ///
 /// ```
 /// use bevy_state::prelude::*;
diff --git a/examples/state/computed_states.rs b/examples/state/computed_states.rs
index 8a4d59585d524..cf1043f1d3853 100644
--- a/examples/state/computed_states.rs
+++ b/examples/state/computed_states.rs
@@ -186,7 +186,7 @@ fn main() {
         .add_systems(OnEnter(InGame), setup_game)
         // And we only want to run the [`clear_game`] function when we leave the [`AppState::InGame`] state, regardless
         // of whether we're paused.
-        .add_state_bound::<InGame>()
+        .enable_state_bound_entities::<InGame>()
         // We want the color change, toggle_pause and quit_to_menu systems to ignore the paused condition, so we can use the [`InGame`] derived
         // state here as well.
         .add_systems(
@@ -200,15 +200,15 @@ fn main() {
         )
         // We can continue setting things up, following all the same patterns used above and in the `states` example.
         .add_systems(OnEnter(IsPaused::Paused), setup_paused_screen)
-        .add_state_bound::<IsPaused>()
+        .enable_state_bound_entities::<IsPaused>()
         .add_systems(OnEnter(TurboMode), setup_turbo_text)
-        .add_state_bound::<TurboMode>()
+        .enable_state_bound_entities::<TurboMode>()
         .add_systems(
             OnEnter(Tutorial::MovementInstructions),
             movement_instructions,
         )
         .add_systems(OnEnter(Tutorial::PauseInstructions), pause_instructions)
-        .add_state_bound::<Tutorial>()
+        .enable_state_bound_entities::<Tutorial>()
         .add_systems(
             Update,
             (
diff --git a/examples/state/sub_states.rs b/examples/state/sub_states.rs
index ddb3db3461cc7..51a6027fad0f9 100644
--- a/examples/state/sub_states.rs
+++ b/examples/state/sub_states.rs
@@ -43,7 +43,7 @@ fn main() {
         .add_systems(OnExit(AppState::Menu), cleanup_menu)
         .add_systems(OnEnter(AppState::InGame), setup_game)
         .add_systems(OnEnter(IsPaused::Paused), setup_paused_screen)
-        .add_state_bound::<IsPaused>()
+        .enable_state_bound_entities::<IsPaused>()
         .add_systems(
             Update,
             (

From 8ab70f0212c4235c051233dea80b2ef9b0fb6e09 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Mon, 3 Jun 2024 18:22:37 +0200
Subject: [PATCH 09/19] document event usage

---
 crates/bevy_state/src/state_bound.rs | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/crates/bevy_state/src/state_bound.rs b/crates/bevy_state/src/state_bound.rs
index 36414dabe6cfc..eeeb14ef8a3de 100644
--- a/crates/bevy_state/src/state_bound.rs
+++ b/crates/bevy_state/src/state_bound.rs
@@ -59,6 +59,9 @@ pub fn clear_state_bound_entities<S: States>(
     mut transitions: EventReader<StateTransitionEvent<S>>,
     query: Query<(Entity, &StateBound<S>)>,
 ) {
+    // We use the latest event, because state machine internals generate at most 1
+    // transition event (per type) each frame. No event means no change happened
+    // and we skip iterating all entities.
     let Some(transition) = transitions.read().last() else {
         return;
     };

From 4555dcff769e675f4d93dc14084b2b6bda23d19b Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Mon, 3 Jun 2024 18:28:38 +0200
Subject: [PATCH 10/19] rename StateBound to StateScoped

---
 crates/bevy_state/src/app.rs                   | 16 ++++++++--------
 crates/bevy_state/src/lib.rs                   |  6 +++---
 .../src/{state_bound.rs => state_scoped.rs}    | 18 +++++++++---------
 examples/state/computed_states.rs              | 18 +++++++++---------
 examples/state/sub_states.rs                   |  4 ++--
 5 files changed, 31 insertions(+), 31 deletions(-)
 rename crates/bevy_state/src/{state_bound.rs => state_scoped.rs} (77%)

diff --git a/crates/bevy_state/src/app.rs b/crates/bevy_state/src/app.rs
index 2f320ca359956..8750a861a1fbd 100644
--- a/crates/bevy_state/src/app.rs
+++ b/crates/bevy_state/src/app.rs
@@ -10,7 +10,7 @@ use crate::state::{
     StateTransition, StateTransitionEvent, StateTransitionSteps, States, SubStates,
 };
 #[cfg(feature = "bevy_hierarchy")]
-use crate::state_bound::clear_state_bound_entities;
+use crate::state_scoped::clear_state_scoped_entities;
 
 /// State installation methods for [`App`](bevy_app::App) and [`SubApp`](bevy_app::SubApp).
 pub trait AppExtStates {
@@ -52,10 +52,10 @@ pub trait AppExtStates {
     fn add_sub_state<S: SubStates>(&mut self) -> &mut Self;
 
     #[cfg(feature = "bevy_hierarchy")]
-    /// Enable state bound entity clearing for state `S`.
+    /// Enable state scoped entity clearing for state `S`.
     ///
-    /// For more information refer to [`StateBound`](crate::state_bound::StateBound).
-    fn enable_state_bound_entities<S: States>(&mut self) -> &mut Self;
+    /// For more information refer to [`StateScoped`](crate::state_scoped::StateScoped).
+    fn enable_state_scoped_entities<S: States>(&mut self) -> &mut Self;
 }
 
 impl AppExtStates for SubApp {
@@ -134,10 +134,10 @@ impl AppExtStates for SubApp {
     }
 
     #[cfg(feature = "bevy_hierarchy")]
-    fn enable_state_bound_entities<S: States>(&mut self) -> &mut Self {
+    fn enable_state_scoped_entities<S: States>(&mut self) -> &mut Self {
         self.add_systems(
             StateTransition,
-            clear_state_bound_entities::<S>.in_set(StateTransitionSteps::ExitSchedules),
+            clear_state_scoped_entities::<S>.in_set(StateTransitionSteps::ExitSchedules),
         )
     }
 }
@@ -164,8 +164,8 @@ impl AppExtStates for App {
     }
 
     #[cfg(feature = "bevy_hierarchy")]
-    fn enable_state_bound_entities<S: States>(&mut self) -> &mut Self {
-        self.main_mut().enable_state_bound_entities::<S>();
+    fn enable_state_scoped_entities<S: States>(&mut self) -> &mut Self {
+        self.main_mut().enable_state_scoped_entities::<S>();
         self
     }
 }
diff --git a/crates/bevy_state/src/lib.rs b/crates/bevy_state/src/lib.rs
index 497196970f898..4711b8682c553 100644
--- a/crates/bevy_state/src/lib.rs
+++ b/crates/bevy_state/src/lib.rs
@@ -35,8 +35,8 @@ pub mod condition;
 /// Provides definitions for the basic traits required by the state system
 pub mod state;
 #[cfg(feature = "bevy_hierarchy")]
-/// Provides [`StateBound`] and [`clear_state_bound_entities`] for managing lifetime of entities.
-pub mod state_bound;
+/// Provides [`StateScoped`] and [`clear_state_scoped_entities`] for managing lifetime of entities.
+pub mod state_scoped;
 
 /// Most commonly used re-exported types.
 pub mod prelude {
@@ -52,5 +52,5 @@ pub mod prelude {
     };
     #[cfg(feature = "bevy_hierarchy")]
     #[doc(hidden)]
-    pub use crate::state_bound::StateBound;
+    pub use crate::state_scoped::StateScoped;
 }
diff --git a/crates/bevy_state/src/state_bound.rs b/crates/bevy_state/src/state_scoped.rs
similarity index 77%
rename from crates/bevy_state/src/state_bound.rs
rename to crates/bevy_state/src/state_scoped.rs
index eeeb14ef8a3de..3427374b2385a 100644
--- a/crates/bevy_state/src/state_bound.rs
+++ b/crates/bevy_state/src/state_scoped.rs
@@ -11,8 +11,8 @@ use crate::state::{StateTransitionEvent, States};
 /// Entities marked with this component will be removed
 /// when the world's state of the matching type no longer matches the supplied value.
 ///
-/// To enable this feature remember configure your application
-/// with [`enable_state_bound_entities`](crate::app::AppExtStates::enable_state_bound_entities) on your state(s) of choice.
+/// To enable this feature remember to configure your application
+/// with [`enable_state_scoped_entities`](crate::app::AppExtStates::enable_state_scoped_entities) on your state(s) of choice.
 ///
 /// ```
 /// use bevy_state::prelude::*;
@@ -31,7 +31,7 @@ use crate::state::{StateTransitionEvent, States};
 ///
 /// fn spawn_player(mut commands: Commands) {
 ///     commands.spawn((
-///         StateBound(GameState::InGame),
+///         StateScoped(GameState::InGame),
 ///         Player
 ///     ));
 /// }
@@ -39,25 +39,25 @@ use crate::state::{StateTransitionEvent, States};
 /// # struct AppMock;
 /// # impl AppMock {
 /// #     fn init_state<S>(&mut self) {}
-/// #     fn add_state_bound<S>(&mut self) {}
+/// #     fn enable_state_scoped_entities<S>(&mut self) {}
 /// #     fn add_systems<S, M>(&mut self, schedule: S, systems: impl IntoSystemConfigs<M>) {}
 /// # }
 /// # struct Update;
 /// # let mut app = AppMock;
 ///
 /// app.init_state::<GameState>();
-/// app.add_state_bound::<GameState>();
+/// app.enable_state_scoped_entities::<GameState>();
 /// app.add_systems(OnEnter(GameState::InGame), spawn_player);
 /// ```
 #[derive(Component)]
-pub struct StateBound<S: States>(pub S);
+pub struct StateScoped<S: States>(pub S);
 
-/// Removes entities marked with [`StateBound<S>`]
+/// Removes entities marked with [`StateScoped<S>`]
 /// when their state no longer matches the world state.
-pub fn clear_state_bound_entities<S: States>(
+pub fn clear_state_scoped_entities<S: States>(
     mut commands: Commands,
     mut transitions: EventReader<StateTransitionEvent<S>>,
-    query: Query<(Entity, &StateBound<S>)>,
+    query: Query<(Entity, &StateScoped<S>)>,
 ) {
     // We use the latest event, because state machine internals generate at most 1
     // transition event (per type) each frame. No event means no change happened
diff --git a/examples/state/computed_states.rs b/examples/state/computed_states.rs
index cf1043f1d3853..e7378a201c4a7 100644
--- a/examples/state/computed_states.rs
+++ b/examples/state/computed_states.rs
@@ -186,7 +186,7 @@ fn main() {
         .add_systems(OnEnter(InGame), setup_game)
         // And we only want to run the [`clear_game`] function when we leave the [`AppState::InGame`] state, regardless
         // of whether we're paused.
-        .enable_state_bound_entities::<InGame>()
+        .enable_state_scoped_entities::<InGame>()
         // We want the color change, toggle_pause and quit_to_menu systems to ignore the paused condition, so we can use the [`InGame`] derived
         // state here as well.
         .add_systems(
@@ -200,15 +200,15 @@ fn main() {
         )
         // We can continue setting things up, following all the same patterns used above and in the `states` example.
         .add_systems(OnEnter(IsPaused::Paused), setup_paused_screen)
-        .enable_state_bound_entities::<IsPaused>()
+        .enable_state_scoped_entities::<IsPaused>()
         .add_systems(OnEnter(TurboMode), setup_turbo_text)
-        .enable_state_bound_entities::<TurboMode>()
+        .enable_state_scoped_entities::<TurboMode>()
         .add_systems(
             OnEnter(Tutorial::MovementInstructions),
             movement_instructions,
         )
         .add_systems(OnEnter(Tutorial::PauseInstructions), pause_instructions)
-        .enable_state_bound_entities::<Tutorial>()
+        .enable_state_scoped_entities::<Tutorial>()
         .add_systems(
             Update,
             (
@@ -422,7 +422,7 @@ mod ui {
 
     pub fn setup_game(mut commands: Commands, asset_server: Res<AssetServer>) {
         commands.spawn((
-            StateBound(InGame),
+            StateScoped(InGame),
             SpriteBundle {
                 texture: asset_server.load("branding/icon.png"),
                 ..default()
@@ -466,7 +466,7 @@ mod ui {
         info!("Printing Pause");
         commands
             .spawn((
-                StateBound(IsPaused::Paused),
+                StateScoped(IsPaused::Paused),
                 NodeBundle {
                     style: Style {
                         // center button
@@ -516,7 +516,7 @@ mod ui {
     pub fn setup_turbo_text(mut commands: Commands) {
         commands
             .spawn((
-                StateBound(TurboMode),
+                StateScoped(TurboMode),
                 NodeBundle {
                     style: Style {
                         // center button
@@ -558,7 +558,7 @@ mod ui {
     pub fn movement_instructions(mut commands: Commands) {
         commands
             .spawn((
-                StateBound(Tutorial::MovementInstructions),
+                StateScoped(Tutorial::MovementInstructions),
                 NodeBundle {
                     style: Style {
                         // center button
@@ -615,7 +615,7 @@ mod ui {
     pub fn pause_instructions(mut commands: Commands) {
         commands
             .spawn((
-                StateBound(Tutorial::PauseInstructions),
+                StateScoped(Tutorial::PauseInstructions),
                 NodeBundle {
                     style: Style {
                         // center button
diff --git a/examples/state/sub_states.rs b/examples/state/sub_states.rs
index 51a6027fad0f9..980d3614b4777 100644
--- a/examples/state/sub_states.rs
+++ b/examples/state/sub_states.rs
@@ -43,7 +43,7 @@ fn main() {
         .add_systems(OnExit(AppState::Menu), cleanup_menu)
         .add_systems(OnEnter(AppState::InGame), setup_game)
         .add_systems(OnEnter(IsPaused::Paused), setup_paused_screen)
-        .enable_state_bound_entities::<IsPaused>()
+        .enable_state_scoped_entities::<IsPaused>()
         .add_systems(
             Update,
             (
@@ -208,7 +208,7 @@ mod ui {
     pub fn setup_paused_screen(mut commands: Commands) {
         commands
             .spawn((
-                StateBound(IsPaused::Paused),
+                StateScoped(IsPaused::Paused),
                 NodeBundle {
                     style: Style {
                         // center button

From 586b564e0b6f0f42fa46a619ccabdf8a4815d4bd Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Mon, 3 Jun 2024 18:58:32 +0200
Subject: [PATCH 11/19] better log transition

---
 crates/bevy_state/src/state/transitions.rs | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/crates/bevy_state/src/state/transitions.rs b/crates/bevy_state/src/state/transitions.rs
index 6536558be00b6..3b315e26f7157 100644
--- a/crates/bevy_state/src/state/transitions.rs
+++ b/crates/bevy_state/src/state/transitions.rs
@@ -212,10 +212,11 @@ pub(crate) fn run_transition<S: States>(
 ///
 /// This system is provided to make debugging easier for Bevy developers.
 pub fn log_transitions<S: States>(mut transitions: EventReader<StateTransitionEvent<S>>) {
-    for transition in transitions.read() {
-        info!(
-            "Transition: {:?} => {:?}",
-            transition.exited, transition.entered
-        );
-    }
+    // State internals can generate at most one event (of type) per frame.
+    let Some(transition) = transitions.read().last() else {
+        return;
+    };
+    let name = std::any::type_name::<S>();
+    let StateTransitionEvent { exited, entered } = transition;
+    info!("{} transition: {:?} => {:?}", name, exited, entered);
 }

From 7015cfba0683d4ee527deb89b1ac1635be63a3d9 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Tue, 4 Jun 2024 00:10:49 +0200
Subject: [PATCH 12/19] fix state installation

---
 crates/bevy_state/src/app.rs | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/crates/bevy_state/src/app.rs b/crates/bevy_state/src/app.rs
index 8750a861a1fbd..1ca8dea0618a8 100644
--- a/crates/bevy_state/src/app.rs
+++ b/crates/bevy_state/src/app.rs
@@ -103,10 +103,13 @@ impl AppExtStates for SubApp {
             self.add_event::<StateTransitionEvent<S>>();
             let schedule = self.get_schedule_mut(StateTransition).unwrap();
             S::register_computed_state_systems(schedule);
-            let state = self.world().resource::<State<S>>().get().clone();
+            let state = self
+                .world()
+                .get_resource::<State<S>>()
+                .map(|s| s.get().clone());
             self.world_mut().send_event(StateTransitionEvent {
                 exited: None,
-                entered: Some(state),
+                entered: state,
             });
         }
 
@@ -123,10 +126,13 @@ impl AppExtStates for SubApp {
             self.add_event::<StateTransitionEvent<S>>();
             let schedule = self.get_schedule_mut(StateTransition).unwrap();
             S::register_sub_state_systems(schedule);
-            let state = self.world().resource::<State<S>>().get().clone();
+            let state = self
+                .world()
+                .get_resource::<State<S>>()
+                .map(|s| s.get().clone());
             self.world_mut().send_event(StateTransitionEvent {
                 exited: None,
-                entered: Some(state),
+                entered: state,
             });
         }
 

From 6b75951bf9c8e3f3c6b4e55110bbfd0bf66e871d Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Tue, 4 Jun 2024 00:12:05 +0200
Subject: [PATCH 13/19] Update crates/bevy_state/src/app.rs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: François Mockers <francois.mockers@vleue.com>
---
 crates/bevy_state/src/app.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/bevy_state/src/app.rs b/crates/bevy_state/src/app.rs
index 1ca8dea0618a8..6fe4cd8b878d4 100644
--- a/crates/bevy_state/src/app.rs
+++ b/crates/bevy_state/src/app.rs
@@ -52,7 +52,7 @@ pub trait AppExtStates {
     fn add_sub_state<S: SubStates>(&mut self) -> &mut Self;
 
     #[cfg(feature = "bevy_hierarchy")]
-    /// Enable state scoped entity clearing for state `S`.
+    /// Enable state-scoped entity clearing for state `S`.
     ///
     /// For more information refer to [`StateScoped`](crate::state_scoped::StateScoped).
     fn enable_state_scoped_entities<S: States>(&mut self) -> &mut Self;

From 745e13a9cc4a2df6c6c749a5b535ab1dc7522088 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Tue, 4 Jun 2024 00:26:26 +0200
Subject: [PATCH 14/19] move log_transitions to dev tools

---
 Cargo.toml                                 |  3 +++
 crates/bevy_dev_tools/Cargo.toml           |  1 +
 crates/bevy_dev_tools/src/lib.rs           |  2 ++
 crates/bevy_dev_tools/src/states.rs        | 18 ++++++++++++++++++
 crates/bevy_state/src/lib.rs               |  4 ++--
 crates/bevy_state/src/state/transitions.rs | 14 --------------
 examples/state/computed_states.rs          |  2 +-
 examples/state/state.rs                    |  2 +-
 examples/state/sub_states.rs               |  2 +-
 9 files changed, 29 insertions(+), 19 deletions(-)
 create mode 100644 crates/bevy_dev_tools/src/states.rs

diff --git a/Cargo.toml b/Cargo.toml
index 3dfdf3ec77203..1f2f3a2e87a97 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1774,6 +1774,7 @@ wasm = false
 name = "state"
 path = "examples/state/state.rs"
 doc-scrape-examples = true
+required-features = ["bevy_dev_tools"]
 
 [package.metadata.example.state]
 name = "State"
@@ -1785,6 +1786,7 @@ wasm = false
 name = "sub_states"
 path = "examples/state/sub_states.rs"
 doc-scrape-examples = true
+required-features = ["bevy_dev_tools"]
 
 [package.metadata.example.sub_states]
 name = "Sub States"
@@ -1796,6 +1798,7 @@ wasm = false
 name = "computed_states"
 path = "examples/state/computed_states.rs"
 doc-scrape-examples = true
+required-features = ["bevy_dev_tools"]
 
 [package.metadata.example.computed_states]
 name = "Computed States"
diff --git a/crates/bevy_dev_tools/Cargo.toml b/crates/bevy_dev_tools/Cargo.toml
index 4599c15ce924c..08b9f89e61eae 100644
--- a/crates/bevy_dev_tools/Cargo.toml
+++ b/crates/bevy_dev_tools/Cargo.toml
@@ -36,6 +36,7 @@ bevy_ui = { path = "../bevy_ui", version = "0.14.0-dev", features = [
 bevy_utils = { path = "../bevy_utils", version = "0.14.0-dev" }
 bevy_window = { path = "../bevy_window", version = "0.14.0-dev" }
 bevy_text = { path = "../bevy_text", version = "0.14.0-dev" }
+bevy_state = { path = "../bevy_state", version = "0.14.0-dev" }
 
 # other
 serde = { version = "1.0", features = ["derive"], optional = true }
diff --git a/crates/bevy_dev_tools/src/lib.rs b/crates/bevy_dev_tools/src/lib.rs
index 2c4c8fb396b8b..58c1e8c17f416 100644
--- a/crates/bevy_dev_tools/src/lib.rs
+++ b/crates/bevy_dev_tools/src/lib.rs
@@ -18,6 +18,8 @@ pub mod fps_overlay;
 #[cfg(feature = "bevy_ui_debug")]
 pub mod ui_debug_overlay;
 
+pub mod states;
+
 /// Enables developer tools in an [`App`]. This plugin is added automatically with `bevy_dev_tools`
 /// feature.
 ///
diff --git a/crates/bevy_dev_tools/src/states.rs b/crates/bevy_dev_tools/src/states.rs
new file mode 100644
index 0000000000000..a2cfc9d0c3fd0
--- /dev/null
+++ b/crates/bevy_dev_tools/src/states.rs
@@ -0,0 +1,18 @@
+//! Tools for debugging states.
+
+use bevy_ecs::event::EventReader;
+use bevy_state::state::{StateTransitionEvent, States};
+use bevy_utils::tracing::info;
+
+/// Logs state transitions into console.
+///
+/// This system is provided to make debugging easier for Bevy developers.
+pub fn log_transitions<S: States>(mut transitions: EventReader<StateTransitionEvent<S>>) {
+    // State internals can generate at most one event (of type) per frame.
+    let Some(transition) = transitions.read().last() else {
+        return;
+    };
+    let name = std::any::type_name::<S>();
+    let StateTransitionEvent { exited, entered } = transition;
+    info!("{} transition: {:?} => {:?}", name, exited, entered);
+}
diff --git a/crates/bevy_state/src/lib.rs b/crates/bevy_state/src/lib.rs
index 4711b8682c553..6579b971cad87 100644
--- a/crates/bevy_state/src/lib.rs
+++ b/crates/bevy_state/src/lib.rs
@@ -47,8 +47,8 @@ pub mod prelude {
     pub use crate::condition::*;
     #[doc(hidden)]
     pub use crate::state::{
-        log_transitions, ComputedStates, NextState, OnEnter, OnExit, OnTransition, State, StateSet,
-        StateTransition, StateTransitionEvent, States, SubStates,
+        ComputedStates, NextState, OnEnter, OnExit, OnTransition, State, StateSet, StateTransition,
+        StateTransitionEvent, States, SubStates,
     };
     #[cfg(feature = "bevy_hierarchy")]
     #[doc(hidden)]
diff --git a/crates/bevy_state/src/state/transitions.rs b/crates/bevy_state/src/state/transitions.rs
index 3b315e26f7157..b816b4ad173a3 100644
--- a/crates/bevy_state/src/state/transitions.rs
+++ b/crates/bevy_state/src/state/transitions.rs
@@ -8,7 +8,6 @@ use bevy_ecs::{
     system::{Commands, In, ResMut},
     world::World,
 };
-use bevy_utils::tracing::info;
 
 use super::{resources::State, states::States};
 
@@ -207,16 +206,3 @@ pub(crate) fn run_transition<S: States>(
 
     let _ = world.try_run_schedule(OnTransition { exited, entered });
 }
-
-/// Logs state transitions into console.
-///
-/// This system is provided to make debugging easier for Bevy developers.
-pub fn log_transitions<S: States>(mut transitions: EventReader<StateTransitionEvent<S>>) {
-    // State internals can generate at most one event (of type) per frame.
-    let Some(transition) = transitions.read().last() else {
-        return;
-    };
-    let name = std::any::type_name::<S>();
-    let StateTransitionEvent { exited, entered } = transition;
-    info!("{} transition: {:?} => {:?}", name, exited, entered);
-}
diff --git a/examples/state/computed_states.rs b/examples/state/computed_states.rs
index e7378a201c4a7..885c2f5801acb 100644
--- a/examples/state/computed_states.rs
+++ b/examples/state/computed_states.rs
@@ -16,7 +16,7 @@
 //! And lastly, we'll add [`Tutorial`], a computed state deriving from [`TutorialState`], [`InGame`] and [`IsPaused`], with 2 distinct
 //! states to display the 2 tutorial texts.
 
-use bevy::prelude::*;
+use bevy::{dev_tools::states::*, prelude::*};
 
 use ui::*;
 
diff --git a/examples/state/state.rs b/examples/state/state.rs
index 776f913543941..ef329b0baa6e4 100644
--- a/examples/state/state.rs
+++ b/examples/state/state.rs
@@ -5,7 +5,7 @@
 //!
 //! In this case, we're transitioning from a `Menu` state to an `InGame` state.
 
-use bevy::prelude::*;
+use bevy::{dev_tools::states::*, prelude::*};
 
 fn main() {
     App::new()
diff --git a/examples/state/sub_states.rs b/examples/state/sub_states.rs
index 980d3614b4777..1190315967194 100644
--- a/examples/state/sub_states.rs
+++ b/examples/state/sub_states.rs
@@ -7,7 +7,7 @@
 //! In this case, we're transitioning from a `Menu` state to an `InGame` state, at which point we create
 //! a substate called `IsPaused` to track whether the game is paused or not.
 
-use bevy::prelude::*;
+use bevy::{dev_tools::states::*, prelude::*};
 
 use ui::*;
 

From 6ebca650e2e490d9531425654c47003df3c76bf6 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Tue, 4 Jun 2024 00:33:58 +0200
Subject: [PATCH 15/19] warn if state isn't installed

---
 crates/bevy_state/src/app.rs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/crates/bevy_state/src/app.rs b/crates/bevy_state/src/app.rs
index 6fe4cd8b878d4..f3a7e6393af16 100644
--- a/crates/bevy_state/src/app.rs
+++ b/crates/bevy_state/src/app.rs
@@ -141,6 +141,15 @@ impl AppExtStates for SubApp {
 
     #[cfg(feature = "bevy_hierarchy")]
     fn enable_state_scoped_entities<S: States>(&mut self) -> &mut Self {
+        use bevy_utils::warn_once;
+
+        if !self
+            .world()
+            .contains_resource::<Events<StateTransitionEvent<S>>>()
+        {
+            let name = std::any::type_name::<S>();
+            warn_once!("State scoped entities are enabled for state `{}`, but the state isn't installed in the app!", name);
+        }
         self.add_systems(
             StateTransition,
             clear_state_scoped_entities::<S>.in_set(StateTransitionSteps::ExitSchedules),

From bcd03090c529122270a6ebfe477ba7816e340ccd Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Tue, 4 Jun 2024 00:36:36 +0200
Subject: [PATCH 16/19] normal warn it is

---
 crates/bevy_state/src/app.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_state/src/app.rs b/crates/bevy_state/src/app.rs
index f3a7e6393af16..befa4ddebf72b 100644
--- a/crates/bevy_state/src/app.rs
+++ b/crates/bevy_state/src/app.rs
@@ -141,14 +141,14 @@ impl AppExtStates for SubApp {
 
     #[cfg(feature = "bevy_hierarchy")]
     fn enable_state_scoped_entities<S: States>(&mut self) -> &mut Self {
-        use bevy_utils::warn_once;
+        use bevy_utils::tracing::warn;
 
         if !self
             .world()
             .contains_resource::<Events<StateTransitionEvent<S>>>()
         {
             let name = std::any::type_name::<S>();
-            warn_once!("State scoped entities are enabled for state `{}`, but the state isn't installed in the app!", name);
+            warn!("State scoped entities are enabled for state `{}`, but the state isn't installed in the app!", name);
         }
         self.add_systems(
             StateTransition,

From 3776d6e1fbf68a18b10dc9d73a228ddc6db8461e Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Tue, 4 Jun 2024 00:43:48 +0200
Subject: [PATCH 17/19] change how bevy_hierarchy affects state scope

---
 crates/bevy_state/src/lib.rs          | 3 +--
 crates/bevy_state/src/state_scoped.rs | 8 ++++++++
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_state/src/lib.rs b/crates/bevy_state/src/lib.rs
index 6579b971cad87..57ed083436cef 100644
--- a/crates/bevy_state/src/lib.rs
+++ b/crates/bevy_state/src/lib.rs
@@ -34,7 +34,7 @@ pub mod app;
 pub mod condition;
 /// Provides definitions for the basic traits required by the state system
 pub mod state;
-#[cfg(feature = "bevy_hierarchy")]
+
 /// Provides [`StateScoped`] and [`clear_state_scoped_entities`] for managing lifetime of entities.
 pub mod state_scoped;
 
@@ -50,7 +50,6 @@ pub mod prelude {
         ComputedStates, NextState, OnEnter, OnExit, OnTransition, State, StateSet, StateTransition,
         StateTransitionEvent, States, SubStates,
     };
-    #[cfg(feature = "bevy_hierarchy")]
     #[doc(hidden)]
     pub use crate::state_scoped::StateScoped;
 }
diff --git a/crates/bevy_state/src/state_scoped.rs b/crates/bevy_state/src/state_scoped.rs
index 3427374b2385a..5ca2b48ce9077 100644
--- a/crates/bevy_state/src/state_scoped.rs
+++ b/crates/bevy_state/src/state_scoped.rs
@@ -4,6 +4,7 @@ use bevy_ecs::{
     event::EventReader,
     system::{Commands, Query},
 };
+#[cfg(feature = "bevy_hierarchy")]
 use bevy_hierarchy::DespawnRecursiveExt;
 
 use crate::state::{StateTransitionEvent, States};
@@ -14,6 +15,8 @@ use crate::state::{StateTransitionEvent, States};
 /// To enable this feature remember to configure your application
 /// with [`enable_state_scoped_entities`](crate::app::AppExtStates::enable_state_scoped_entities) on your state(s) of choice.
 ///
+/// If `bevy_hierarchy` feature is enabled, which it is by default, the despawn will be recursive.
+///
 /// ```
 /// use bevy_state::prelude::*;
 /// use bevy_ecs::prelude::*;
@@ -54,6 +57,8 @@ pub struct StateScoped<S: States>(pub S);
 
 /// Removes entities marked with [`StateScoped<S>`]
 /// when their state no longer matches the world state.
+///
+/// If `bevy_hierarchy` feature is enabled, which it is by default, the despawn will be recursive.
 pub fn clear_state_scoped_entities<S: States>(
     mut commands: Commands,
     mut transitions: EventReader<StateTransitionEvent<S>>,
@@ -70,7 +75,10 @@ pub fn clear_state_scoped_entities<S: States>(
     };
     for (entity, binding) in &query {
         if binding.0 == *exited {
+            #[cfg(feature = "bevy_hierarchy")]
             commands.entity(entity).despawn_recursive();
+            #[cfg(not(feature = "bevy_hierarchy"))]
+            commands.entity(entity).despawn();
         }
     }
 }

From 64891614c46426e16004bf702cde7d22e342ee68 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Tue, 4 Jun 2024 00:45:45 +0200
Subject: [PATCH 18/19] document decisions

---
 crates/bevy_state/src/app.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/crates/bevy_state/src/app.rs b/crates/bevy_state/src/app.rs
index befa4ddebf72b..587cf9e29f28f 100644
--- a/crates/bevy_state/src/app.rs
+++ b/crates/bevy_state/src/app.rs
@@ -150,6 +150,8 @@ impl AppExtStates for SubApp {
             let name = std::any::type_name::<S>();
             warn!("State scoped entities are enabled for state `{}`, but the state isn't installed in the app!", name);
         }
+        // We work with [`StateTransition`] in set [`StateTransitionSteps::ExitSchedules`] as opposed to [`OnExit`],
+        // because [`OnExit`] only runs for one specific variant of the state.
         self.add_systems(
             StateTransition,
             clear_state_scoped_entities::<S>.in_set(StateTransitionSteps::ExitSchedules),

From 7df06b08fd8caeed057f5245480b9fc5cff076e0 Mon Sep 17 00:00:00 2001
From: MiniaczQ <xnetroidpl@gmail.com>
Date: Tue, 4 Jun 2024 13:24:35 +0200
Subject: [PATCH 19/19] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: François Mockers <francois.mockers@vleue.com>
---
 crates/bevy_dev_tools/src/states.rs | 2 +-
 crates/bevy_state/src/app.rs        | 3 ---
 2 files changed, 1 insertion(+), 4 deletions(-)

diff --git a/crates/bevy_dev_tools/src/states.rs b/crates/bevy_dev_tools/src/states.rs
index a2cfc9d0c3fd0..7e3aa237c60cf 100644
--- a/crates/bevy_dev_tools/src/states.rs
+++ b/crates/bevy_dev_tools/src/states.rs
@@ -6,7 +6,7 @@ use bevy_utils::tracing::info;
 
 /// Logs state transitions into console.
 ///
-/// This system is provided to make debugging easier for Bevy developers.
+/// This system is provided to make debugging easier by tracking state changes.
 pub fn log_transitions<S: States>(mut transitions: EventReader<StateTransitionEvent<S>>) {
     // State internals can generate at most one event (of type) per frame.
     let Some(transition) = transitions.read().last() else {
diff --git a/crates/bevy_state/src/app.rs b/crates/bevy_state/src/app.rs
index 587cf9e29f28f..2ff97f6ee517b 100644
--- a/crates/bevy_state/src/app.rs
+++ b/crates/bevy_state/src/app.rs
@@ -9,7 +9,6 @@ use crate::state::{
     setup_state_transitions_in_world, ComputedStates, FreelyMutableState, NextState, State,
     StateTransition, StateTransitionEvent, StateTransitionSteps, States, SubStates,
 };
-#[cfg(feature = "bevy_hierarchy")]
 use crate::state_scoped::clear_state_scoped_entities;
 
 /// State installation methods for [`App`](bevy_app::App) and [`SubApp`](bevy_app::SubApp).
@@ -51,7 +50,6 @@ pub trait AppExtStates {
     /// This method is idempotent: it has no effect when called again using the same generic type.
     fn add_sub_state<S: SubStates>(&mut self) -> &mut Self;
 
-    #[cfg(feature = "bevy_hierarchy")]
     /// Enable state-scoped entity clearing for state `S`.
     ///
     /// For more information refer to [`StateScoped`](crate::state_scoped::StateScoped).
@@ -139,7 +137,6 @@ impl AppExtStates for SubApp {
         self
     }
 
-    #[cfg(feature = "bevy_hierarchy")]
     fn enable_state_scoped_entities<S: States>(&mut self) -> &mut Self {
         use bevy_utils::tracing::warn;