Observer run conditions (#22602)

# Objective

Allow observers to use run conditions, enabling conditional execution
based on world state - the same pattern that systems use with .run_if().

Fixes #14195
Fixes #21442

## Solution

Add a run_if() method to observer systems via the ObserverSystemExt
trait. Conditions are stored in Observer and checked before execution in
the runner.

Key implementation details:
- ObserverWithCondition<E,B,M,S> wrapper preserves event type info for
compile-time EntityEvent enforcement on entity observers
- Conditions are ReadOnlySystem (enforced by SystemCondition trait),
matching system run conditions
- Multiple conditions chain with AND semantics, short-circuiting on
first false

It's a bit more involved than mentioned
[here](#21442 (comment))
since we need the full system‑style API: chained run_ifs, entity
observers with compile‑time EntityEvent checks, and use with
add_observer/observe.

That forces a typed wrapper + marker types +
IntoObserver/IntoEntityObserver, and conditions must be initialized at
spawn time (so the hook has to take/init/restore). The runner also needs
a safety‑documented precheck before running the observer.

## Testing

- Added 7 new tests covering:
  - Condition preventing/allowing execution
  - Multiple conditions (all true / one false)
  - Entity observers with conditions
  - Resource-based conditions
  - Builder pattern on Observer::new()
- All existing tests pass (cargo test -p bevy_ecs)
- Updated observers.rs example with Space key toggle

---

## Showcase

```rust
#[derive(Resource)]
struct GameActive(bool);
// Global observer - only runs when game is active
app.add_observer(
    on_damage.run_if(|state: Res<GameActive>| state.0)
);
// Chained conditions (AND semantics)
app.add_observer(
    on_damage
        .run_if(|state: Res<GameActive>| state.0)
        .run_if(|player: Query<&Health, With<Player>>| player.single().is_ok())
);
// Entity observer
commands.spawn(Enemy).observe(
    on_hit.run_if(|game: Res<GameActive>| game.0)
);
// Builder pattern
world.spawn(
    Observer::new(on_event)
        .with_entity(target)
        .run_if(some_condition)
);
```

<details>

<summary>Example from observers.rs</summary>

```rust
#[derive(Resource, Default)]
struct ExplosionsEnabled(bool);

fn toggle_explosions(mut enabled: ResMut<ExplosionsEnabled>, input: Res<ButtonInput<KeyCode>>) {
    if input.just_pressed(KeyCode::Space) {
        enabled.0 = !enabled.0;
        info!("Explosions {}", if enabled.0 { "enabled" } else { "disabled" });
    }
}

fn setup(app: &mut App) {
    app.add_observer(
        explode_mine.run_if(|enabled: Res<ExplosionsEnabled>| enabled.0)
    );
}
```

</details>

Author: jonas-meyer

crates/bevy_app/src/app.rs

@@ -11,15 +11,15 @@ pub use bevy_derive::AppLabel;
 use bevy_ecs::{
     component::RequiredComponentsError,
     error::{DefaultErrorHandler, ErrorHandler},
-    event::Event,
     intern::Interned,
     message::{message_update_system, MessageCursor},
+    observer::IntoObserver,
     prelude::*,
     schedule::{
         InternedSystemSet, ScheduleBuildSettings, ScheduleCleanupPolicy, ScheduleError,
         ScheduleLabel,
     },
-    system::{IntoObserverSystem, ScheduleSystem, SystemId, SystemInput},
+    system::{ScheduleSystem, SystemId, SystemInput},
 };
 use bevy_platform::collections::HashMap;
 use core::{fmt::Debug, num::NonZero, panic::AssertUnwindSafe};
@@ -1392,10 +1392,7 @@ impl App {
     ///     }
     /// });
     /// ```
-    pub fn add_observer<E: Event, B: Bundle, M>(
-        &mut self,
-        observer: impl IntoObserverSystem<E, B, M>,
-    ) -> &mut Self {
+    pub fn add_observer<M>(&mut self, observer: impl IntoObserver<M>) -> &mut Self {
         self.world_mut().add_observer(observer);
         self
     }

crates/bevy_ecs/src/lib.rs

@@ -80,7 +80,7 @@ pub mod prelude {
             Message, MessageMutator, MessageReader, MessageWriter, Messages, PopulatedMessageReader,
         },
         name::{Name, NameOrEntity},
-        observer::{Observer, On},
+        observer::{Observer, ObserverSystemExt, On},
         query::{Added, Allow, AnyOf, Changed, Has, Or, QueryBuilder, QueryState, With, Without},
         related,
         relationship::RelationshipTarget,

crates/bevy_ecs/src/observer/condition.rs

@@ -0,0 +1,108 @@
+//! Run conditions for observers.
+//!
+//! This module provides the types needed to add run conditions to observers,
+//! allowing them to conditionally execute based on world state.
+
+use alloc::{boxed::Box, vec::Vec};
+use core::marker::PhantomData;
+
+use crate::{
+    bundle::Bundle,
+    event::Event,
+    schedule::{BoxedCondition, SystemCondition},
+    system::{IntoObserverSystem, IntoSystem},
+    world::{unsafe_world_cell::UnsafeWorldCell, World},
+};
+
+/// Stores a boxed condition system for an observer.
+pub(crate) struct ObserverCondition {
+    condition: BoxedCondition,
+}
+
+impl ObserverCondition {
+    pub(crate) fn new<M>(condition: impl SystemCondition<M>) -> Self {
+        Self {
+            condition: Box::new(IntoSystem::into_system(condition)),
+        }
+    }
+
+    pub(crate) fn from_boxed(condition: BoxedCondition) -> Self {
+        Self { condition }
+    }
+
+    pub(crate) fn initialize(&mut self, world: &mut World) {
+        self.condition.initialize(world);
+    }
+
+    /// # Safety
+    /// - The condition must be initialized.
+    /// - The world cell must have valid access for the condition's read-only parameters.
+    pub(crate) unsafe fn check(&mut self, world: UnsafeWorldCell) -> bool {
+        // SAFETY: Caller ensures world is valid and condition is initialized.
+        // Conditions are read-only systems, so they won't cause aliasing issues.
+        unsafe { self.condition.run_unsafe((), world) }.unwrap_or(false)
+    }
+}
+
+#[doc(hidden)]
+pub struct ObserverWithConditionMarker;
+
+/// An observer system with run conditions that preserves event type information.
+///
+/// This type is returned by [`ObserverSystemExt::run_if`](super::ObserverSystemExt::run_if)
+/// and allows `entity.observe(system.run_if(cond))` to work with compile-time
+/// verification that the event implements [`EntityEvent`](crate::event::EntityEvent).
+pub struct ObserverWithCondition<E: Event, B: Bundle, M, S: IntoObserverSystem<E, B, M>> {
+    pub(crate) system: S,
+    pub(crate) conditions: Vec<BoxedCondition>,
+    pub(crate) _marker: PhantomData<fn() -> (E, B, M)>,
+}
+
+impl<E: Event, B: Bundle, M, S: IntoObserverSystem<E, B, M>> ObserverWithCondition<E, B, M, S> {
+    /// Adds another run condition to this observer.
+    ///
+    /// All conditions must return `true` for the observer to run (AND semantics).
+    ///
+    /// **Note:** Chained `.run_if()` calls do **not** short-circuit — all conditions
+    /// run every time to maintain correct change detection ticks. If you need
+    /// short-circuit behavior, use `.run_if(a.and(b))`, but be aware this may cause
+    /// stale `Changed<T>` detection if the second condition is frequently skipped.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use bevy_ecs::prelude::*;
+    /// # #[derive(Event)]
+    /// # struct MyEvent;
+    /// # #[derive(Resource)]
+    /// # struct CondA(bool);
+    /// # #[derive(Resource)]
+    /// # struct CondB(bool);
+    /// # fn on_event(_: On<MyEvent>) {}
+    /// # let mut world = World::new();
+    /// # world.insert_resource(CondA(true));
+    /// # world.insert_resource(CondB(true));
+    /// world.add_observer(
+    ///     on_event
+    ///         .run_if(|a: Res<CondA>| a.0)
+    ///         .run_if(|b: Res<CondB>| b.0)
+    /// );
+    /// ```
+    pub fn run_if<C, CM>(mut self, condition: C) -> Self
+    where
+        C: SystemCondition<CM>,
+    {
+        self.conditions
+            .push(Box::new(IntoSystem::into_system(condition)));
+        self
+    }
+
+    pub(crate) fn take_conditions(self) -> (S, Vec<ObserverCondition>) {
+        let conditions = self
+            .conditions
+            .into_iter()
+            .map(ObserverCondition::from_boxed)
+            .collect();
+        (self.system, conditions)
+    }
+}

crates/bevy_ecs/src/observer/distributed_storage.rs

@@ -11,13 +11,17 @@
 
 use core::any::Any;
 
+use core::marker::PhantomData;
+
 use crate::{
     component::{ComponentCloneBehavior, ComponentId, Mutable, StorageType},
-    entity::Entity,
     error::{ErrorContext, ErrorHandler},
-    event::{Event, EventKey},
+    event::EventKey,
     lifecycle::{ComponentHook, HookContext},
-    observer::{observer_system_runner, ObserverRunner},
+    observer::{
+        condition::{ObserverCondition, ObserverWithCondition, ObserverWithConditionMarker},
+        observer_system_runner, ObserverRunner,
+    },
     prelude::*,
     system::{IntoObserverSystem, ObserverSystem},
     world::DeferredWorld,
@@ -208,6 +212,7 @@ pub struct Observer {
     pub(crate) last_trigger_id: u32,
     pub(crate) despawned_watched_entities: u32,
     pub(crate) runner: ObserverRunner,
+    pub(crate) conditions: Vec<ObserverCondition>,
 }
 
 impl Observer {
@@ -234,6 +239,7 @@ impl Observer {
             runner: observer_system_runner::<E, B, I::System>,
             despawned_watched_entities: 0,
             last_trigger_id: 0,
+            conditions: Vec::new(),
         }
     }
 
@@ -246,21 +252,32 @@ impl Observer {
                 let default_error_handler = world.default_error_handler();
                 world.commands().queue(move |world: &mut World| {
                     let entity = hook_context.entity;
-                    if let Some(mut observe) = world.get_mut::<Observer>(entity) {
+                    let mut conditions = {
+                        let Some(mut observe) = world.get_mut::<Observer>(entity) else {
+                            return;
+                        };
                         if observe.descriptor.event_keys.is_empty() {
                             return;
                         }
                         if observe.error_handler.is_none() {
                             observe.error_handler = Some(default_error_handler);
                         }
-                        world.register_observer(entity);
+                        core::mem::take(&mut observe.conditions)
+                    };
+                    for condition in &mut conditions {
+                        condition.initialize(world);
                     }
+                    if let Some(mut observe) = world.get_mut::<Observer>(entity) {
+                        observe.conditions = conditions;
+                    }
+                    world.register_observer(entity);
                 });
             },
             error_handler: None,
             runner,
             despawned_watched_entities: 0,
             last_trigger_id: 0,
+            conditions: Vec::new(),
         }
     }
 
@@ -326,6 +343,15 @@ impl Observer {
         self
     }
 
+    /// Adds a run condition to this observer.
+    ///
+    /// The observer will only run if all conditions return `true` (AND semantics).
+    /// Multiple conditions can be added by chaining `run_if` calls.
+    pub fn run_if<M>(mut self, condition: impl SystemCondition<M>) -> Self {
+        self.conditions.push(ObserverCondition::new(condition));
+        self
+    }
+
     /// Returns the [`ObserverDescriptor`] for this [`Observer`].
     pub fn descriptor(&self) -> &ObserverDescriptor {
         &self.descriptor
@@ -435,18 +461,38 @@ fn hook_on_add<E: Event, B: Bundle, S: ObserverSystem<E, B>>(
         let event_key = world.register_event_key::<E>();
         let components = B::component_ids(&mut world.components_registrator());
 
-        if let Some(mut observer) = world.get_mut::<Observer>(entity) {
+        let system_ptr: *mut dyn ObserverSystem<E, B> = {
+            let Some(mut observer) = world.get_mut::<Observer>(entity) else {
+                return;
+            };
             observer.descriptor.event_keys.push(event_key);
             observer.descriptor.components.extend(components);
 
             let system: &mut dyn Any = observer.system.as_mut();
-            let system: *mut dyn ObserverSystem<E, B> = system.downcast_mut::<S>().unwrap();
-            // SAFETY: World reference is exclusive and initialize does not touch system, so references do not alias
-            unsafe {
-                (*system).initialize(world);
-            }
-            world.register_observer(entity);
+            system.downcast_mut::<S>().unwrap() as *mut dyn ObserverSystem<E, B>
+        };
+
+        // SAFETY: World reference is exclusive and initialize does not touch system, so references do not alias
+        unsafe {
+            (*system_ptr).initialize(world);
+        }
+
+        let mut conditions = {
+            let Some(mut observer) = world.get_mut::<Observer>(entity) else {
+                return;
+            };
+            core::mem::take(&mut observer.conditions)
+        };
+
+        for condition in &mut conditions {
+            condition.initialize(world);
         }
+
+        if let Some(mut observer) = world.get_mut::<Observer>(entity) {
+            observer.conditions = conditions;
+        }
+
+        world.register_observer(entity);
     });
 }
 
@@ -510,3 +556,83 @@ impl<T: Any + System> AnyNamedSystem for T {
         self.name()
     }
 }
+
+/// Trait for types that can be converted into an [`Observer`].
+pub trait IntoObserver<Marker>: Send + 'static {
+    /// Converts this type into an [`Observer`].
+    fn into_observer(self) -> Observer;
+}
+
+impl IntoObserver<()> for Observer {
+    fn into_observer(self) -> Observer {
+        self
+    }
+}
+
+impl<E: Event, B: Bundle, M, T: IntoObserverSystem<E, B, M>> IntoObserver<(E, B, M)> for T {
+    fn into_observer(self) -> Observer {
+        Observer::new(self)
+    }
+}
+
+impl<E: Event, B: Bundle, M: 'static, S: IntoObserverSystem<E, B, M>>
+    IntoObserver<ObserverWithConditionMarker> for ObserverWithCondition<E, B, M, S>
+{
+    fn into_observer(self) -> Observer {
+        let (system, conditions) = self.take_conditions();
+        let mut observer = Observer::new(system);
+        observer.conditions = conditions;
+        observer
+    }
+}
+
+/// Trait for types that can be converted into an entity-targeting [`Observer`].
+///
+/// This trait enforces that the event type implements [`EntityEvent`].
+#[diagnostic::on_unimplemented(
+    message = "`{Self}` cannot be used as an entity observer",
+    note = "entity observers require the event type to implement `EntityEvent`"
+)]
+pub trait IntoEntityObserver<Marker>: Send + 'static {
+    /// Converts this type into an [`Observer`] that watches the given entity.
+    fn into_observer_for_entity(self, entity: Entity) -> Observer;
+}
+
+impl<E: EntityEvent, B: Bundle, M, T: IntoObserverSystem<E, B, M>> IntoEntityObserver<(E, B, M)>
+    for T
+{
+    fn into_observer_for_entity(self, entity: Entity) -> Observer {
+        Observer::new(self).with_entity(entity)
+    }
+}
+
+impl<E: EntityEvent, B: Bundle, M: 'static, S: IntoObserverSystem<E, B, M>>
+    IntoEntityObserver<ObserverWithConditionMarker> for ObserverWithCondition<E, B, M, S>
+{
+    fn into_observer_for_entity(self, entity: Entity) -> Observer {
+        let (system, conditions) = self.take_conditions();
+        let mut observer = Observer::new(system);
+        observer.conditions = conditions;
+        observer.with_entity(entity)
+    }
+}
+
+/// Extension trait for adding run conditions to observer systems.
+pub trait ObserverSystemExt<E: Event, B: Bundle, M>: IntoObserverSystem<E, B, M> + Sized {
+    /// Adds a run condition to this observer system.
+    ///
+    /// The observer will only run if the condition returns `true`.
+    /// Multiple conditions can be chained (AND semantics).
+    fn run_if<C, CM>(self, condition: C) -> ObserverWithCondition<E, B, M, Self>
+    where
+        C: SystemCondition<CM>,
+    {
+        ObserverWithCondition {
+            system: self,
+            conditions: alloc::vec![Box::new(IntoSystem::into_system(condition))],
+            _marker: PhantomData,
+        }
+    }
+}
+
+impl<E: Event, B: Bundle, M, T: IntoObserverSystem<E, B, M>> ObserverSystemExt<E, B, M> for T {}