Observer

Struct Observer 

Source
pub struct Observer { /* private fields */ }
Expand description

An Observer system. Add this Component to an Entity to turn it into an “observer”.

Observers watch for a “trigger” of a specific Event. An event can be triggered on the World by calling World::trigger. It can also be queued up as a Command using Commands::trigger.

When a World triggers an Event, it will immediately run every Observer that watches for that Event.

§Usage

The simplest usage of the observer pattern looks like this:

#[derive(Event)]
struct Speak {
    message: String,
}

world.add_observer(|event: On<Speak>| {
    println!("{}", event.message);
});

world.trigger(Speak {
    message: "Hello!".into(),
});

Notice that we used World::add_observer. This is just a shorthand for spawning an Entity with an Observer manually:

// These are functionally the same:
world.add_observer(|event: On<Speak>| {});
world.spawn(Observer::new(|event: On<Speak>| {}));

Observers are a specialized System called an ObserverSystem. The first parameter must be On, which provides access to the Event, the Trigger, and some additional execution context.

Because they are systems, they can access arbitrary World data by adding SystemParams:

world.add_observer(|event: On<PrintNames>, names: Query<&Name>| {
    for name in &names {
        println!("{name:?}");
    }
});

You can also add Commands, which means you can spawn new entities, insert new components, etc:

world.add_observer(|event: On<SpawnThing>, mut commands: Commands| {
    commands.spawn(Thing);
});

Observers can also trigger new events:

