Rename NextState::set_if_neq to set_if_different to resolve clashing (bevyengine#24676)

Fixes bevyengine#24655 by renaming NextState::set_if_neq to set_if_different to
resolve clashing.

Author: mansiverma897993

_release-content/migration-guides/next_state_set_if_neq_rename.md

@@ -0,0 +1,16 @@
+---
+title: "`NextState::set_if_neq` renamed to `set_if_different`"
+pull_requests: [24676]
+---
+
+`NextState::set_if_neq` and related methods and enum variants have been renamed to avoid naming conflicts with `Mut::set_if_neq` / `ReflectMut::set_if_neq` which have a different meaning.
+
+The following names have changed:
+
+- `NextState::set_if_neq` is now `NextState::set_if_different`
+- `NextState::PendingIfNeq` is now `NextState::PendingIfDifferent`
+- `CommandsStatesExt::set_state_if_neq` is now `CommandsStatesExt::set_state_if_different`
+- `ReflectFreelyMutableState::set_next_state_if_neq` is now `ReflectFreelyMutableState::set_next_state_if_different`
+- `ReflectFreelyMutableStateFns::set_next_state_if_neq` is now `ReflectFreelyMutableStateFns::set_next_state_if_different`
+
+Deprecated compatibility wrappers have been added for the renamed methods (`NextState::set_if_neq`, `CommandsStatesExt::set_state_if_neq`, and `ReflectFreelyMutableState::set_next_state_if_neq`) to allow existing code to compile with deprecation warnings.

crates/bevy_state/src/commands.rs

@@ -21,29 +21,43 @@ pub trait CommandsStatesExt {
     ///
     /// 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_if_different<S: FreelyMutableState>(&mut self, state: S);
+
+    /// Sets the next state the app should move to, skipping any state transitions if the next state is the same as the current state.
+    ///
+    /// 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.
+    #[deprecated(since = "0.19.0", note = "use `set_state_if_different` instead")]
     fn set_state_if_neq<S: FreelyMutableState>(&mut self, state: S);
 }
 
 impl CommandsStatesExt for Commands<'_, '_> {
     fn set_state<S: FreelyMutableState>(&mut self, state: S) {
         self.queue(move |w: &mut World| {
             let mut next = w.resource_mut::<NextState<S>>();
-            if let NextState::PendingIfNeq(prev) = &*next {
+            if let NextState::PendingIfDifferent(prev) = &*next {
                 debug!("overwriting next state {prev:?} with {state:?}");
             }
             next.set(state);
         });
     }
 
-    fn set_state_if_neq<S: FreelyMutableState>(&mut self, state: S) {
+    fn set_state_if_different<S: FreelyMutableState>(&mut self, state: S) {
         self.queue(move |w: &mut World| {
             let mut next = w.resource_mut::<NextState<S>>();
-            if let NextState::PendingIfNeq(prev) = &*next
+            if let NextState::PendingIfDifferent(prev) = &*next
                 && *prev != state
             {
-                debug!("overwriting next state {prev:?} with {state:?} if not equal");
+                debug!("overwriting next state {prev:?} with {state:?} if different");
             }
-            next.set_if_neq(state);
+            next.set_if_different(state);
         });
     }
+
+    fn set_state_if_neq<S: FreelyMutableState>(&mut self, state: S) {
+        self.set_state_if_different(state);
+    }
 }

crates/bevy_state/src/reflect.rs

@@ -59,8 +59,8 @@ pub struct ReflectFreelyMutableState(ReflectFreelyMutableStateFns);
 pub struct ReflectFreelyMutableStateFns {
     /// Function pointer implementing [`ReflectFreelyMutableState::set_next_state()`].
     pub set_next_state: fn(&mut World, &dyn Reflect, &TypeRegistry),
-    /// Function pointer implementing [`ReflectFreelyMutableState::set_next_state_if_neq()`].
-    pub set_next_state_if_neq: fn(&mut World, &dyn Reflect, &TypeRegistry),
+    /// Function pointer implementing [`ReflectFreelyMutableState::set_next_state_if_different()`].
+    pub set_next_state_if_different: fn(&mut World, &dyn Reflect, &TypeRegistry),
 }
 
 impl ReflectFreelyMutableStateFns {
@@ -80,13 +80,23 @@ impl ReflectFreelyMutableState {
         (self.0.set_next_state)(world, state, registry);
     }
     /// Tentatively set a pending state transition to a reflected [`ReflectFreelyMutableState`], skipping state transitions if the target state is the same as the current state.
+    pub fn set_next_state_if_different(
+        &self,
+        world: &mut World,
+        state: &dyn Reflect,
+        registry: &TypeRegistry,
+    ) {
+        (self.0.set_next_state_if_different)(world, state, registry);
+    }
+    /// Tentatively set a pending state transition to a reflected [`ReflectFreelyMutableState`], skipping state transitions if the target state is the same as the current state.
+    #[deprecated(since = "0.19.0", note = "use `set_next_state_if_different` instead")]
     pub fn set_next_state_if_neq(
         &self,
         world: &mut World,
         state: &dyn Reflect,
         registry: &TypeRegistry,
     ) {
-        (self.0.set_next_state_if_neq)(world, state, registry);
+        self.set_next_state_if_different(world, state, registry);
     }
 }
 
@@ -103,14 +113,14 @@ impl<S: FreelyMutableState + Reflect + TypePath> CreateTypeData<S> for ReflectFr
                     next_state.set(new_state);
                 }
             },
-            set_next_state_if_neq: |world, reflected_state, registry| {
+            set_next_state_if_different: |world, reflected_state, registry| {
                 let new_state: S = from_reflect_with_fallback(
                     reflected_state.as_partial_reflect(),
                     world,
                     registry,
                 );
                 if let Some(mut next_state) = world.get_resource_mut::<NextState<S>>() {
-                    next_state.set_if_neq(new_state);
+                    next_state.set_if_different(new_state);
                 }
             },
         })

