Computed State & Sub States

Cargo.toml

@@ -1505,6 +1505,17 @@ description = "Illustrates how to use States to control transitioning from a Men
 category = "ECS (Entity Component System)"
 wasm = false
 
+[[example]]
+name = "computed_states"
+path = "examples/ecs/computed_states.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.computed_states]
+name = "Computed States"
+description = "Advanced state patterns using Computed States"
+category = "ECS (Entity Component System)"
+wasm = false
+
 [[example]]
 name = "system_piping"
 path = "examples/ecs/system_piping.rs"

crates/bevy_app/src/app.rs

@@ -1,10 +1,11 @@
-use crate::{First, Main, MainSchedulePlugin, Plugin, Plugins, StateTransition};
+use crate::{First, Main, MainSchedulePlugin, Plugin, Plugins};
 pub use bevy_derive::AppLabel;
 use bevy_ecs::{
     prelude::*,
     schedule::{
         apply_state_transition, common_conditions::run_once as run_once_condition,
-        run_enter_schedule, InternedScheduleLabel, IntoSystemConfigs, IntoSystemSetConfigs,
+        run_enter_schedule, setup_state_transitions_in_world, ComputedStates, FreelyMutableState,
+        InternedScheduleLabel, IntoSystemConfigs, IntoSystemSetConfigs, ManualStateTransitions,
         ScheduleBuildSettings, ScheduleLabel, StateTransitionEvent,
     },
 };
