Struct bevy::ecs::component::ComponentHooks

pub struct ComponentHooks { /* private fields */ }

Lifecycle hooks for a given Component, stored in its ComponentInfo

Implementations

impl ComponentHooks

pub fn on_add( &mut self, hook: for<'w> fn(_: DeferredWorld<'w>, _: Entity, _: ComponentId) ) -> &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.

Will panic if the component already has an on_add hook

Examples found in repository

examples/ecs/component_hooks.rs (lines 63-76)

fn setup(world: &mut World) {
    // In order to register component hooks the component must:
    // - not be currently in use by any entities in the world
    // - not already have a hook of that kind registered
    // This is to prevent overriding hooks defined in plugins and other crates as well as keeping things fast
    world
        .register_component_hooks::<MyComponent>()
        // There are 3 component lifecycle hooks: `on_add`, `on_insert` and `on_remove`
        // A hook has 3 arguments:
        // - a `DeferredWorld`, this allows access to resource and component data as well as `Commands`
        // - the entity that triggered the hook
        // - the component id of the triggering component, this is mostly used for dynamic components
        //
        // `on_add` will trigger when a component is inserted onto an entity without it
        .on_add(|mut world, entity, component_id| {
            // You can access component data from within the hook
            let value = world.get::<MyComponent>(entity).unwrap().0;
            println!(
                "Component: {:?} added to: {:?} with value {:?}",
                component_id, entity, value
            );
            // Or access resources
            world
                .resource_mut::<MyComponentIndex>()
                .insert(value, entity);
            // Or send events
            world.send_event(MyEvent);
        })
        // `on_insert` will trigger when a component is inserted onto an entity,
        // regardless of whether or not it already had it and after `on_add` if it ran
        .on_insert(|world, _, _| {
            println!("Current Index: {:?}", world.resource::<MyComponentIndex>());
        })
        // `on_remove` will trigger when a component is removed from an entity,
        // since it runs before the component is removed you can still access the component data
        .on_remove(|mut world, entity, component_id| {
            let value = world.get::<MyComponent>(entity).unwrap().0;
            println!(
                "Component: {:?} removed from: {:?} with value {:?}",
                component_id, entity, value
            );
            world.resource_mut::<MyComponentIndex>().remove(&value);
            // You can also issue commands through `.commands()`
            world.commands().entity(entity).despawn();
        });
}

pub fn on_insert( &mut self, hook: for<'w> fn(_: DeferredWorld<'w>, _: Entity, _: ComponentId) ) -> &mut ComponentHooks

Register a ComponentHook that will be run when this component is added (with .insert) or replaced. The hook won’t run if the component is already present and is only mutated. An on_insert hook always runs after any on_add hooks (if the entity didn’t already have the component).

Will panic if the component already has an on_insert hook

Examples found in repository

examples/ecs/component_hooks.rs (lines 79-81)

fn setup(world: &mut World) {
    // In order to register component hooks the component must:
    // - not be currently in use by any entities in the world
    // - not already have a hook of that kind registered
    // This is to prevent overriding hooks defined in plugins and other crates as well as keeping things fast
    world
        .register_component_hooks::<MyComponent>()
        // There are 3 component lifecycle hooks: `on_add`, `on_insert` and `on_remove`
        // A hook has 3 arguments:
        // - a `DeferredWorld`, this allows access to resource and component data as well as `Commands`
        // - the entity that triggered the hook
        // - the component id of the triggering component, this is mostly used for dynamic components
        //
        // `on_add` will trigger when a component is inserted onto an entity without it
        .on_add(|mut world, entity, component_id| {
            // You can access component data from within the hook
            let value = world.get::<MyComponent>(entity).unwrap().0;
            println!(
                "Component: {:?} added to: {:?} with value {:?}",
                component_id, entity, value
            );
            // Or access resources
            world
                .resource_mut::<MyComponentIndex>()
                .insert(value, entity);
            // Or send events
            world.send_event(MyEvent);
        })
        // `on_insert` will trigger when a component is inserted onto an entity,
        // regardless of whether or not it already had it and after `on_add` if it ran
        .on_insert(|world, _, _| {
            println!("Current Index: {:?}", world.resource::<MyComponentIndex>());
        })
        // `on_remove` will trigger when a component is removed from an entity,
        // since it runs before the component is removed you can still access the component data
        .on_remove(|mut world, entity, component_id| {
            let value = world.get::<MyComponent>(entity).unwrap().0;
            println!(
                "Component: {:?} removed from: {:?} with value {:?}",
                component_id, entity, value
            );
            world.resource_mut::<MyComponentIndex>().remove(&value);
            // You can also issue commands through `.commands()`
            world.commands().entity(entity).despawn();
        });
}

pub fn on_remove( &mut self, hook: for<'w> fn(_: DeferredWorld<'w>, _: Entity, _: ComponentId) ) -> &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.

Will panic if the component already has an on_remove hook

Examples found in repository

examples/ecs/component_hooks.rs (lines 84-93)

fn setup(world: &mut World) {
    // In order to register component hooks the component must:
    // - not be currently in use by any entities in the world
    // - not already have a hook of that kind registered
    // This is to prevent overriding hooks defined in plugins and other crates as well as keeping things fast
    world
        .register_component_hooks::<MyComponent>()
        // There are 3 component lifecycle hooks: `on_add`, `on_insert` and `on_remove`
        // A hook has 3 arguments:
        // - a `DeferredWorld`, this allows access to resource and component data as well as `Commands`
        // - the entity that triggered the hook
        // - the component id of the triggering component, this is mostly used for dynamic components
        //
        // `on_add` will trigger when a component is inserted onto an entity without it
        .on_add(|mut world, entity, component_id| {
            // You can access component data from within the hook
            let value = world.get::<MyComponent>(entity).unwrap().0;
            println!(
                "Component: {:?} added to: {:?} with value {:?}",
                component_id, entity, value
            );
            // Or access resources
            world
                .resource_mut::<MyComponentIndex>()
                .insert(value, entity);
            // Or send events
            world.send_event(MyEvent);
        })
        // `on_insert` will trigger when a component is inserted onto an entity,
        // regardless of whether or not it already had it and after `on_add` if it ran
        .on_insert(|world, _, _| {
            println!("Current Index: {:?}", world.resource::<MyComponentIndex>());
        })
        // `on_remove` will trigger when a component is removed from an entity,
        // since it runs before the component is removed you can still access the component data
        .on_remove(|mut world, entity, component_id| {
            let value = world.get::<MyComponent>(entity).unwrap().0;
            println!(
                "Component: {:?} removed from: {:?} with value {:?}",
                component_id, entity, value
            );
            world.resource_mut::<MyComponentIndex>().remove(&value);
            // You can also issue commands through `.commands()`
            world.commands().entity(entity).despawn();
        });
}

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

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>, _: Entity, _: ComponentId) ) -> Option<&mut ComponentHooks>

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

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

Formats the value using the given formatter.

impl Default for ComponentHooks

fn default() -> ComponentHooks

Returns the “default value” for a type.