Rename When system param to If (#20325)

# Objective

Regardless of where we land on #19489, `When` as a system param wrapper
is a touch verbose. In many cases, users may find themselves liberally
applying `When` to their fallible system params. I believe that `If`
maintains the same semantics in a smaller and more readable package, and
therefore should replace `When`.

## Showcase

`When`:
```rs
fn fallible_params(player: When<Single<&mut Velocity, With<Player>>>, gravity: When<Res<Gravity>>) {}
```

`If`:
```rs
fn fallible_params(player: If<Single<&mut Velocity, With<Player>>>, gravity: If<Res<Gravity>>) {}
```

Author: CorvusPrudens

crates/bevy_ecs/src/lib.rs

@@ -99,10 +99,10 @@ pub mod prelude {
         },
         spawn::{Spawn, SpawnIter, SpawnRelated, SpawnWith, WithOneRelated, WithRelated},
         system::{
-            Command, Commands, Deferred, EntityCommand, EntityCommands, In, InMut, InRef,
+            Command, Commands, Deferred, EntityCommand, EntityCommands, If, In, InMut, InRef,
             IntoSystem, Local, NonSend, NonSendMut, ParamSet, Populated, Query, ReadOnlySystem,
             Res, ResMut, Single, System, SystemIn, SystemInput, SystemParamBuilder,
-            SystemParamFunction, When,
+            SystemParamFunction,
         },
         world::{
             EntityMut, EntityRef, EntityWorldMut, FilteredResources, FilteredResourcesMut,

crates/bevy_ecs/src/system/builder.rs

@@ -7,8 +7,8 @@ use crate::{
     query::{QueryData, QueryFilter, QueryState},
     resource::Resource,
     system::{
-        DynSystemParam, DynSystemParamState, Local, ParamSet, Query, SystemParam,
-        SystemParamValidationError, When,
+        DynSystemParam, DynSystemParamState, If, Local, ParamSet, Query, SystemParam,
+        SystemParamValidationError,
     },
     world::{
         FilteredResources, FilteredResourcesBuilder, FilteredResourcesMut,
@@ -605,15 +605,13 @@ unsafe impl<P: SystemParam, B: SystemParamBuilder<P>>
     }
 }
 
-/// A [`SystemParamBuilder`] for a [`When`].
+/// A [`SystemParamBuilder`] for a [`If`].
 #[derive(Clone)]
-pub struct WhenBuilder<T>(T);
+pub struct IfBuilder<T>(T);
 
-// SAFETY: `WhenBuilder<B>` builds a state that is valid for `P`, and any state valid for `P` is valid for `When<P>`
-unsafe impl<P: SystemParam, B: SystemParamBuilder<P>> SystemParamBuilder<When<P>>
-    for WhenBuilder<B>
-{
-    fn build(self, world: &mut World) -> <When<P> as SystemParam>::State {
+// SAFETY: `IfBuilder<B>` builds a state that is valid for `P`, and any state valid for `P` is valid for `If<P>`
+unsafe impl<P: SystemParam, B: SystemParamBuilder<P>> SystemParamBuilder<If<P>> for IfBuilder<B> {
+    fn build(self, world: &mut World) -> <If<P> as SystemParam>::State {
         self.0.build(world)
     }
 }

crates/bevy_ecs/src/system/system_param.rs

@@ -1846,16 +1846,16 @@ unsafe impl<T: ReadOnlySystemParam> ReadOnlySystemParam for Result<T, SystemPara
 /// fn fails_on_missing_resource(res: Res<SomeResource>) {}
 ///
 /// // This system will skip without error if `SomeResource` is not present.
-/// fn skips_on_missing_resource(res: When<Res<SomeResource>>) {
+/// fn skips_on_missing_resource(res: If<Res<SomeResource>>) {
 ///     // The inner parameter is available using `Deref`
 ///     let some_resource: &SomeResource = &res;
 /// }
 /// # bevy_ecs::system::assert_is_system(skips_on_missing_resource);
 /// ```
 #[derive(Debug)]
-pub struct When<T>(pub T);
+pub struct If<T>(pub T);
 
-impl<T> When<T> {
+impl<T> If<T> {
     /// Returns the inner `T`.
     ///
     /// The inner value is `pub`, so you can also obtain it by destructuring the parameter:
@@ -1864,7 +1864,7 @@ impl<T> When<T> {
     /// # use bevy_ecs::prelude::*;
     /// # #[derive(Resource)]
     /// # struct SomeResource;
-    /// fn skips_on_missing_resource(When(res): When<Res<SomeResource>>) {
+    /// fn skips_on_missing_resource(If(res): If<Res<SomeResource>>) {
     ///     let some_resource: Res<SomeResource> = res;
     /// }
     /// # bevy_ecs::system::assert_is_system(skips_on_missing_resource);
@@ -1874,24 +1874,24 @@ impl<T> When<T> {
     }
 }
 
-impl<T> Deref for When<T> {
+impl<T> Deref for If<T> {
     type Target = T;
     fn deref(&self) -> &Self::Target {
         &self.0
     }
 }
 
-impl<T> DerefMut for When<T> {
+impl<T> DerefMut for If<T> {
     fn deref_mut(&mut self) -> &mut Self::Target {
         &mut self.0
     }
 }
 
 // SAFETY: Delegates to `T`, which ensures the safety requirements are met
-unsafe impl<T: SystemParam> SystemParam for When<T> {
+unsafe impl<T: SystemParam> SystemParam for If<T> {
     type State = T::State;
 
-    type Item<'world, 'state> = When<T::Item<'world, 'state>>;
+    type Item<'world, 'state> = If<T::Item<'world, 'state>>;
 
     fn init_state(world: &mut World) -> Self::State {
         T::init_state(world)
@@ -1925,7 +1925,7 @@ unsafe impl<T: SystemParam> SystemParam for When<T> {
         world: UnsafeWorldCell<'world>,
         change_tick: Tick,
     ) -> Self::Item<'world, 'state> {
-        When(T::get_param(state, system_meta, world, change_tick))
+        If(T::get_param(state, system_meta, world, change_tick))
     }
 
     fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World) {
@@ -1938,7 +1938,7 @@ unsafe impl<T: SystemParam> SystemParam for When<T> {
 }
 
 // SAFETY: Delegates to `T`, which ensures the safety requirements are met
-unsafe impl<T: ReadOnlySystemParam> ReadOnlySystemParam for When<T> {}
+unsafe impl<T: ReadOnlySystemParam> ReadOnlySystemParam for If<T> {}
 
 // SAFETY: Registers access for each element of `state`.
 // If any one conflicts, it will panic.
@@ -2784,7 +2784,7 @@ pub struct SystemParamValidationError {
     /// failures in validation should be considered a bug in the user's logic that must be immediately addressed (like [`Res`]).
     ///
     /// If `true`, the system should be skipped.
-    /// This is set by wrapping the system param in [`When`],
+    /// This is set by wrapping the system param in [`If`],
     /// and indicates that the system is intended to only operate in certain application states.
     pub skipped: bool,
 
@@ -2848,7 +2848,7 @@ impl Display for SystemParamValidationError {
             self.message
         )?;
         if !self.skipped {
-            write!(fmt, "\nIf this is an expected state, wrap the parameter in `Option<T>` and handle `None` when it happens, or wrap the parameter in `When<T>` to skip the system when it happens.")?;
+            write!(fmt, "\nIf this is an expected state, wrap the parameter in `Option<T>` and handle `None` when it happens, or wrap the parameter in `If<T>` to skip the system when it happens.")?;
         }
         Ok(())
     }

release-content/migration-guides/system_run_returns_result.md

@@ -3,7 +3,7 @@ title: "`System::run` returns `Result`"
 pull_requests: [19145]
 ---
 
-In order to support fallible systems and parameter-based system skipping like `Single` and `When<T>` in more places, `System::run` and related methods now return a `Result` instead of a plain value.  
+In order to support fallible systems and parameter-based system skipping like `Single` and `If<T>` in more places, `System::run` and related methods now return a `Result` instead of a plain value.
 
 If you were calling `System::run`, `System::run_unsafe`, `System::run_without_applying_deferred`, or `ReadOnlySystem::run_readonly`, the simplest solution is to `unwrap()` the resulting `Result`.
 The only case where an infallible system will return `Err` is an invalid parameter, such as a missing resource, and those cases used to panic.