@@ -354,23 +355,24 @@ impl App {
     ///
     /// Adds [`State<S>`] and [`NextState<S>`] resources, [`OnEnter`] and [`OnExit`] schedules
     /// for each state variant (if they don't already exist), an instance of [`apply_state_transition::<S>`] in
-    /// [`StateTransition`] so that transitions happen before [`Update`](crate::Update) and
-    /// a instance of [`run_enter_schedule::<S>`] in [`StateTransition`] with a
+    /// [`ManualStateTransitions`] so that transitions happen before [`Update`](crate::Update) and
+    /// a instance of [`run_enter_schedule::<S>`] in [`ManualStateTransitions`] with a
     /// [`run_once`](`run_once_condition`) condition to run the on enter schedule of the
     /// initial state.
     ///
     /// If you would like to control how other systems run based on the current state,
     /// you can emulate this behavior using the [`in_state`] [`Condition`].
     ///
     /// Note that you can also apply state transitions at other points in the schedule
-    /// by adding the [`apply_state_transition`] system manually.
-    pub fn init_state<S: States + FromWorld>(&mut self) -> &mut Self {
+    /// by triggering the [`StateTransition`](`bevy_ecs::schedule::StateTransition`) schedule manually.
+    pub fn init_state<S: FreelyMutableState + FromWorld>(&mut self) -> &mut Self {
         if !self.world.contains_resource::<State<S>>() {
+            setup_state_transitions_in_world(&mut self.world);
             self.init_resource::<State<S>>()
                 .init_resource::<NextState<S>>()
                 .add_event::<StateTransitionEvent<S>>()
                 .add_systems(
-                    StateTransition,
+                    ManualStateTransitions,
                     (
                         run_enter_schedule::<S>.run_if(run_once_condition()),
                         apply_state_transition::<S>,
@@ -391,22 +393,23 @@ impl App {
     ///
     /// Adds [`State<S>`] and [`NextState<S>`] resources, [`OnEnter`] and [`OnExit`] schedules
     /// for each state variant (if they don't already exist), an instance of [`apply_state_transition::<S>`] in
-    /// [`StateTransition`] so that transitions happen before [`Update`](crate::Update) and
-    /// a instance of [`run_enter_schedule::<S>`] in [`StateTransition`] with a
+    /// [`ManualStateTransitions`] so that transitions happen before [`Update`](crate::Update) and
+    /// a instance of [`run_enter_schedule::<S>`] in [`ManualStateTransitions`] with a
     /// [`run_once`](`run_once_condition`) condition to run the on enter schedule of the
     /// initial state.
     ///
     /// If you would like to control how other systems run based on the current state,
     /// you can emulate this behavior using the [`in_state`] [`Condition`].
     ///
     /// Note that you can also apply state transitions at other points in the schedule
-    /// by adding the [`apply_state_transition`] system manually.
-    pub fn insert_state<S: States>(&mut self, state: S) -> &mut Self {
+    /// by triggering the [`StateTransition`](`bevy_ecs::schedule::StateTransition`) schedule manually.
+    pub fn insert_state<S: FreelyMutableState>(&mut self, state: S) -> &mut Self {
+        setup_state_transitions_in_world(&mut self.world);
         self.insert_resource(State::new(state))
             .init_resource::<NextState<S>>()
             .add_event::<StateTransitionEvent<S>>()
             .add_systems(
-                StateTransition,
+                ManualStateTransitions,
                 (
                     run_enter_schedule::<S>.run_if(run_once_condition()),
                     apply_state_transition::<S>,
@@ -421,6 +424,26 @@ impl App {
         self
     }
 
+    /// Sets up a type implementing [`ComputedStates`].
+    ///
+    /// This method is idempotent: it has no effect when called again using the same generic type.
+    ///
+    /// For each source state the derived state depends on, it adds this state's derivation
+    /// to it's [`ComputeDependantStates<Source>`](bevy_ecs::schedule::ComputeDependantStates<S>) schedule.
+    pub fn add_computed_state<S: ComputedStates>(&mut self) -> &mut Self {
+        if !self
+            .world
+            .contains_resource::<Events<StateTransitionEvent<S>>>()
+        {
+            setup_state_transitions_in_world(&mut self.world);
+            self.add_event::<StateTransitionEvent<S>>();
+            let mut schedules = self.world.resource_mut::<Schedules>();
+            S::register_state_compute_systems_in_schedule(schedules.as_mut());
+        }
+
+        self
+    }
+
     /// Adds a system to the given schedule in this app's [`Schedules`].
     ///
     /// # Examples

crates/bevy_app/src/lib.rs

@@ -25,8 +25,7 @@ pub mod prelude {
         app::App,
         main_schedule::{
             First, FixedFirst, FixedLast, FixedPostUpdate, FixedPreUpdate, FixedUpdate, Last, Main,
-            PostStartup, PostUpdate, PreStartup, PreUpdate, SpawnScene, Startup, StateTransition,
-            Update,
+            PostStartup, PostUpdate, PreStartup, PreUpdate, SpawnScene, Startup, Update,
         },
         DynamicPlugin, Plugin, PluginGroup,
     };

crates/bevy_app/src/main_schedule.rs

@@ -1,6 +1,6 @@
 use crate::{App, Plugin};
 use bevy_ecs::{
-    schedule::{ExecutorKind, InternedScheduleLabel, Schedule, ScheduleLabel},
+    schedule::{ExecutorKind, InternedScheduleLabel, Schedule, ScheduleLabel, StateTransition},
     system::{Local, Resource},
     world::{Mut, World},
 };
@@ -72,12 +72,6 @@ pub struct First;
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct PreUpdate;
 
-/// Runs [state transitions](bevy_ecs::schedule::States).
-///
-/// See the [`Main`] schedule for some details about how schedules are run.
-#[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
-pub struct StateTransition;
-
 /// Runs the [`FixedMain`] schedule in a loop according until all relevant elapsed time has been "consumed".
 ///
 /// See the [`Main`] schedule for some details about how schedules are run.

crates/bevy_ecs/macros/src/states.rs

@@ -6,16 +6,30 @@ use crate::bevy_ecs_path;
 
 pub fn derive_states(input: TokenStream) -> TokenStream {
     let ast = parse_macro_input!(input as DeriveInput);
+
     let generics = ast.generics;
     let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
 
-    let mut trait_path = bevy_ecs_path();
-    trait_path.segments.push(format_ident!("schedule").into());
+    let mut base_trait_path = bevy_ecs_path();
+    base_trait_path
+        .segments
+        .push(format_ident!("schedule").into());
+
+    let mut trait_path = base_trait_path.clone();
     trait_path.segments.push(format_ident!("States").into());
+
+    let mut state_mutation_trait_path = base_trait_path.clone();
+    state_mutation_trait_path
+        .segments
+        .push(format_ident!("FreelyMutableState").into());
+
     let struct_name = &ast.ident;
 
     quote! {
         impl #impl_generics #trait_path for #struct_name #ty_generics #where_clause {}
+
+        impl #impl_generics #state_mutation_trait_path for #struct_name #ty_generics #where_clause {
+        }
     }
     .into()
 }

crates/bevy_ecs/src/lib.rs

@@ -41,9 +41,10 @@ pub mod prelude {
         query::{Added, AnyOf, Changed, Has, Or, QueryBuilder, QueryState, With, Without},
         removal_detection::RemovedComponents,
         schedule::{
-            apply_deferred, apply_state_transition, common_conditions::*, Condition,
-            IntoSystemConfigs, IntoSystemSet, IntoSystemSetConfigs, NextState, OnEnter, OnExit,
-            OnTransition, Schedule, Schedules, State, StateTransitionEvent, States, SystemSet,
+            apply_deferred, apply_state_transition, common_conditions::*, ComputedStates,
+            Condition, IntoSystemConfigs, IntoSystemSet, IntoSystemSetConfigs, NextState, OnEnter,
+            OnExit, OnTransition, Schedule, Schedules, State, StateSet, StateTransition,
+            StateTransitionEvent, States, SystemSet,
         },
         system::{
             Commands, Deferred, In, IntoSystem, Local, NonSend, NonSendMut, ParallelCommands,