crates/bevy_state/src/state/mod.rs

@@ -581,7 +581,7 @@ mod tests {
             .is_empty());
 
         world.insert_resource(TransitionCounter::default());
-        world.insert_resource(NextState::PendingIfNeq(SimpleState::A));
+        world.insert_resource(NextState::PendingIfDifferent(SimpleState::A));
         world.run_schedule(StateTransition);
         assert_eq!(world.resource::<State<SimpleState>>().0, SimpleState::A);
         assert_eq!(

crates/bevy_state/src/state/resources.rs

@@ -187,14 +187,14 @@ pub enum NextState<S: FreelyMutableState> {
     /// There is a pending transition for state `S`
     ///
     /// This will not trigger state transitions schedules if the target state is the same as the current one.
-    PendingIfNeq(S),
+    PendingIfDifferent(S),
 }
 
 impl<S: FreelyMutableState> NextState<S> {
     /// Tentatively set a pending state transition to `Some(state)`.
     ///
     /// This will run the state transition schedules [`OnEnter`](crate::state::OnEnter) and [`OnExit`](crate::state::OnExit).
-    /// If you want to skip those schedules for the same where we are transitioning to the same state, use [`set_if_neq`](Self::set_if_neq) instead.
+    /// If you want to skip those schedules when transitioning to the same state, use [`set_if_different`](Self::set_if_different) instead.
     pub fn set(&mut self, state: S) {
         *self = Self::Pending(state);
     }
@@ -203,12 +203,21 @@ impl<S: FreelyMutableState> NextState<S> {
     ///
     /// Like [`set`](Self::set), but will not run any state transition schedules if the target state is the same as the current one.
     /// If [`set`](Self::set) has already been called in the same frame with the same state, the transition schedules will be run anyways.
-    pub fn set_if_neq(&mut self, state: S) {
+    pub fn set_if_different(&mut self, state: S) {
         if !matches!(self, Self::Pending(s) if s == &state) {
-            *self = Self::PendingIfNeq(state);
+            *self = Self::PendingIfDifferent(state);
         }
     }
 
+    /// Tentatively set a pending state transition to `Some(state)`.
+    ///
+    /// Like [`set`](Self::set), but will not run any state transition schedules if the target state is the same as the current one.
+    /// If [`set`](Self::set) has already been called in the same frame with the same state, the transition schedules will be run anyways.
+    #[deprecated(since = "0.19.0", note = "use `set_if_different` instead")]
+    pub fn set_if_neq(&mut self, state: S) {
+        self.set_if_different(state);
+    }
+
     /// Remove any pending changes to [`State<S>`]
     pub fn reset(&mut self) {
         *self = Self::Unchanged;
@@ -225,7 +234,7 @@ pub(crate) fn take_next_state<S: FreelyMutableState>(
             next_state.set_changed();
             Some((x, true))
         }
-        NextState::PendingIfNeq(x) => {
+        NextState::PendingIfDifferent(x) => {
             next_state.set_changed();
             Some((x, false))
         }

crates/bevy_state/src/state_scoped.rs

@@ -868,7 +868,7 @@ mod tests {
         let entity = app.world_mut().spawn(DespawnOnExit(State::On)).id();
         assert!(app.world().get_entity(entity).is_ok());
 
-        app.world_mut().commands().set_state_if_neq(State::On);
+        app.world_mut().commands().set_state_if_different(State::On);
         app.update();
 
         assert_eq!(
@@ -878,7 +878,7 @@ mod tests {
             &State::On
         );
         // entity was not despawned on exit
-        // this is because "set_state_if_neq" skips state transitions since
+        // this is because "set_state_if_different" skips state transitions since
         // the app's next state is the same as its previous.
         assert!(app.world().get_entity(entity).is_ok());
     }