Struct Trigger

pub struct Trigger<'w, E, B: Bundle = ()> { /* private fields */ }

Type containing triggered Event information for a given run of an Observer. This contains the Event data itself. If it was triggered for a specific Entity, it includes that as well. It also contains event propagation information. See Trigger::propagate for more information.

Implementations

impl<'w, E, B: Bundle> Trigger<'w, E, B>

pub fn new( event: &'w mut E, propagate: &'w mut bool, trigger: ObserverTrigger, ) -> Self

Creates a new trigger for the given event and observer information.

pub fn event_type(&self) -> ComponentId

Returns the event type of this trigger.

pub fn event(&self) -> &E

Returns a reference to the triggered event.

pub fn event_mut(&mut self) -> &mut E

Returns a mutable reference to the triggered event.

pub fn event_ptr(&self) -> Ptr<'_>

Returns a pointer to the triggered event.

pub fn target(&self) -> Entity

Returns the Entity that was targeted by the event that triggered this observer. It may be Entity::PLACEHOLDER.

Observable events can target specific entities. When those events fire, they will trigger any observers on the targeted entities. In this case, the target() and observer() are the same, because the observer that was triggered is attached to the entity that was targeted by the event.

However, it is also possible for those events to bubble up the entity hierarchy and trigger observers on different entities, or trigger a global observer. In these cases, the observing entity is different from the entity being targeted by the event.

This is an important distinction: the entity reacting to an event is not always the same as the entity triggered by the event.

pub fn components(&self) -> &[ComponentId]

Returns the components that triggered the observer, out of the components defined in B. Does not necessarily include all of them as B acts like an OR filter rather than an AND filter.

pub fn observer(&self) -> Entity

Returns the Entity that observed the triggered event. This allows you to despawn the observer, ceasing observation.

Examples

/// Handle `MyEvent` and if it is done, stop observation.
fn my_observer(trigger: Trigger<MyEvent>, mut commands: Commands) {
    if trigger.event().done {
        commands.entity(trigger.observer()).despawn();
        return;
    }

    // ...
}

pub fn propagate(&mut self, should_propagate: bool)

Enables or disables event propagation, allowing the same event to trigger observers on a chain of different entities.

The path an event will propagate along is specified by its associated Traversal component. By default, events use () which ends the path immediately and prevents propagation.

To enable propagation, you must:

• Set Event::Traversal to the component you want to propagate along.
• Either call propagate(true) in the first observer or set Event::AUTO_PROPAGATE to true.

You can prevent an event from propagating further using propagate(false).

pub fn get_propagate(&self) -> bool

Returns the value of the flag that controls event propagation. See propagate for more information.

pub fn caller(&self) -> MaybeLocation

Returns the source code location that triggered this observer.

Trait Implementations

impl<'w, E: Debug, B: Bundle> Debug for Trigger<'w, E, B>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'w, E, B: Bundle> Deref for Trigger<'w, E, B>

type Target = E

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'w, E, B: Bundle> DerefMut for Trigger<'w, E, B>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<E: 'static, B: Bundle> SystemInput for Trigger<'_, E, B>

Used for ObserverSystems.

type Param<'i> = Trigger<'i, E, B>

The wrapper input type that is defined as the first argument to FunctionSystems.

type Inner<'i> = Trigger<'i, E, B>

The inner input type that is passed to functions that run systems, such as System::run.

fn wrap(this: Self::Inner<'_>) -> Self::Param<'_>

Converts a SystemInput::Inner into a SystemInput::Param.