Struct On

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

A system parameter used by an observer to process events. See Observer and Event for examples.

On contains the triggered Event data for a given run of an Observer. It also provides access to the Trigger, which for things like EntityEvent with a PropagateEntityTrigger, includes control over event propagation.

The generic B: Bundle is used to further specialize the events that this observer is interested in. The entity involved does not have to have these components, but the observer will only be triggered if the event matches the components in B.

This is used to to avoid providing a generic argument in your event, as is done for Add and the other lifecycle events.

Providing multiple components in this bundle will cause this event to be triggered by any matching component in the bundle, rather than requiring all of them to be present.

Implementations

impl<'w, 't, E: Event, B: Bundle> On<'w, 't, E, B>

pub fn new( event: &'w mut E, observer: Entity, trigger: &'w mut E::Trigger<'t>, trigger_context: &'w TriggerContext, ) -> Self

Creates a new instance of On for the given triggered event.

pub fn event_key(&self) -> EventKey

Returns the event type of this On instance.

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 trigger(&self) -> &E::Trigger<'t>

Returns the Trigger context for this event.

pub fn trigger_mut(&mut self) -> &mut E::Trigger<'t>

Returns the mutable Trigger context for this event.

pub fn observer(&self) -> Entity

Returns the Entity of the Observer of the triggered event. This allows you to despawn the observer, ceasing observation.

Examples

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

fn assert_observer(event: On<AssertEvent>) {  
    assert_eq!(event.observer(), event.entity);  
}  

let mut world = World::new();  
let entity = world.spawn(Observer::new(assert_observer)).id();  

world.trigger(AssertEvent { entity });  

pub fn caller(&self) -> MaybeLocation

Returns the source code location that triggered this observer, if the track_location cargo feature is enabled.

impl<'w, 't, E: EntityEvent, B: Bundle> On<'w, 't, E, B>

pub fn target(&self) -> Entity

👎Deprecated since 0.17.0: Call On::event() to access the event, then read the target entity from the event directly.

A deprecated way to retrieve the entity that this EntityEvent targeted at.

Access the event via On::event, then read the entity that the event was targeting. Prefer using the field name directly for clarity, but if you are working in a generic context, you can use EntityEvent::event_target.

impl<'w, 't, const AUTO_PROPAGATE: bool, E: EntityEvent + for<'a> Event<Trigger<'a> = PropagateEntityTrigger<AUTO_PROPAGATE, E, T>>, B: Bundle, T: Traversal<E>> On<'w, 't, E, B>

pub fn original_event_target(&self) -> Entity

Returns the original Entity that this EntityEvent targeted via EntityEvent::event_target when it was first triggered, prior to any propagation logic.

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 EntityEvent will propagate along is specified by the Traversal component defined in PropagateEntityTrigger.

EntityEvent does not propagate by default. To enable propagation, you must:

• Enable propagation in EntityEvent using #[entity_event(propagate)]. See EntityEvent for details.
• Either call propagate(true) in the first observer or in the EntityEvent derive add #[entity_event(auto_propagate)].

You can prevent an event from propagating further using propagate(false). This will prevent the event from triggering on the next Entity in the Traversal, but note that all remaining observers for the current entity will still run.

pub fn get_propagate(&self) -> bool

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

Trait Implementations

impl<'w, 't, E: for<'a> Event<Trigger<'a>: Debug> + Debug, B: Bundle> Debug for On<'w, 't, E, B>

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

Formats the value using the given formatter.

impl<'w, 't, E: Event, B: Bundle> Deref for On<'w, 't, E, B>

type Target = E

The resulting type after dereferencing.

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

Dereferences the value.

impl<'w, 't, E: Event, B: Bundle> DerefMut for On<'w, 't, E, B>

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

Mutably dereferences the value.

impl<E: Event, B: Bundle> SystemInput for On<'_, '_, E, B>

Used for ObserverSystems.

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

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

type Inner<'i> = On<'i, '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.