Trait EntityEvent

Source

pub trait EntityEvent: Event {
    // Required methods
    fn event_target(&self) -> Entity;
    fn event_target_mut(&mut self) -> &mut Entity;
}

Expand description

An EntityEvent is an Event that is triggered for a specific EntityEvent::event_target entity:

#[derive(EntityEvent)]
struct Explode {
    entity: Entity,
}

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

world.trigger(Explode { entity });

EntityEvent will set EntityEvent::event_target automatically for named structs with an entity field name (as seen above). It also works for tuple structs whose only field is Entity:

#[derive(EntityEvent)]
struct Explode(Entity);

The EntityEvent::event_target can also be manually set using the #[event_target] field attribute:

#[derive(EntityEvent)]
struct Explode {
    #[event_target]
    exploded_entity: Entity,
}

#[derive(EntityEvent)]
struct Explode(#[event_target] Entity);

§Trigger Behavior

When derived, EntityEvent defaults to setting Event::Trigger to EntityTrigger, which will run all normal “untargeted” observers added via World::add_observer, just like a default Event would (see the example above).

However it will also run all observers that watch specific entities, which enables you to assign entity-specific logic:

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

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

§`EntityEvent` Propagation

When deriving EntityEvent, you can enable “event propagation” (also known as “event bubbling”) by specifying the #[entity_event(propagate)] attribute:

#[derive(EntityEvent)]
#[entity_event(propagate)]
struct Click {
    entity: Entity,
}

This will default to using the ChildOf component to propagate the Event “up” the hierarchy (from child to parent).

You can also specify your own Traversal implementation. A common pattern is to use Relationship components, which will follow the relationships to their root (just be sure to avoid cycles … these aren’t detected for performance reasons):

#[derive(Component)]
#[relationship(relationship_target = ClickableBy)]
struct Clickable(Entity);

#[derive(Component)]
#[relationship_target(relationship = Clickable)]
struct ClickableBy(Vec<Entity>);

#[derive(EntityEvent)]
#[entity_event(propagate = &'static Clickable)]
struct Click {
    entity: Entity,
}

By default, propagation requires observers to opt-in:

#[derive(EntityEvent)]
#[entity_event(propagate)]
struct Click {
    entity: Entity,
}

world.add_observer(|mut click: On<Click>| {
  // this will propagate the event up to the parent, using `ChildOf`
  click.propagate(true);
});

But you can enable auto propagation using the #[entity_event(auto_propagate)] attribute:

#[derive(EntityEvent)]
#[entity_event(propagate, auto_propagate)]
struct Click {
    entity: Entity,
}

You can also stop propagation like this:

world.add_observer(|mut click: On<Click>| {
  if is_finished_propagating() {
    click.propagate(false);
  }
});

§Naming and Usage Conventions

In most cases, it is recommended to use a named struct field for the “event target” entity, and to use a name that is descriptive as possible, as this makes events easier to understand and read.

For events with only one Entity field, entity is often a reasonable name. But if there are multiple Entity fields, it is often a good idea to use a more descriptive name.

It is also generally recommended to consume “event target” entities directly via their named field, as this can make the context clearer, allows for more specific documentation hints in IDEs, and it generally reads better.

§Manually spawning `EntityEvent` observers

The examples above that call EntityWorldMut::observe to add entity-specific observer logic are just shorthand for spawning an Observer directly and manually watching the entity:

let mut observer = Observer::new(|event: On<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, as there can be multiple observers of the same entity!

You can call Observer::watch_entity more than once or Observer::watch_entities to watch multiple entities with the same Observer.

Required Methods§

Source

fn event_target(&self) -> Entity

The Entity “target” of this EntityEvent. When triggered, this will run observers that watch for this specific entity.

Source

fn event_target_mut(&mut self) -> &mut Entity

Returns a mutable reference to the Entity “target” of this EntityEvent. When triggered, this will run observers that watch for this specific entity.

Note: In general, this should not be mutated from within an Observer, as this will not “retarget” the event in any of Bevy’s built-in Trigger implementations.