From 09979cdb6500811bd5a8959a74e7aafcfd8c9c1d Mon Sep 17 00:00:00 2001
From: koe <ukoe@protonmail.com>
Date: Sat, 7 Sep 2024 16:47:05 -0500
Subject: [PATCH 1/4] add set_state extension method to Commands

---
 crates/bevy_state/src/commands.rs   | 28 ++++++++++++++++++++++
 crates/bevy_state/src/lib.rs        |  4 ++++
 examples/games/alien_cake_addict.rs | 10 +++-----
 examples/games/game_menu.rs         | 37 +++++++++++------------------
 4 files changed, 49 insertions(+), 30 deletions(-)
 create mode 100644 crates/bevy_state/src/commands.rs

diff --git a/crates/bevy_state/src/commands.rs b/crates/bevy_state/src/commands.rs
new file mode 100644
index 0000000000000..38addffcff4f9
--- /dev/null
+++ b/crates/bevy_state/src/commands.rs
@@ -0,0 +1,28 @@
+use bevy_ecs::{system::Commands, world::World};
+use bevy_utils::tracing::debug;
+
+use crate::state::{FreelyMutableState, NextState};
+
+/// Extension trait for [`Commands`](bevy_ecs::prelude::Commands) adding `bevy_state` helpers.
+pub trait CommandsStatesExt {
+    /// Sets the next state the app should move to.
+    ///
+    /// Internally this schedules a command that updates the [`NextState<S>`](crate::prelude::NextState)
+    /// resource with `state`.
+    ///
+    /// Note that commands introduce sync points to the ECS schedule, so modifying `NextState`
+    /// directly may be more efficient depending on your use-case.
+    fn set_state<S: FreelyMutableState>(&mut self, state: S);
+}
+
+impl CommandsStatesExt for Commands<'_, '_> {
+    fn set_state<S: FreelyMutableState>(&mut self, state: S) {
+        self.add(move |w: &mut World| {
+            let mut next = w.resource_mut::<NextState<S>>();
+            if let NextState::Pending(prev) = &*next {
+                debug!("overwriting state {:?} with {:?}", prev, state);
+            }
+            next.set(state);
+        });
+    }
+}
diff --git a/crates/bevy_state/src/lib.rs b/crates/bevy_state/src/lib.rs
index b9ded18d4ef0e..5356560579460 100644
--- a/crates/bevy_state/src/lib.rs
+++ b/crates/bevy_state/src/lib.rs
@@ -34,6 +34,8 @@
 #[cfg(feature = "bevy_app")]
 /// Provides [`App`](bevy_app::App) and [`SubApp`](bevy_app::SubApp) with state installation methods
 pub mod app;
+/// Provides extension methods for [`Commands`](bevy_ecs::Commands).
+pub mod commands;
 /// Provides definitions for the runtime conditions that interact with the state system
 pub mod condition;
 /// Provides definitions for the basic traits required by the state system
