Always enable state scoped entities (#20883)

# Objective

- Reverts #16180
- Fixes #20866

## Solution

- Just enable state scoped entities all the time. No need to keep API
surface for disabling that tiiiiiny bit of overhead. If someone needs
this, we can still trivially add it back.

## Testing

- `bevy run --example state_scope`

---------

Co-authored-by: Alice Cecile <[email protected]>

Author: janhohenheim

crates/bevy_state/macros/src/states.rs

@@ -1,47 +1,12 @@
 use proc_macro::TokenStream;
 use quote::{format_ident, quote};
-use syn::{parse_macro_input, spanned::Spanned, DeriveInput, LitBool, Pat, Path, Result};
+use syn::{parse_macro_input, spanned::Spanned, DeriveInput, Pat, Path, Result};
 
 use crate::bevy_state_path;
 
-pub const STATES: &str = "states";
-pub const SCOPED_ENTITIES: &str = "scoped_entities";
-
-struct StatesAttrs {
-    scoped_entities_enabled: bool,
-}
-
-fn parse_states_attr(ast: &DeriveInput) -> Result<StatesAttrs> {
-    let mut attrs = StatesAttrs {
-        scoped_entities_enabled: true,
-    };
-
-    for attr in ast.attrs.iter() {
-        if attr.path().is_ident(STATES) {
-            attr.parse_nested_meta(|nested| {
-                if nested.path.is_ident(SCOPED_ENTITIES) {
-                    if let Ok(value) = nested.value() {
-                        attrs.scoped_entities_enabled = value.parse::<LitBool>()?.value();
-                    }
-                    Ok(())
-                } else {
-                    Err(nested.error("Unsupported attribute"))
-                }
-            })?;
-        }
-    }
-
-    Ok(attrs)
-}
-
 pub fn derive_states(input: TokenStream) -> TokenStream {
     let ast = parse_macro_input!(input as DeriveInput);
 
-    let attrs = match parse_states_attr(&ast) {
-        Ok(attrs) => attrs,
-        Err(e) => return e.into_compile_error().into(),
-    };
-
     let generics = ast.generics;
     let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
 
@@ -58,11 +23,8 @@ pub fn derive_states(input: TokenStream) -> TokenStream {
 
     let struct_name = &ast.ident;
 
-    let scoped_entities_enabled = attrs.scoped_entities_enabled;
-
     quote! {
         impl #impl_generics #trait_path for #struct_name #ty_generics #where_clause {
-            const SCOPED_ENTITIES_ENABLED: bool = #scoped_entities_enabled;
         }
 
         impl #impl_generics #state_mutation_trait_path for #struct_name #ty_generics #where_clause {
@@ -76,7 +38,7 @@ struct Source {
     source_value: Pat,
 }
 
-fn parse_sources_attr(ast: &DeriveInput) -> Result<(StatesAttrs, Source)> {
+fn parse_sources_attr(ast: &DeriveInput) -> Result<Source> {
     let mut result = ast
         .attrs
         .iter()
@@ -112,19 +74,16 @@ fn parse_sources_attr(ast: &DeriveInput) -> Result<(StatesAttrs, Source)> {
         ));
     }
 
-    let states_attrs = parse_states_attr(ast)?;
-
     let Some(result) = result.pop() else {
         return Err(syn::Error::new(ast.span(), "SubStates require a source"));
     };
 
-    Ok((states_attrs, result))
+    Ok(result)
 }
 
 pub fn derive_substates(input: TokenStream) -> TokenStream {
     let ast = parse_macro_input!(input as DeriveInput);
-    let (states_attrs, sources) =
-        parse_sources_attr(&ast).expect("Failed to parse substate sources");
+    let sources = parse_sources_attr(&ast).expect("Failed to parse substate sources");
 
     let generics = ast.generics;
     let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
@@ -155,8 +114,6 @@ pub fn derive_substates(input: TokenStream) -> TokenStream {
     let source_state_type = sources.source_type;
     let source_state_value = sources.source_value;
 
-    let scoped_entities_enabled = states_attrs.scoped_entities_enabled;
-
     let result = quote! {
         impl #impl_generics #trait_path for #struct_name #ty_generics #where_clause {
             type SourceStates = #source_state_type;
@@ -168,8 +125,6 @@ pub fn derive_substates(input: TokenStream) -> TokenStream {
 
         impl #impl_generics #state_trait_path for #struct_name #ty_generics #where_clause {
             const DEPENDENCY_DEPTH : usize = <Self as #trait_path>::SourceStates::SET_DEPENDENCY_DEPTH + 1;
-
-            const SCOPED_ENTITIES_ENABLED: bool = #scoped_entities_enabled;
         }
 
         impl #impl_generics #state_mutation_trait_path for #struct_name #ty_generics #where_clause {

crates/bevy_state/src/app.rs

@@ -59,11 +59,12 @@ pub trait AppExtStates {
 
     /// Enable state-scoped entity clearing for state `S`.
     ///
-    /// This is enabled by default. If you don't want this behavior, add the `#[states(scoped_entities = false)]`
-    /// attribute when deriving the [`States`] trait.
-    ///
-    /// For more information refer to [`crate::state_scoped`].
+    /// Since state scoped entities are enabled by default, this method does nothing anymore.
     #[doc(hidden)]
+    #[deprecated(
+        since = "0.17.0",
+        note = "State scoped entities are enabled by default. This method does nothing anymore, you can safely remove it."
+    )]
     fn enable_state_scoped_entities<S: States>(&mut self) -> &mut Self;
 
     #[cfg(feature = "bevy_reflect")]
@@ -111,9 +112,7 @@ impl AppExtStates for SubApp {
                 exited: None,
                 entered: Some(state),
             });
-            if S::SCOPED_ENTITIES_ENABLED {
-                self.enable_state_scoped_entities::<S>();
-            }
+            enable_state_scoped_entities::<S>(self);
         } else {
             let name = core::any::type_name::<S>();
             warn!("State {name} is already initialized.");
@@ -136,9 +135,7 @@ impl AppExtStates for SubApp {
                 exited: None,
                 entered: Some(state),
             });
-            if S::SCOPED_ENTITIES_ENABLED {
-                self.enable_state_scoped_entities::<S>();
-            }
+            enable_state_scoped_entities::<S>(self);
         } else {
             // Overwrite previous state and initial event
             self.insert_resource::<State<S>>(State::new(state.clone()));
@@ -173,9 +170,7 @@ impl AppExtStates for SubApp {
                 exited: None,
                 entered: state,
             });
-            if S::SCOPED_ENTITIES_ENABLED {
-                self.enable_state_scoped_entities::<S>();
-            }
+            enable_state_scoped_entities::<S>(self);
         } else {
             let name = core::any::type_name::<S>();
             warn!("Computed state {name} is already initialized.");
@@ -204,9 +199,7 @@ impl AppExtStates for SubApp {
                 exited: None,
                 entered: state,
             });