world.add_observer(|event: On<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!

§Event Trigger behavior

Each Event defines a Trigger behavior, which determines which observers will run for the given Event and how they will be run.

Event by default (when derived) uses GlobalTrigger. When it is triggered any Observer watching for it will be run.

§Event sub-types

There are some built-in specialized Event types with custom Trigger logic:

You can also define your own!

§Observer execution timing

Observers triggered via World::trigger are evaluated immediately, as are all commands they queue up.

Observers triggered via Commands::trigger are evaluated at the next sync point in the ECS schedule, just like any other Command.

To control the relative ordering of observer trigger commands sent from different systems, order the systems in the schedule relative to each other.

Currently, Bevy does not provide a way to specify the relative ordering of observers watching for the same event. Their ordering is considered to be arbitrary. It is recommended to make no assumptions about their execution order.

Commands sent by observers are currently not immediately applied. Instead, all queued observers will run, and then all of the commands from those observers will be applied.

§ObservedBy

When entities are observed, they will receive an ObservedBy component, which will be updated to track the observers that are currently observing them.

§Manual Observer target configuration

You can manually control the targets that an observer is watching by calling builder methods like Observer::with_entity before inserting the Observer component.

In general, it is better to use the EntityWorldMut::observe or EntityCommands::observe methods, which spawns a new observer, and configures it to watch the entity it is called on.

§Cleaning up observers

If an EntityEvent Observer targets specific entities, and all of those entities are despawned, the Observer entity will also be despawned. This protects against observer “garbage” building up over time.

§Component lifecycle events: Observers vs Hooks

It is important to note that observers, just like hooks, can watch for and respond to lifecycle events. Unlike hooks, observers are not treated as an “innate” part of component behavior: they can be added or removed at runtime, and multiple observers can be registered for the same lifecycle event for the same component.

The ordering of hooks versus observers differs based on the lifecycle event in question:

  • when adding components, hooks are evaluated first, then observers
  • when removing components, observers are evaluated first, then hooks

This allows hooks to act as constructors and destructors for components, as they always have the first and final say in the component’s lifecycle.

§Observer re-targeting

Currently, observers cannot be retargeted after spawning: despawn and respawn an observer as a workaround.

§Internal observer cache

For more efficient observer triggering, Observers make use of the internal CachedObservers storage. In general, this is an implementation detail developers don’t need to worry about, but it can be used when implementing custom Trigger types, or to add “dynamic” observers for cases like scripting / modding.

Implementations§

Source§

impl Observer

Source

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 an event of type E is triggered.

§Panics

Panics if the given system is an exclusive system.

Source

pub fn with_dynamic_runner( runner: unsafe fn(DeferredWorld<'_>, Entity, &TriggerContext, PtrMut<'_>, PtrMut<'_>), ) -> Observer

Creates a new Observer with custom runner, this is mostly used for dynamic event observers

Source

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

Observes the given entity (in addition to any entity already being observed). This will cause the Observer to run whenever an EntityEvent::event_target is the given entity. Note that if this is called after an Observer is spawned, it will produce no effects.

Source

pub fn with_entities<I>(self, entities: I) -> Observer
where I: IntoIterator<Item = Entity>,

Observes the given entities (in addition to any entity already being observed). This will cause the Observer to run whenever an EntityEvent::event_target is any of the entities. Note that if this is called after an Observer is spawned, it will produce no effects.

Source

pub fn watch_entity(&mut self, entity: Entity)

Observes the given entity (in addition to any entity already being observed). This will cause the Observer to run whenever an EntityEvent::event_target is the given entity. Note that if this is called after an Observer is spawned, it will produce no effects.

Source

pub fn watch_entities<I>(&mut self, entities: I)
where I: IntoIterator<Item = Entity>,

Observes the given entity (in addition to any entity already being observed). This will cause the Observer to run whenever an EntityEvent::event_target is any of the entities. Note that if this is called after an Observer is spawned, it will produce no effects.

Source

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

Observes the given component. This will cause the Observer to run whenever the Event has an EntityComponentsTrigger that targets the given component.

Source

pub unsafe fn with_event_key(self, event_key: EventKey) -> Observer

Observes the given event_key. This will cause the Observer to run whenever an event with the given EventKey is triggered.

§Safety

The type of the event_key EventKey must match the actual value of the event passed into the observer system.

Source

pub fn with_error_handler( self, error_handler: fn(BevyError, ErrorContext), ) -> Observer

Sets the error handler to use for this observer.

See the error module-level documentation for more information.

Source

pub fn descriptor(&self) -> &ObserverDescriptor

Returns the ObserverDescriptor for this Observer.

Source

pub fn system_name(&self) -> DebugName

Returns the name of the Observer’s system .

Trait Implementations§

Source§

impl Component for Observer

Source§

const STORAGE_TYPE: StorageType = StorageType::SparseSet

A constant indicating the storage type used for this component.
Source§

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>. Read more
Source§

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

Gets the on_add ComponentHook for this Component if one is defined.
Source§

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

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

fn register_required_components( _component_id: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components. Read more
Source§

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

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

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

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

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

Gets the on_despawn ComponentHook for this Component if one is defined.
Source§

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component. Read more
Source§

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] Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T, U> AsBindGroupShaderType<U> for T
where U: ShaderType, &'a T: for<'a> Into<U>,

Source§

fn as_bind_group_shader_type(&self, _images: &RenderAssets<GpuImage>) -> U

Return the T ShaderType for self. When used in AsBindGroup derives, it is safe to assume that all images in self exist.
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<C> Bundle for C
where C: Component,

Source§

fn component_ids( components: &mut ComponentsRegistrator<'_>, ids: &mut impl FnMut(ComponentId), )

Source§

fn get_component_ids( components: &Components, ids: &mut impl FnMut(Option<ComponentId>), )

Gets this Bundle’s component ids. This will be None if the component has not been registered.
Source§

impl<C> BundleFromComponents for C
where C: Component,

Source§

unsafe fn from_components<T, F>(ctx: &mut T, func: &mut F) -> C
where F: for<'a> FnMut(&'a mut T) -> OwningPtr<'a>,

Source§

impl<T> Downcast for T
where T: Any,

Source§

fn into_any(self: Box<T>) -> Box<dyn Any>

Converts Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>, which can then be downcast into Box<dyn ConcreteType> where ConcreteType implements Trait.
Source§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Converts Rc<Trait> (where Trait: Downcast) to Rc<Any>, which can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
Source§

fn as_any(&self) -> &(dyn Any + 'static)

Converts &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
Source§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Converts &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
Source§

impl<T> Downcast for T
where T: Any,

Source§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
Source§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
Source§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
Source§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
Source§

impl<T> DowncastSend for T
where T: Any + Send,

Source§

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

Converts Box<Trait> (where Trait: DowncastSend) to Box<dyn Any + Send>, which can then be downcast into Box<ConcreteType> where ConcreteType implements Trait.
Source§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

Source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
Source§

impl<C> DynamicBundle for C
where C: Component,

Source§

type Effect = ()

An operation on the entity that happens after inserting this bundle.
Source§

unsafe fn get_components( ptr: MovingPtr<'_, C>, func: &mut impl FnMut(StorageType, OwningPtr<'_>), ) -> <C as DynamicBundle>::Effect

Moves the components out of the bundle. Read more
Source§

unsafe fn apply_effect( _ptr: MovingPtr<'_, MaybeUninit<C>>, _entity: &mut EntityWorldMut<'_>, )

Applies the after-effects of spawning this bundle. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, W> HasTypeWitness<W> for T
where W: MakeTypeWitness<Arg = T>, T: ?Sized,

Source§

const WITNESS: W = W::MAKE

A constant of the type witness
Source§

impl<T> Identity for T
where T: ?Sized,

Source§

const TYPE_EQ: TypeEq<T, <T as Identity>::Type> = TypeEq::NEW

Proof that Self is the same type as Self::Type, provides methods for casting between Self and Self::Type.
Source§

type Type = T

The same type as Self, used to emulate type equality bounds (T == U) with associated type equality constraints (T: Identity<Type = U>).
Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> IntoResult<T> for T

Source§

fn into_result(self) -> Result<T, RunSystemError>

Converts this type into the system output type.
Source§

impl<A> Is for A
where A: Any,

Source§

fn is<T>() -> bool
where T: Any,

Checks if the current type “is” another type, using a TypeId equality comparison. This is most useful in the context of generic logic. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

impl<T> ConditionalSend for T
where T: Send,

Source§

impl<T> Settings for T
where T: 'static + Send + Sync,

Source§

impl<T> WasmNotSend for T
where T: Send,

Source§

impl<T> WasmNotSendSync for T

Source§

impl<T> WasmNotSync for T
where T: Sync,