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.

There are two ways of configuring hooks for a component:

1. Defining the relevant hooks on the Component implementation
2. Using the World::register_component_hooks method

Example

use bevy_ecs::prelude::*;
use bevy_platform::collections::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, context| {
   let mut tracked_entities = world.resource_mut::<TrackedEntities>();
  tracked_entities.0.insert(context.entity);
});

world.register_component_hooks::<MyTrackedComponent>().on_remove(|mut world, context| {
  let mut tracked_entities = world.resource_mut::<TrackedEntities>();
  tracked_entities.0.remove(&context.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: for<'w> fn(DeferredWorld<'w>, HookContext), ) -> &mut ComponentHooks

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: for<'w> fn(DeferredWorld<'w>, HookContext), ) -> &mut ComponentHooks

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 needs to be combined with immutable components to serve as a mechanism for reliably updating indexes and other caches.

Panics

Will panic if the component already has an on_insert hook

pub fn on_replace( &mut self, hook: for<'w> fn(DeferredWorld<'w>, HookContext), ) -> &mut ComponentHooks

Register a ComponentHook that will be run when this component is about to be dropped, such as being replaced (with .insert) or removed.

If this component is inserted onto an entity that already has it, this hook will run before the value is replaced, allowing access to the previous data just before it is dropped. This hook does not run if the entity did not already have this component.

An on_replace hook always runs before any on_remove hooks (if the component is being removed from the entity).

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 needs to be combined with immutable components to serve as a mechanism for reliably updating indexes and other caches.

Panics

Will panic if the component already has an on_replace hook

pub fn on_remove( &mut self, hook: for<'w> fn(DeferredWorld<'w>, HookContext), ) -> &mut ComponentHooks

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 on_despawn( &mut self, hook: for<'w> fn(DeferredWorld<'w>, HookContext), ) -> &mut ComponentHooks

Register a ComponentHook that will be run for each component on an entity when it is despawned.

Panics

Will panic if the component already has an on_despawn hook

pub fn try_on_add( &mut self, hook: for<'w> fn(DeferredWorld<'w>, HookContext), ) -> Option<&mut ComponentHooks>

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: for<'w> fn(DeferredWorld<'w>, HookContext), ) -> Option<&mut ComponentHooks>

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_replace( &mut self, hook: for<'w> fn(DeferredWorld<'w>, HookContext), ) -> Option<&mut ComponentHooks>

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

This is a fallible version of Self::on_replace.

Returns None if the component already has an on_replace hook.

pub fn try_on_remove( &mut self, hook: for<'w> fn(DeferredWorld<'w>, HookContext), ) -> Option<&mut ComponentHooks>

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.

pub fn try_on_despawn( &mut self, hook: for<'w> fn(DeferredWorld<'w>, HookContext), ) -> Option<&mut ComponentHooks>

Attempt to register a ComponentHook that will be run for each component on an entity when it is despawned.

This is a fallible version of Self::on_despawn.

Returns None if the component already has an on_despawn hook.

Trait Implementations

impl Clone for ComponentHooks

fn clone(&self) -> ComponentHooks

Returns a duplicate 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<(), Error>

Formats the value using the given formatter.

impl Default for ComponentHooks

fn default() -> ComponentHooks

Returns the “default value” for a type.