Move utilities from examples to bevy_state and add concept of state-scoped entities

crates/bevy_state/Cargo.toml

@@ -12,16 +12,18 @@ 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" }
 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

crates/bevy_state/src/app.rs

@@ -1,10 +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,
+    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 {
@@ -44,6 +50,12 @@ 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 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,14 @@ impl AppExtStates for SubApp {
 
         self
     }
+
+    #[cfg(feature = "bevy_hierarchy")]
+    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 +162,12 @@ impl AppExtStates for App {
         self.main_mut().add_sub_state::<S>();
         self
     }
+
+    #[cfg(feature = "bevy_hierarchy")]
+    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.

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::StateBound;
 }

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>>) {

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,15 @@ 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>>) {
+    for transition in transitions.read() {
+        info!(
+            "Transition: {:?} => {:?}",
+            transition.exited, transition.entered
+        );
+    }
+}

crates/bevy_state/src/state_bound.rs

@@ -0,0 +1,73 @@
+use bevy_ecs::{
+    component::Component,
+    entity::Entity,
+    event::EventReader,
+    system::{Commands, Query},
+};
+use bevy_hierarchy::DespawnRecursiveExt;
+
+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.
+///
+/// ```
+/// use bevy_state::prelude::*;
+/// use bevy_ecs::prelude::*;
+///
+/// #[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 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;
+/// # let mut app = AppMock;
+///
+/// app.init_state::<GameState>();
+/// app.add_state_bound::<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>(
+    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();
+        }
+    }
+}

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,26 +200,22 @@ 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_state_bound::<Tutorial>()
         .add_systems(
-            OnExit(Tutorial::MovementInstructions),
-            clear_state_bound_entities(Tutorial::MovementInstructions),
-        )
-        .add_systems(
-            OnExit(Tutorial::PauseInstructions),
-            clear_state_bound_entities(Tutorial::PauseInstructions),
+            Update,
+            (
+                log_transitions::<AppState>,
+                log_transitions::<TutorialState>,
+            ),
         )
-        .add_systems(Update, log_transitions)
         .run();
 }
 
@@ -277,22 +273,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 +309,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::*;
 

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
-        );
-    }
-}

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,
             (
@@ -59,7 +56,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 +139,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::*;