Struct bevy_ecs::component::ComponentHooks

source ·
pub struct ComponentHooks { /* private fields */ }
Expand description

World-mutating functions that run as part of lifecycle events of a Component.

Hooks are functions that run when a component is added, overwritten, or removed from an entity. These are intended to be used for structural side effects that need to happen when a component is added or removed, and are not intended for general-purpose logic.

For example, you might use a hook to update a cached index when a component is added, to clean up resources when a component is removed, or to keep hierarchical data structures across entities in sync.

This information is stored in the ComponentInfo of the associated component.

§Example

use bevy_ecs::prelude::*;
use bevy_utils::HashSet;

#[derive(Component)]
struct MyTrackedComponent;

#[derive(Resource, Default)]
struct TrackedEntities(HashSet<Entity>);

let mut world = World::new();
world.init_resource::<TrackedEntities>();

// No entities with `MyTrackedComponent` have been added yet, so we can safely add component hooks
let mut tracked_component_query = world.query::<&MyTrackedComponent>();
assert!(tracked_component_query.iter(&world).next().is_none());

world.register_component_hooks::<MyTrackedComponent>().on_add(|mut world, entity, _component_id| {
   let mut tracked_entities = world.resource_mut::<TrackedEntities>();
  tracked_entities.0.insert(entity);
});

world.register_component_hooks::<MyTrackedComponent>().on_remove(|mut world, entity, _component_id| {
  let mut tracked_entities = world.resource_mut::<TrackedEntities>();
  tracked_entities.0.remove(&entity);
});

let entity = world.spawn(MyTrackedComponent).id();
let tracked_entities = world.resource::<TrackedEntities>();
assert!(tracked_entities.0.contains(&entity));

world.despawn(entity);
let tracked_entities = world.resource::<TrackedEntities>();
assert!(!tracked_entities.0.contains(&entity));

Implementations§

source§

impl ComponentHooks

source

pub fn on_add(&mut self, hook: ComponentHook) -> &mut Self

Register a ComponentHook that will be run when this component is added to an entity. An on_add hook will always run before on_insert hooks. Spawning an entity counts as adding all of its components.

§Panics

Will panic if the component already has an on_add hook

source

pub fn on_insert(&mut self, hook: ComponentHook) -> &mut Self

Register a ComponentHook that will be run when this component is added (with .insert) or replaced.

An on_insert hook always runs after any on_add hooks (if the entity didn’t already have the component).

§Warning

The hook won’t run if the component is already present and is only mutated, such as in a system via a query. As a result, this is not an appropriate mechanism for reliably updating indexes and other caches.

§Panics

Will panic if the component already has an on_insert hook

source

pub fn on_remove(&mut self, hook: ComponentHook) -> &mut Self

Register a ComponentHook that will be run when this component is removed from an entity. Despawning an entity counts as removing all of its components.

§Panics

Will panic if the component already has an on_remove hook

source

pub fn try_on_add(&mut self, hook: ComponentHook) -> Option<&mut Self>

Attempt to register a ComponentHook that will be run when this component is added to an entity.

This is a fallible version of Self::on_add.

Returns None if the component already has an on_add hook.

source

pub fn try_on_insert(&mut self, hook: ComponentHook) -> Option<&mut Self>

Attempt to register a ComponentHook that will be run when this component is added (with .insert)

This is a fallible version of Self::on_insert.

Returns None if the component already has an on_insert hook.

source

pub fn try_on_remove(&mut self, hook: ComponentHook) -> Option<&mut Self>

Attempt to register a ComponentHook that will be run when this component is removed from an entity.

This is a fallible version of Self::on_remove.

Returns None if the component already has an on_remove hook.

Trait Implementations§

source§

impl Clone for ComponentHooks

source§

fn clone(&self) -> ComponentHooks

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for ComponentHooks

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for ComponentHooks

source§

fn default() -> ComponentHooks

Returns the “default value” for a type. 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> 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<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> 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<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> FromWorld for T
where T: Default,

source§

fn from_world(_world: &mut World) -> T

Creates Self using data from the given World.
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> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

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

§

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>,

§

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> TypeData for T
where T: 'static + Send + Sync + Clone,

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,