mirror of
https://github.com/bevyengine/bevy
synced 2025-01-03 00:38:56 +00:00
6314f50e7b
# Objective Implementing `States` manually is repetitive, so let's not. One thing I'm unsure of is whether the macro import statement is in the right place.
108 lines
4.1 KiB
Rust
108 lines
4.1 KiB
Rust
use std::fmt::Debug;
|
|
use std::hash::Hash;
|
|
use std::mem;
|
|
|
|
use crate as bevy_ecs;
|
|
use crate::schedule::{ScheduleLabel, SystemSet};
|
|
use crate::system::Resource;
|
|
use crate::world::World;
|
|
|
|
pub use bevy_ecs_macros::States;
|
|
|
|
/// 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>`] resource,
|
|
/// and the queued state with the [`NextState<T>`] resource.
|
|
///
|
|
/// State transitions typically occur in the [`OnEnter<T::Variant>`] and [`OnExit<T:Varaitn>`] schedules,
|
|
/// which can be run via the [`apply_state_transition::<T>`] system.
|
|
/// Systems that run each frame in various states are typically stored in the main schedule,
|
|
/// and are conventionally part of the [`OnUpdate(T::Variant)`] system set.
|
|
///
|
|
/// # Example
|
|
///
|
|
/// ```rust
|
|
/// use bevy_ecs::prelude::States;
|
|
///
|
|
/// #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default, States)]
|
|
/// enum GameState {
|
|
/// #[default]
|
|
/// MainMenu,
|
|
/// SettingsMenu,
|
|
/// InGame,
|
|
/// }
|
|
///
|
|
/// ```
|
|
pub trait States: 'static + Send + Sync + Clone + PartialEq + Eq + Hash + Debug + Default {
|
|
type Iter: Iterator<Item = Self>;
|
|
|
|
/// Returns an iterator over all the state variants.
|
|
fn variants() -> Self::Iter;
|
|
}
|
|
|
|
/// The label of a [`Schedule`](super::Schedule) that runs whenever [`State<S>`]
|
|
/// enters this state.
|
|
#[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
|
|
pub struct OnEnter<S: States>(pub S);
|
|
|
|
/// The label of a [`Schedule`](super::Schedule) that runs whenever [`State<S>`]
|
|
/// exits this state.
|
|
#[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
|
|
pub struct OnExit<S: States>(pub S);
|
|
|
|
/// A [`SystemSet`] that will run within `CoreSet::StateTransitions` when this state is active.
|
|
///
|
|
/// This is provided for convenience. A more general [`state_equals`](crate::schedule::common_conditions::state_equals)
|
|
/// [condition](super::Condition) also exists for systems that need to run elsewhere.
|
|
#[derive(SystemSet, Clone, Debug, PartialEq, Eq, Hash)]
|
|
pub struct OnUpdate<S: States>(pub S);
|
|
|
|
/// A finite-state machine whose transitions have associated schedules
|
|
/// ([`OnEnter(state)`] and [`OnExit(state)`]).
|
|
///
|
|
/// The current state value can be accessed through this resource. To *change* the state,
|
|
/// queue a transition in the [`NextState<S>`] resource, and it will be applied by the next
|
|
/// [`apply_state_transition::<S>`] system.
|
|
///
|
|
/// The starting state is defined via the [`Default`] implementation for `S`.
|
|
#[derive(Resource, Default)]
|
|
pub struct State<S: States>(pub S);
|
|
|
|
/// The next state of [`State<S>`].
|
|
///
|
|
/// To queue a transition, just set the contained value to `Some(next_state)`.
|
|
/// Note that these transitions can be overriden by other systems:
|
|
/// only the actual value of this resource at the time of [`apply_state_transition`] matters.
|
|
#[derive(Resource, Default)]
|
|
pub struct NextState<S: States>(pub Option<S>);
|
|
|
|
impl<S: States> NextState<S> {
|
|
/// Tentatively set a planned state transition to `Some(state)`.
|
|
pub fn set(&mut self, state: S) {
|
|
self.0 = Some(state);
|
|
}
|
|
}
|
|
|
|
/// Run the enter schedule for the current state
|
|
pub fn run_enter_schedule<S: States>(world: &mut World) {
|
|
world.run_schedule(OnEnter(world.resource::<State<S>>().0.clone()));
|
|
}
|
|
|
|
/// If a new state is queued in [`NextState<S>`], this system:
|
|
/// - Takes the new state value from [`NextState<S>`] and updates [`State<S>`].
|
|
/// - Runs the [`OnExit(exited_state)`] schedule.
|
|
/// - Runs the [`OnEnter(entered_state)`] schedule.
|
|
pub fn apply_state_transition<S: States>(world: &mut World) {
|
|
if world.resource::<NextState<S>>().0.is_some() {
|
|
let entered_state = world.resource_mut::<NextState<S>>().0.take().unwrap();
|
|
let exited_state = mem::replace(
|
|
&mut world.resource_mut::<State<S>>().0,
|
|
entered_state.clone(),
|
|
);
|
|
world.run_schedule(OnExit(exited_state));
|
|
world.run_schedule(OnEnter(entered_state));
|
|
}
|
|
}
|