-            if S::SCOPED_ENTITIES_ENABLED {
-                self.enable_state_scoped_entities::<S>();
-            }
+            enable_state_scoped_entities::<S>(self);
         } else {
             let name = core::any::type_name::<S>();
             warn!("Sub state {name} is already initialized.");
@@ -217,28 +210,7 @@ impl AppExtStates for SubApp {
 
     #[doc(hidden)]
     fn enable_state_scoped_entities<S: States>(&mut self) -> &mut Self {
-        if !self
-            .world()
-            .contains_resource::<Events<StateTransitionEvent<S>>>()
-        {
-            let name = core::any::type_name::<S>();
-            warn!("State scoped entities are enabled for state `{name}`, but the state isn't installed in the app!");
-        }
-
-        // Note: We work with `StateTransition` in set
-        // `StateTransitionSystems::ExitSchedules` rather than `OnExit`, because
-        // `OnExit` only runs for one specific variant of the state.
-        self.add_systems(
-            StateTransition,
-            despawn_entities_on_exit_state::<S>.in_set(StateTransitionSystems::ExitSchedules),
-        )
-        // Note: We work with `StateTransition` in set
-        // `StateTransitionSystems::EnterSchedules` rather than `OnEnter`, because
-        // `OnEnter` only runs for one specific variant of the state.
-        .add_systems(
-            StateTransition,
-            despawn_entities_on_enter_state::<S>.in_set(StateTransitionSystems::EnterSchedules),
-        )
+        self
     }
 
     #[cfg(feature = "bevy_reflect")]
@@ -266,6 +238,31 @@ impl AppExtStates for SubApp {
     }
 }
 
+fn enable_state_scoped_entities<S: States>(app: &mut SubApp) {
+    if !app
+        .world()
+        .contains_resource::<Events<StateTransitionEvent<S>>>()
+    {
+        let name = core::any::type_name::<S>();
+        warn!("State scoped entities are enabled for state `{name}`, but the state wasn't initialized in the app!");
+    }
+
+    // Note: We work with `StateTransition` in set
+    // `StateTransitionSystems::ExitSchedules` rather than `OnExit`, because
+    // `OnExit` only runs for one specific variant of the state.
+    app.add_systems(
+        StateTransition,
+        despawn_entities_on_exit_state::<S>.in_set(StateTransitionSystems::ExitSchedules),
+    )
+    // Note: We work with `StateTransition` in set
+    // `StateTransitionSystems::EnterSchedules` rather than `OnEnter`, because
+    // `OnEnter` only runs for one specific variant of the state.
+    .add_systems(
+        StateTransition,
+        despawn_entities_on_enter_state::<S>.in_set(StateTransitionSystems::EnterSchedules),
+    );
+}
+
 impl AppExtStates for App {
     fn init_state<S: FreelyMutableState + FromWorld>(&mut self) -> &mut Self {
         self.main_mut().init_state::<S>();
@@ -289,7 +286,6 @@ impl AppExtStates for App {
 
     #[doc(hidden)]
     fn enable_state_scoped_entities<S: States>(&mut self) -> &mut Self {
-        self.main_mut().enable_state_scoped_entities::<S>();
         self
     }
 

crates/bevy_state/src/state/computed_states.rs

@@ -91,8 +91,6 @@ pub trait ComputedStates: 'static + Send + Sync + Clone + PartialEq + Eq + Hash
 
 impl<S: ComputedStates> States for S {
     const DEPENDENCY_DEPTH: usize = S::SourceStates::SET_DEPENDENCY_DEPTH + 1;
-
-    const SCOPED_ENTITIES_ENABLED: bool = true;
 }
 
 #[cfg(test)]

crates/bevy_state/src/state/states.rs

@@ -66,12 +66,4 @@ pub trait States: 'static + Send + Sync + Clone + PartialEq + Eq + Hash + Debug
     /// Used to help order transitions and de-duplicate [`ComputedStates`](crate::state::ComputedStates), as well as prevent cyclical
     /// `ComputedState` dependencies.
     const DEPENDENCY_DEPTH: usize = 1;
-
-    /// Should [state scoping](crate::state_scoped) be enabled for this state?
-    /// If set to `true`, the
-    /// [`DespawnOnEnter`](crate::state_scoped::DespawnOnEnter) and
-    /// [`DespawnOnExit`](crate::state_scoped::DespawnOnExit)
-    /// components are used to remove entities when entering or exiting the
-    /// state.
-    const SCOPED_ENTITIES_ENABLED: bool = false;
 }

crates/bevy_state/src/state_scoped.rs

@@ -92,9 +92,6 @@ pub fn despawn_entities_on_exit_state<S: States>(
 /// Entities marked with this component will be despawned
 /// upon entering the given state.
 ///
-/// 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::*;
 /// use bevy_ecs::{prelude::*, system::ScheduleSystem};

release-content/migration-guides/state_scoped_entities_by_default.md

@@ -1,10 +1,9 @@
 ---
-title: Entities are now state scoped by default
-pull_requests: [19354]
+title: State-scoped entities are now always enabled implicitly
+pull_requests: [19354, 20883]
 ---
 
-State scoped entities is now enabled by default, and you don't need to call `app.enable_state_scoped_entities::<State>()` anymore.
+State scoped entities is now always enabled, and as a consequence, `app.enable_state_scoped_entities::<State>()` is no longer needed.
+It has been marked as deprecated and does nothing when called.
 
-If you were previously adding the `#[states(scoped_entities)]` attribute when deriving the `States` trait, you can remove it.
-
-If you want to keep the previous behavior, you must add the attribute `#[states(scoped_entities = false)]`.
+The attribute `#[states(scoped_entities)]` has been removed. You can safely remove it from your code without replacement.