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, B, M, I>(system: I) -> Observer

where E: Event, B: Bundle, I: IntoObserverSystem<E, B, M>,

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).

Examples found in repository

examples/ecs/observers.rs (line 103)

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);
    commands.spawn((
        Text::new(
            "Click on a \"Mine\" to trigger it.\n\
            When it explodes it will trigger all overlapping mines.",
        ),
        Node {
            position_type: PositionType::Absolute,
            top: Val::Px(12.),
            left: Val::Px(12.),
            ..default()
        },
    ));

    let mut rng = ChaCha8Rng::seed_from_u64(19878367467713);

    commands
        .spawn(Mine::random(&mut rng))
        // Observers can watch for events targeting a specific entity.
        // This will create a new observer that runs whenever the Explode event
        // is triggered for this spawned entity.
        .observe(explode_mine);

    // We want to spawn a bunch of mines. We could just call the code above for each of them.
    // That would create a new observer instance for every Mine entity. Having duplicate observers
    // generally isn't worth worrying about as the overhead is low. But if you want to be maximally efficient,
    // you can reuse observers across entities.
    //
    // First, observers are actually just entities with the Observer component! The `observe()` functions
    // you've seen so far in this example are just shorthand for manually spawning an observer.
    let mut observer = Observer::new(explode_mine);

    // As we spawn entities, we can make this observer watch each of them:
    for _ in 0..1000 {
        let entity = commands.spawn(Mine::random(&mut rng)).id();
        observer.watch_entity(entity);
    }

    // By spawning the Observer component, it becomes active!
    commands.spawn(observer);
}

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

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.

Examples found in repository

examples/ecs/observers.rs (line 108)

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);
    commands.spawn((
        Text::new(
            "Click on a \"Mine\" to trigger it.\n\
            When it explodes it will trigger all overlapping mines.",
        ),
        Node {
            position_type: PositionType::Absolute,
            top: Val::Px(12.),
            left: Val::Px(12.),
            ..default()
        },
    ));

    let mut rng = ChaCha8Rng::seed_from_u64(19878367467713);

    commands
        .spawn(Mine::random(&mut rng))
        // Observers can watch for events targeting a specific entity.
        // This will create a new observer that runs whenever the Explode event
        // is triggered for this spawned entity.
        .observe(explode_mine);

    // We want to spawn a bunch of mines. We could just call the code above for each of them.
    // That would create a new observer instance for every Mine entity. Having duplicate observers
    // generally isn't worth worrying about as the overhead is low. But if you want to be maximally efficient,
    // you can reuse observers across entities.
    //
    // First, observers are actually just entities with the Observer component! The `observe()` functions
    // you've seen so far in this example are just shorthand for manually spawning an observer.
    let mut observer = Observer::new(explode_mine);

    // As we spawn entities, we can make this observer watch each of them:
    for _ in 0..1000 {
        let entity = commands.spawn(Mine::random(&mut rng)).id();
        observer.watch_entity(entity);
    }

    // By spawning the Observer component, it becomes active!
    commands.spawn(observer);
}

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

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) -> Observer

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), ) -> Observer

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<for<'w> fn(DeferredWorld<'w>, HookContext)>

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<for<'w> fn(DeferredWorld<'w>, HookContext)>

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

fn on_replace() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

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

fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

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

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

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>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

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]