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
impl ComponentHooks
sourcepub fn on_add(&mut self, hook: ComponentHook) -> &mut Self
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
sourcepub fn on_insert(&mut self, hook: ComponentHook) -> &mut Self
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
sourcepub fn on_remove(&mut self, hook: ComponentHook) -> &mut Self
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
sourcepub fn try_on_add(&mut self, hook: ComponentHook) -> Option<&mut Self>
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.
sourcepub fn try_on_insert(&mut self, hook: ComponentHook) -> Option<&mut Self>
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.
sourcepub fn try_on_remove(&mut self, hook: ComponentHook) -> Option<&mut Self>
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
impl Clone for ComponentHooks
source§fn clone(&self) -> ComponentHooks
fn clone(&self) -> ComponentHooks
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for ComponentHooks
impl Debug for ComponentHooks
source§impl Default for ComponentHooks
impl Default for ComponentHooks
source§fn default() -> ComponentHooks
fn default() -> ComponentHooks
Auto Trait Implementations§
impl Freeze for ComponentHooks
impl RefUnwindSafe for ComponentHooks
impl Send for ComponentHooks
impl Sync for ComponentHooks
impl Unpin for ComponentHooks
impl UnwindSafe for ComponentHooks
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
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>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
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)
fn as_any(&self) -> &(dyn Any + 'static)
&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)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&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
impl<T> DowncastSync for T
source§impl<T> FromWorld for Twhere
T: Default,
impl<T> FromWorld for Twhere
T: Default,
source§fn from_world(_world: &mut World) -> T
fn from_world(_world: &mut World) -> T
Self
using data from the given World
.