@@ -53,6 +55,8 @@ pub mod prelude {
     #[doc(hidden)]
     pub use crate::app::AppExtStates;
     #[doc(hidden)]
+    pub use crate::commands::CommandsStatesExt;
+    #[doc(hidden)]
     pub use crate::condition::*;
     #[cfg(feature = "bevy_reflect")]
     #[doc(hidden)]
diff --git a/examples/games/alien_cake_addict.rs b/examples/games/alien_cake_addict.rs
index fa1b0543a9661..8c1941a3fb603 100644
--- a/examples/games/alien_cake_addict.rs
+++ b/examples/games/alien_cake_addict.rs
@@ -316,7 +316,6 @@ fn focus_camera(
 fn spawn_bonus(
     time: Res<Time>,
     mut timer: ResMut<BonusSpawnTimer>,
-    mut next_state: ResMut<NextState<GameState>>,
     mut commands: Commands,
     mut game: ResMut<Game>,
     mut rng: ResMut<Random>,
@@ -331,7 +330,7 @@ fn spawn_bonus(
         commands.entity(entity).despawn_recursive();
         game.bonus.entity = None;
         if game.score <= -5 {
-            next_state.set(GameState::GameOver);
+            commands.set_state(GameState::GameOver);
             return;
         }
     }
@@ -389,12 +388,9 @@ fn scoreboard_system(game: Res<Game>, mut query: Query<&mut Text>) {
 }
 
 // restart the game when pressing spacebar
-fn gameover_keyboard(
-    mut next_state: ResMut<NextState<GameState>>,
-    keyboard_input: Res<ButtonInput<KeyCode>>,
-) {
+fn gameover_keyboard(mut commands: Commands, keyboard_input: Res<ButtonInput<KeyCode>>) {
     if keyboard_input.just_pressed(KeyCode::Space) {
-        next_state.set(GameState::Playing);
+        commands.set_state(GameState::Playing);
     }
 }
 
diff --git a/examples/games/game_menu.rs b/examples/games/game_menu.rs
index 5c5f1c4752680..242c39b9f0d56 100644
--- a/examples/games/game_menu.rs
+++ b/examples/games/game_menu.rs
@@ -103,13 +103,9 @@ mod splash {
     }
 
     // Tick the timer, and change state when finished
-    fn countdown(
-        mut game_state: ResMut<NextState<GameState>>,
-        time: Res<Time>,
-        mut timer: ResMut<SplashTimer>,
-    ) {
+    fn countdown(mut commands: Commands, time: Res<Time>, mut timer: ResMut<SplashTimer>) {
         if timer.tick(time.delta()).finished() {
-            game_state.set(GameState::Menu);
+            commands.set_state(GameState::Menu);
         }
     }
 }
@@ -228,13 +224,9 @@ mod game {
     }
 
     // Tick the timer, and change state when finished
-    fn game(
-        time: Res<Time>,
-        mut game_state: ResMut<NextState<GameState>>,
-        mut timer: ResMut<GameTimer>,
-    ) {
+    fn game(time: Res<Time>, mut commands: Commands, mut timer: ResMut<GameTimer>) {
         if timer.tick(time.delta()).finished() {
-            game_state.set(GameState::Menu);
+            commands.set_state(GameState::Menu);
         }
     }
 }
@@ -378,8 +370,8 @@ mod menu {
         }
     }
 
-    fn menu_setup(mut menu_state: ResMut<NextState<MenuState>>) {
-        menu_state.set(MenuState::Main);
+    fn menu_setup(mut commands: Commands) {
+        commands.set_state(MenuState::Main);
     }
 
     fn main_menu_setup(mut commands: Commands, asset_server: Res<AssetServer>) {
@@ -777,13 +769,12 @@ mod menu {
     }
 
     fn menu_action(
+        mut commands: Commands,
         interaction_query: Query<
             (&Interaction, &MenuButtonAction),
             (Changed<Interaction>, With<Button>),
         >,
         mut app_exit_events: EventWriter<AppExit>,
-        mut menu_state: ResMut<NextState<MenuState>>,
-        mut game_state: ResMut<NextState<GameState>>,
     ) {
         for (interaction, menu_button_action) in &interaction_query {
             if *interaction == Interaction::Pressed {
@@ -792,19 +783,19 @@ mod menu {
                         app_exit_events.send(AppExit::Success);
                     }
                     MenuButtonAction::Play => {
-                        game_state.set(GameState::Game);
-                        menu_state.set(MenuState::Disabled);
+                        commands.set_state(GameState::Game);
+                        commands.set_state(MenuState::Disabled);
                     }
-                    MenuButtonAction::Settings => menu_state.set(MenuState::Settings),
+                    MenuButtonAction::Settings => commands.set_state(MenuState::Settings),
                     MenuButtonAction::SettingsDisplay => {
-                        menu_state.set(MenuState::SettingsDisplay);
+                        commands.set_state(MenuState::SettingsDisplay);
                     }
                     MenuButtonAction::SettingsSound => {
-                        menu_state.set(MenuState::SettingsSound);
+                        commands.set_state(MenuState::SettingsSound);
                     }
-                    MenuButtonAction::BackToMainMenu => menu_state.set(MenuState::Main),
+                    MenuButtonAction::BackToMainMenu => commands.set_state(MenuState::Main),
                     MenuButtonAction::BackToSettings => {
-                        menu_state.set(MenuState::Settings);
+                        commands.set_state(MenuState::Settings);
                     }
                 }
             }

From 93b37861295fc6ca473de6ce0b575aa3793e1301 Mon Sep 17 00:00:00 2001
From: koe <ukoe@protonmail.com>
Date: Sat, 7 Sep 2024 17:20:54 -0500
Subject: [PATCH 2/4] docs fixes

---
 crates/bevy_state/src/commands.rs | 2 +-
 crates/bevy_state/src/lib.rs      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_state/src/commands.rs b/crates/bevy_state/src/commands.rs
index 38addffcff4f9..5483809cdac46 100644
--- a/crates/bevy_state/src/commands.rs
+++ b/crates/bevy_state/src/commands.rs
@@ -3,7 +3,7 @@ use bevy_utils::tracing::debug;
 
 use crate::state::{FreelyMutableState, NextState};
 
-/// Extension trait for [`Commands`](bevy_ecs::prelude::Commands) adding `bevy_state` helpers.
+/// Extension trait for [`Commands`] adding `bevy_state` helpers.
 pub trait CommandsStatesExt {
     /// Sets the next state the app should move to.
     ///
diff --git a/crates/bevy_state/src/lib.rs b/crates/bevy_state/src/lib.rs
index 5356560579460..5e18ab7cdcf29 100644
--- a/crates/bevy_state/src/lib.rs
+++ b/crates/bevy_state/src/lib.rs
@@ -34,7 +34,7 @@
 #[cfg(feature = "bevy_app")]
 /// Provides [`App`](bevy_app::App) and [`SubApp`](bevy_app::SubApp) with state installation methods
 pub mod app;
-/// Provides extension methods for [`Commands`](bevy_ecs::Commands).
+/// Provides extension methods for [`Commands`](bevy_ecs::prelude::Commands).
 pub mod commands;
 /// Provides definitions for the runtime conditions that interact with the state system
 pub mod condition;

From 05da2213309952cb605489e0c7d387f74abc346d Mon Sep 17 00:00:00 2001
From: koe <ukoe@protonmail.com>
Date: Sat, 7 Sep 2024 17:39:12 -0500
Subject: [PATCH 3/4] more precise debug message

---
 crates/bevy_state/src/commands.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/crates/bevy_state/src/commands.rs b/crates/bevy_state/src/commands.rs
index 5483809cdac46..b392d6b39498b 100644
--- a/crates/bevy_state/src/commands.rs
+++ b/crates/bevy_state/src/commands.rs
@@ -20,7 +20,9 @@ impl CommandsStatesExt for Commands<'_, '_> {
         self.add(move |w: &mut World| {
             let mut next = w.resource_mut::<NextState<S>>();
             if let NextState::Pending(prev) = &*next {
-                debug!("overwriting state {:?} with {:?}", prev, state);
+                if *prev != state {
+                    debug!("overwriting next state {:?} with {:?}", prev, state);
+                }
             }
             next.set(state);
         });

From eef1d1fde2c61bd4314876c058ce86f052fdb020 Mon Sep 17 00:00:00 2001
From: koe <ukoe@protonmail.com>
Date: Sun, 8 Sep 2024 14:14:34 -0500
Subject: [PATCH 4/4] undo examples

---
 examples/games/alien_cake_addict.rs | 10 +++++---
 examples/games/game_menu.rs         | 37 ++++++++++++++++++-----------
 2 files changed, 30 insertions(+), 17 deletions(-)

diff --git a/examples/games/alien_cake_addict.rs b/examples/games/alien_cake_addict.rs
index 8c1941a3fb603..fa1b0543a9661 100644
--- a/examples/games/alien_cake_addict.rs
+++ b/examples/games/alien_cake_addict.rs
@@ -316,6 +316,7 @@ fn focus_camera(
 fn spawn_bonus(
     time: Res<Time>,
     mut timer: ResMut<BonusSpawnTimer>,
+    mut next_state: ResMut<NextState<GameState>>,
     mut commands: Commands,
     mut game: ResMut<Game>,
     mut rng: ResMut<Random>,
@@ -330,7 +331,7 @@ fn spawn_bonus(
         commands.entity(entity).despawn_recursive();
         game.bonus.entity = None;
         if game.score <= -5 {
-            commands.set_state(GameState::GameOver);
+            next_state.set(GameState::GameOver);
             return;
         }
     }
@@ -388,9 +389,12 @@ fn scoreboard_system(game: Res<Game>, mut query: Query<&mut Text>) {
 }
 
 // restart the game when pressing spacebar
-fn gameover_keyboard(mut commands: Commands, keyboard_input: Res<ButtonInput<KeyCode>>) {
+fn gameover_keyboard(
+    mut next_state: ResMut<NextState<GameState>>,
+    keyboard_input: Res<ButtonInput<KeyCode>>,
+) {
     if keyboard_input.just_pressed(KeyCode::Space) {
-        commands.set_state(GameState::Playing);
+        next_state.set(GameState::Playing);
     }
 }
 
diff --git a/examples/games/game_menu.rs b/examples/games/game_menu.rs
index 242c39b9f0d56..5c5f1c4752680 100644
--- a/examples/games/game_menu.rs
+++ b/examples/games/game_menu.rs
@@ -103,9 +103,13 @@ mod splash {
     }
 
     // Tick the timer, and change state when finished
-    fn countdown(mut commands: Commands, time: Res<Time>, mut timer: ResMut<SplashTimer>) {
+    fn countdown(
+        mut game_state: ResMut<NextState<GameState>>,
+        time: Res<Time>,
+        mut timer: ResMut<SplashTimer>,
+    ) {
         if timer.tick(time.delta()).finished() {
-            commands.set_state(GameState::Menu);
+            game_state.set(GameState::Menu);
         }
     }
 }
@@ -224,9 +228,13 @@ mod game {
     }
 
     // Tick the timer, and change state when finished
-    fn game(time: Res<Time>, mut commands: Commands, mut timer: ResMut<GameTimer>) {
+    fn game(
+        time: Res<Time>,
+        mut game_state: ResMut<NextState<GameState>>,
+        mut timer: ResMut<GameTimer>,
+    ) {
         if timer.tick(time.delta()).finished() {
-            commands.set_state(GameState::Menu);
+            game_state.set(GameState::Menu);
         }
     }
 }
@@ -370,8 +378,8 @@ mod menu {
         }
     }
 
-    fn menu_setup(mut commands: Commands) {
-        commands.set_state(MenuState::Main);
+    fn menu_setup(mut menu_state: ResMut<NextState<MenuState>>) {
+        menu_state.set(MenuState::Main);
     }
 
     fn main_menu_setup(mut commands: Commands, asset_server: Res<AssetServer>) {
@@ -769,12 +777,13 @@ mod menu {
     }
 
     fn menu_action(
-        mut commands: Commands,
         interaction_query: Query<
             (&Interaction, &MenuButtonAction),
             (Changed<Interaction>, With<Button>),
         >,
         mut app_exit_events: EventWriter<AppExit>,
+        mut menu_state: ResMut<NextState<MenuState>>,
+        mut game_state: ResMut<NextState<GameState>>,
     ) {
         for (interaction, menu_button_action) in &interaction_query {
             if *interaction == Interaction::Pressed {
@@ -783,19 +792,19 @@ mod menu {
                         app_exit_events.send(AppExit::Success);
                     }
                     MenuButtonAction::Play => {
-                        commands.set_state(GameState::Game);
-                        commands.set_state(MenuState::Disabled);
+                        game_state.set(GameState::Game);
+                        menu_state.set(MenuState::Disabled);
                     }
-                    MenuButtonAction::Settings => commands.set_state(MenuState::Settings),
+                    MenuButtonAction::Settings => menu_state.set(MenuState::Settings),
                     MenuButtonAction::SettingsDisplay => {
-                        commands.set_state(MenuState::SettingsDisplay);
+                        menu_state.set(MenuState::SettingsDisplay);
                     }
                     MenuButtonAction::SettingsSound => {
-                        commands.set_state(MenuState::SettingsSound);
+                        menu_state.set(MenuState::SettingsSound);
                     }
-                    MenuButtonAction::BackToMainMenu => commands.set_state(MenuState::Main),
+                    MenuButtonAction::BackToMainMenu => menu_state.set(MenuState::Main),
                     MenuButtonAction::BackToSettings => {
-                        commands.set_state(MenuState::Settings);
+                        menu_state.set(MenuState::Settings);
                     }
                 }
             }