7a1fcb7fe7
# Objective - Alternative to and builds on top of #16284. - Fixes #15849. ## Solution - Rename component `StateScoped` to `DespawnOnExitState`. - Rename system `clear_state_scoped_entities` to `despawn_entities_on_exit_state`. - Add `DespawnOnEnterState` and `despawn_entities_on_enter_state` which is the `OnEnter` equivalent. > [!NOTE] > Compared to #16284, the main change is that I did the rename in such a way as to keep the terms `OnExit` and `OnEnter` together. In my own game, I was adding `VisibleOnEnterState` and `HiddenOnExitState` and when naming those, I kept the `OnExit` and `OnEnter` together. When I checked #16284 it stood out to me that the naming was a bit awkward. Putting the `State` in the middle and breaking up `OnEnter` and `OnExit` also breaks searching for those terms. ## Open questions 1. Should we split `enable_state_scoped_entities` into two functions, one for the `OnEnter` and one for the `OnExit`? I personally have zero need thus far for the `OnEnter` version, so I'd be interested in not having this enabled unless I ask for it. 2. If yes to 1., should we follow my lead in my `Visibility` state components (see below) and name these `app.enable_despawn_entities_on_enter_state()` and `app.enable_despawn_entities_on_exit_state()`, which IMO says what it does on the tin? ## Testing Ran all changed examples. ## Side note: `VisibleOnEnterState` and `HiddenOnExitState` For reference to anyone else and to help with the open questions, I'm including the code I wrote for controlling entity visibility when a state is entered/exited. <details> <summary>visibility.rs</summary> ```rust use bevy_app::prelude::*; use bevy_ecs::prelude::*; use bevy_reflect::prelude::*; use bevy_render::prelude::*; use bevy_state::{prelude::*, state::StateTransitionSteps}; use tracing::*; pub trait AppExtStates { fn enable_visible_entities_on_enter_state<S: States>(&mut self) -> &mut Self; fn enable_hidden_entities_on_exit_state<S: States>(&mut self) -> &mut Self; } impl AppExtStates for App { fn enable_visible_entities_on_enter_state<S: States>(&mut self) -> &mut Self { self.main_mut() .enable_visible_entities_on_enter_state::<S>(); self } fn enable_hidden_entities_on_exit_state<S: States>(&mut self) -> &mut Self { self.main_mut().enable_hidden_entities_on_exit_state::<S>(); self } } impl AppExtStates for SubApp { fn enable_visible_entities_on_enter_state<S: States>(&mut self) -> &mut Self { if !self .world() .contains_resource::<Events<StateTransitionEvent<S>>>() { let name = core::any::type_name::<S>(); warn!("Visible entities on enter state 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, update_to_visible_on_enter_state::<S>.in_set(StateTransitionSteps::ExitSchedules), ) } fn enable_hidden_entities_on_exit_state<S: States>(&mut self) -> &mut Self { if !self .world() .contains_resource::<Events<StateTransitionEvent<S>>>() { let name = core::any::type_name::<S>(); warn!("Hidden entities on exit state 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, update_to_hidden_on_exit_state::<S>.in_set(StateTransitionSteps::ExitSchedules), ) } } #[derive(Clone, Component, Debug, Reflect)] #[reflect(Component, Debug)] pub struct VisibleOnEnterState<S: States>(pub S); #[derive(Clone, Component, Debug, Reflect)] #[reflect(Component, Debug)] pub struct HiddenOnExitState<S: States>(pub S); /// Makes entities marked with [`VisibleOnEnterState<S>`] visible when the state /// `S` is entered. pub fn update_to_visible_on_enter_state<S: States>( mut transitions: EventReader<StateTransitionEvent<S>>, mut query: Query<(&VisibleOnEnterState<S>, &mut Visibility)>, ) { // 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; }; if transition.entered == transition.exited { return; } let Some(entered) = &transition.entered else { return; }; for (binding, mut visibility) in query.iter_mut() { if binding.0 == *entered { visibility.set_if_neq(Visibility::Visible); } } } /// Makes entities marked with [`HiddenOnExitState<S>`] invisible when the state /// `S` is exited. pub fn update_to_hidden_on_exit_state<S: States>( mut transitions: EventReader<StateTransitionEvent<S>>, mut query: Query<(&HiddenOnExitState<S>, &mut Visibility)>, ) { // 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; }; if transition.entered == transition.exited { return; } let Some(exited) = &transition.exited else { return; }; for (binding, mut visibility) in query.iter_mut() { if binding.0 == *exited { visibility.set_if_neq(Visibility::Hidden); } } } ``` </details> --------- Co-authored-by: Benjamin Brienen <Benjamin.Brienen@outlook.com> Co-authored-by: Ben Frankel <ben.frankel7@gmail.com>
76 lines
3.0 KiB
Rust
76 lines
3.0 KiB
Rust
use core::fmt::Debug;
|
|
|
|
use core::hash::Hash;
|
|
|
|
/// Types that can define world-wide states in a finite-state machine.
|
|
///
|
|
/// The [`Default`] trait defines the starting state.
|
|
/// Multiple states can be defined for the same world,
|
|
/// allowing you to classify the state of the world across orthogonal dimensions.
|
|
/// You can access the current state of type `T` with the [`State<T>`](crate::state::State) resource,
|
|
/// and the queued state with the [`NextState<T>`](crate::state::NextState) resource.
|
|
///
|
|
/// State transitions typically occur in the [`OnEnter<T::Variant>`](crate::state::OnEnter) and [`OnExit<T::Variant>`](crate::state::OnExit) schedules,
|
|
/// which can be run by triggering the [`StateTransition`](crate::state::StateTransition) schedule.
|
|
///
|
|
/// Types used as [`ComputedStates`](crate::state::ComputedStates) do not need to and should not derive [`States`].
|
|
/// [`ComputedStates`](crate::state::ComputedStates) should not be manually mutated: functionality provided
|
|
/// by the [`States`] derive and the associated [`FreelyMutableState`](crate::state::FreelyMutableState) trait.
|
|
///
|
|
/// # Example
|
|
///
|
|
/// ```
|
|
/// use bevy_state::prelude::*;
|
|
/// use bevy_ecs::prelude::IntoScheduleConfigs;
|
|
/// use bevy_ecs::system::{ResMut, ScheduleSystem};
|
|
///
|
|
///
|
|
/// #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default, States)]
|
|
/// enum GameState {
|
|
/// #[default]
|
|
/// MainMenu,
|
|
/// SettingsMenu,
|
|
/// InGame,
|
|
/// }
|
|
///
|
|
/// fn handle_escape_pressed(mut next_state: ResMut<NextState<GameState>>) {
|
|
/// # let escape_pressed = true;
|
|
/// if escape_pressed {
|
|
/// next_state.set(GameState::SettingsMenu);
|
|
/// }
|
|
/// }
|
|
///
|
|
/// fn open_settings_menu() {
|
|
/// // Show the settings menu...
|
|
/// }
|
|
///
|
|
/// # struct AppMock;
|
|
/// # impl AppMock {
|
|
/// # fn add_systems<S, M>(&mut self, schedule: S, systems: impl IntoScheduleConfigs<ScheduleSystem, M>) {}
|
|
/// # }
|
|
/// # struct Update;
|
|
/// # let mut app = AppMock;
|
|
///
|
|
/// app.add_systems(Update, handle_escape_pressed.run_if(in_state(GameState::MainMenu)));
|
|
/// app.add_systems(OnEnter(GameState::SettingsMenu), open_settings_menu);
|
|
/// ```
|
|
#[diagnostic::on_unimplemented(
|
|
message = "`{Self}` can not be used as a state",
|
|
label = "invalid state",
|
|
note = "consider annotating `{Self}` with `#[derive(States)]`"
|
|
)]
|
|
pub trait States: 'static + Send + Sync + Clone + PartialEq + Eq + Hash + Debug {
|
|
/// How many other states this state depends on.
|
|
/// 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
|
|
/// [`DespawnOnEnterState`](crate::state_scoped::DespawnOnEnterState) and
|
|
/// [`DespawnOnExitState`](crate::state_scoped::DespawnOnEnterState)
|
|
/// components are used to remove entities when entering or exiting the
|
|
/// state.
|
|
const SCOPED_ENTITIES_ENABLED: bool = false;
|
|
}
|