Struct Observer

pub struct Observer { /* private fields */ }

An Observer system. Add this Component to an Entity to turn it into an “observer”.

Observers listen for a “trigger” of a specific Event. Events are triggered by calling World::trigger or World::trigger_targets.

Note that “buffered” events sent using EventReader and EventWriter are not automatically triggered. They must be triggered at a specific point in the schedule.

Usage

The simplest usage of the observer pattern looks like this:

#[derive(Event)]
struct Speak {
    message: String,
}

world.add_observer(|trigger: Trigger<Speak>| {
    println!("{}", trigger.event().message);
});

// Observers currently require a flush() to be registered. In the context of schedules,
// this will generally be done for you.
world.flush();

world.trigger(Speak {
    message: "Hello!".into(),
});

Notice that we used World::add_observer. This is just a shorthand for spawning an Observer manually:

// These are functionally the same:
world.add_observer(|trigger: Trigger<Speak>| {});
world.spawn(Observer::new(|trigger: Trigger<Speak>| {}));

Observers are systems. They can access arbitrary World data by adding SystemParams:

world.add_observer(|trigger: Trigger<PrintNames>, names: Query<&Name>| {
    for name in &names {
        println!("{name:?}");
    }
});

Note that Trigger must always be the first parameter.

You can also add Commands, which means you can spawn new entities, insert new components, etc:

world.add_observer(|trigger: Trigger<SpawnThing>, mut commands: Commands| {
    commands.spawn(Thing);
});

Observers can also trigger new events:

world.add_observer(|trigger: Trigger<A>, mut commands: Commands| {
    commands.trigger(B);
});

When the commands are flushed (including these “nested triggers”) they will be recursively evaluated until there are no commands left, meaning nested triggers all evaluate at the same time!

Events can be triggered for entities, which will be passed to the Observer:

#[derive(Event)]
struct Explode;

world.add_observer(|trigger: Trigger<Explode>, mut commands: Commands| {
    println!("Entity {} goes BOOM!", trigger.target());
    commands.entity(trigger.target()).despawn();
});

world.flush();

world.trigger_targets(Explode, entity);

You can trigger multiple entities at once:

world.trigger_targets(Explode, [e1, e2]);

Observers can also watch specific entities, which enables you to assign entity-specific logic:

world.entity_mut(e1).observe(|trigger: Trigger<Explode>, mut commands: Commands| {
    println!("Boom!");
    commands.entity(trigger.target()).despawn();
});

world.entity_mut(e2).observe(|trigger: Trigger<Explode>, mut commands: Commands| {
    println!("The explosion fizzles! This entity is immune!");
});

If all entities watched by a given Observer are despawned, the Observer entity will also be despawned. This protects against observer “garbage” building up over time.

The examples above calling EntityWorldMut::observe to add entity-specific observer logic are (once again) just shorthand for spawning an Observer directly:

let mut observer = Observer::new(|trigger: Trigger<Explode>| {});
observer.watch_entity(entity);
world.spawn(observer);

Note that the Observer component is not added to the entity it is observing. Observers should always be their own entities!

You can call Observer::watch_entity more than once, which allows you to watch multiple entities with the same Observer.

When first added, Observer will also create an ObserverState component, which registers the observer with the World and serves as the “source of truth” of the observer.

Implementations

impl Observer

pub fn new<E: Event, B: Bundle, M, I: IntoObserverSystem<E, B, M>>( system: I, ) -> Self

Creates a new Observer, which defaults to a “global” observer. This means it will run whenever the event E is triggered for any entity (or no entity).

pub fn with_entity(self, entity: Entity) -> Self

Observe the given entity. This will cause the Observer to run whenever the Event is triggered for the entity.

pub fn watch_entity(&mut self, entity: Entity)

Observe the given entity. This will cause the Observer to run whenever the Event is triggered for the entity. Note that if this is called after an Observer is spawned, it will produce no effects.

pub fn with_component(self, component: ComponentId) -> Self

Observe the given component. This will cause the Observer to run whenever the Event is triggered with the given component target.

pub unsafe fn with_event(self, event: ComponentId) -> Self

Observe the given event. This will cause the Observer to run whenever an event with the given ComponentId is triggered.

Safety

The type of the event ComponentId must match the actual value of the event passed into the observer system.

pub fn with_error_handler( self, error_handler: fn(BevyError, ErrorContext), ) -> Self

Set the error handler to use for this observer.

See the error module-level documentation for more information.

pub fn descriptor(&self) -> &ObserverDescriptor

Returns the ObserverDescriptor for this Observer.

Trait Implementations

impl Component for Observer

const STORAGE_TYPE: StorageType = StorageType::SparseSet

A constant indicating the storage type used for this component.

type Mutability = Mutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have [Component<Mutability = Mutable>], while immutable components will instead have [Component<Mutability = Immutable>].

fn on_add() -> Option<ComponentHook>

Gets the on_add ComponentHook for this Component if one is defined.

fn register_component_hooks(hooks: &mut ComponentHooks)

👎Deprecated since 0.16.0: Use the individual hook methods instead (e.g., Component::on_add, etc.)

Called when registering this component, allowing mutable access to its ComponentHooks.

fn on_insert() -> Option<ComponentHook>

Gets the on_insert ComponentHook for this Component if one is defined.

fn on_replace() -> Option<ComponentHook>

Gets the on_replace ComponentHook for this Component if one is defined.

fn on_remove() -> Option<ComponentHook>

Gets the on_remove ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<ComponentHook>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn register_required_components( _component_id: ComponentId, _components: &mut ComponentsRegistrator<'_>, _required_components: &mut RequiredComponents, _inheritance_depth: u16, _recursion_check_stack: &mut Vec<ComponentId>, )

Registers required components.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn map_entities<E: EntityMapper>(_this: &mut Self, _mapper: &mut E)

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]