Struct ComponentHooks

pub struct ComponentHooks { /* private fields */ }

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

impl ComponentHooks

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

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

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

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.

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.

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

impl Clone for ComponentHooks

fn clone(&self) -> ComponentHooks

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ComponentHooks

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

Formats the value using the given formatter.

impl Default for ComponentHooks

fn default() -> ComponentHooks

Returns the “default value” for a type.