49338245ea
# Objective This PR addresses one of the issues from [discord state discussion](https://discord.com/channels/691052431525675048/1237949214017716356). Same-state transitions can be desirable, so there should exist a hook for them. Fixes https://github.com/bevyengine/bevy/issues/9130. ## Solution - Allow `StateTransitionEvent<S>` to contain identity transitions. - Ignore identity transitions at schedule running level (`OnExit`, `OnTransition`, `OnEnter`). - Propagate identity transitions through `SubStates` and `ComputedStates`. - Add example about registering custom transition schedules. ## Changelog - `StateTransitionEvent<S>` can be emitted with same `exited` and `entered` state. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
88 lines
2.7 KiB
Rust
88 lines
2.7 KiB
Rust
use bevy_ecs::{
|
|
component::Component,
|
|
entity::Entity,
|
|
event::EventReader,
|
|
system::{Commands, Query},
|
|
};
|
|
#[cfg(feature = "bevy_hierarchy")]
|
|
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 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::*;
|
|
///
|
|
/// #[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((
|
|
/// StateScoped(GameState::InGame),
|
|
/// Player
|
|
/// ));
|
|
/// }
|
|
///
|
|
/// # struct AppMock;
|
|
/// # impl AppMock {
|
|
/// # fn init_state<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.enable_state_scoped_entities::<GameState>();
|
|
/// app.add_systems(OnEnter(GameState::InGame), spawn_player);
|
|
/// ```
|
|
#[derive(Component)]
|
|
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>>,
|
|
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
|
|
// 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 (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();
|
|
}
|
|
}
|
|
}
|