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.entity());
    commands.entity(trigger.entity()).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.entity()).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.

Trait Implementations

impl Component for Observer

const STORAGE_TYPE: StorageType = StorageType::SparseSet

A constant indicating the storage type used for this component.

fn register_component_hooks(hooks: &mut ComponentHooks)

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

fn register_required_components( _component_id: ComponentId, _components: &mut Components, _storages: &mut Storages, _required_components: &mut RequiredComponents, _inheritance_depth: u16, )

Registers required components.