Trait RelationshipTarget 

pub trait RelationshipTarget: Sized + Component<Mutability = Mutable> {
    type Relationship: Relationship<RelationshipTarget = Self>;
    type Collection: RelationshipSourceCollection;

    const LINKED_SPAWN: bool;

    // Required methods
    fn collection(&self) -> &Self::Collection;
    fn collection_mut_risky(&mut self) -> &mut Self::Collection;
    fn from_collection_risky(collection: Self::Collection) -> Self;

    // Provided methods
    fn on_replace(world: DeferredWorld<'_>, _: HookContext) { ... }
    fn on_despawn(world: DeferredWorld<'_>, _: HookContext) { ... }
    fn with_capacity(capacity: usize) -> Self { ... }
    fn iter(
        &self,
    ) -> <Self::Collection as RelationshipSourceCollection>::SourceIter<'_> { ... }
    fn len(&self) -> usize { ... }
    fn is_empty(&self) -> bool { ... }
}

A Component containing the collection of entities that relate to this Entity via the associated Relationship type. See the Relationship documentation for more information.

Required Associated Constants

const LINKED_SPAWN: bool

If this is true, when despawning or cloning (when linked cloning is enabled), the related entities targeting this entity will also be despawned or cloned.

For example, this is set to true for Bevy’s built-in parent-child relation, defined by ChildOf and Children. This means that when a parent is despawned, any children targeting that parent are also despawned (and the same applies to cloning).

To get around this behavior, you can first break the relationship between entities, and then despawn or clone. This defaults to false when derived.

Required Associated Types

type Relationship: Relationship<RelationshipTarget = Self>

The Relationship that populates this RelationshipTarget collection.

type Collection: RelationshipSourceCollection

The collection type that stores the “source” entities for this RelationshipTarget component.

Check the list of types which implement RelationshipSourceCollection for the data structures that can be used inside of your component. If you need a new collection type, you can implement the RelationshipSourceCollection trait for a type you own which wraps the collection you want to use (to avoid the orphan rule), or open an issue on the Bevy repository to request first-party support for your collection type.

Required Methods

fn collection(&self) -> &Self::Collection

Returns a reference to the stored RelationshipTarget::Collection.

fn collection_mut_risky(&mut self) -> &mut Self::Collection

Returns a mutable reference to the stored RelationshipTarget::Collection.

Warning

This should generally not be called by user code, as modifying the internal collection could invalidate the relationship. The collection should not contain duplicates.

fn from_collection_risky(collection: Self::Collection) -> Self

Creates a new RelationshipTarget from the given RelationshipTarget::Collection.

Warning

This should generally not be called by user code, as constructing the internal collection could invalidate the relationship. The collection should not contain duplicates.

Provided Methods

fn on_replace(world: DeferredWorld<'_>, _: HookContext)

The on_replace component hook that maintains the Relationship / RelationshipTarget connection.

fn on_despawn(world: DeferredWorld<'_>, _: HookContext)

The on_despawn component hook that despawns entities stored in an entity’s RelationshipTarget when that entity is despawned.

fn with_capacity(capacity: usize) -> Self

Creates this RelationshipTarget with the given pre-allocated entity capacity.

fn iter( &self, ) -> <Self::Collection as RelationshipSourceCollection>::SourceIter<'_>

Iterates the entities stored in this collection.

Examples found in repository

examples/ui/text_background_colors.rs (line 74)

fn cycle_text_background_colors(
    time: Res<Time>,
    children_query: Query<&Children, With<Text>>,
    mut text_background_colors_query: Query<&mut TextBackgroundColor>,
) {
    let n = time.elapsed_secs() as usize;
    let children = children_query.single().unwrap();

    for (i, child) in children.iter().enumerate() {
        text_background_colors_query.get_mut(child).unwrap().0 = PALETTE[(i + n) % PALETTE.len()];
    }
}

examples/usage/context_menu.rs (line 52)

fn text_color_on_hover<T: Debug + Clone + Reflect>(
    color: Color,
) -> impl FnMut(On<Pointer<T>>, Query<&mut TextColor>, Query<&Children>) {
    move |mut event: On<Pointer<T>>,
          mut text_color: Query<&mut TextColor>,
          children: Query<&Children>| {
        let Ok(children) = children.get(event.original_event_target()) else {
            return;
        };
        event.propagate(false);

        // find the text among children and change its color
        for child in children.iter() {
            if let Ok(mut col) = text_color.get_mut(child) {
                col.0 = color;
            }
        }
    }
}

examples/3d/motion_blur.rs (line 318)

fn move_cars(
    time: Res<Time>,
    mut movables: Query<(&mut Transform, &Moves, &Children)>,
    mut spins: Query<&mut Transform, (Without<Moves>, With<Rotates>)>,
) {
    for (mut transform, moves, children) in &mut movables {
        let time = time.elapsed_secs() * 0.25;
        let t = time + 0.5 * moves.0;
        let dx = ops::cos(t);
        let dz = -ops::sin(3.0 * t);
        let speed_variation = (dx * dx + dz * dz).sqrt() * 0.15;
        let t = t + speed_variation;
        let prev = transform.translation;
        transform.translation.x = race_track_pos(0.0, t).x;
        transform.translation.z = race_track_pos(0.0, t).y;
        transform.translation.y = -0.59;
        let delta = transform.translation - prev;
        transform.look_to(delta, Vec3::Y);
        for child in children.iter() {
            let Ok(mut wheel) = spins.get_mut(child) else {
                continue;
            };
            let radius = wheel.scale.x;
            let circumference = 2.0 * std::f32::consts::PI * radius;
            let angle = delta.length() / circumference * std::f32::consts::PI * 2.0;
            wheel.rotate_local_y(angle);
        }
    }
}

examples/ecs/relationships.rs (line 90)

    fn debug_relationships(
        // Not all of our entities are targeted by something, so we use `Option` in our query to handle this case.
        relations_query: Query<(&Name, &Targeting, Option<&TargetedBy>)>,
        name_query: Query<&Name>,
    ) {
        let mut relationships = String::new();

        for (name, targeting, maybe_targeted_by) in relations_query.iter() {
            let targeting_name = name_query.get(targeting.0).unwrap();
            let targeted_by_string = if let Some(targeted_by) = maybe_targeted_by {
                let mut vec_of_names = Vec::<&Name>::new();

                for entity in targeted_by.iter() {
                    let name = name_query.get(entity).unwrap();
                    vec_of_names.push(name);
                }

                // Convert this to a nice string for printing.
                let vec_of_str: Vec<&str> = vec_of_names.iter().map(|name| name.as_str()).collect();
                vec_of_str.join(", ")
            } else {
                "nobody".to_string()
            };

            relationships.push_str(&format!(
                "{name} is targeting {targeting_name}, and is targeted by {targeted_by_string}\n",
            ));
        }

        println!("{relationships}");
    }

fn len(&self) -> usize

Returns the number of entities in this collection.

Examples found in repository

examples/ecs/hierarchy.rs (line 82)

fn rotate(
    mut commands: Commands,
    time: Res<Time>,
    mut parents_query: Query<(Entity, &Children), With<Sprite>>,
    mut transform_query: Query<&mut Transform, With<Sprite>>,
) {
    for (parent, children) in &mut parents_query {
        if let Ok(mut transform) = transform_query.get_mut(parent) {
            transform.rotate_z(-PI / 2. * time.delta_secs());
        }

        // To iterate through the entities children, just treat the Children component as a Vec
        // Alternatively, you could query entities that have a ChildOf component
        for child in children {
            if let Ok(mut transform) = transform_query.get_mut(*child) {
                transform.rotate_z(PI * time.delta_secs());
            }
        }

        // To demonstrate removing children, we'll remove a child after a couple of seconds.
        if time.elapsed_secs() >= 2.0 && children.len() == 2 {
            let child = children.last().unwrap();
            commands.entity(*child).despawn();
        }

        if time.elapsed_secs() >= 4.0 {
            // This will remove the entity from its parent's list of children, as well as despawn
            // any children the entity has.
            commands.entity(parent).despawn();
        }
    }
}

fn is_empty(&self) -> bool

Returns true if this entity collection is empty.

Examples found in repository

examples/ui/standard_widgets_observers.rs (line 179)

fn button_on_interaction<E: EntityEvent, C: Component>(
    event: On<E, C>,
    mut buttons: Query<
        (
            &Hovered,
            Has<InteractionDisabled>,
            Has<Pressed>,
            &mut BackgroundColor,
            &mut BorderColor,
            &Children,
        ),
        With<DemoButton>,
    >,
    mut text_query: Query<&mut Text>,
) {
    if let Ok((hovered, disabled, pressed, mut color, mut border_color, children)) =
        buttons.get_mut(event.event_target())
    {
        if children.is_empty() {
            return;
        }
        let Ok(mut text) = text_query.get_mut(children[0]) else {
            return;
        };
        let hovered = hovered.get();
        // These "removal event checks" exist because the `Remove` event is triggered _before_ the component is actually
        // removed, meaning it still shows up in the query. We're investigating the best way to improve this scenario.
        let pressed = pressed && !(E::is::<Remove>() && C::is::<Pressed>());
        let disabled = disabled && !(E::is::<Remove>() && C::is::<InteractionDisabled>());
        match (disabled, hovered, pressed) {
            // Disabled button
            (true, _, _) => {
                **text = "Disabled".to_string();
                *color = NORMAL_BUTTON.into();
                border_color.set_all(GRAY);
            }

            // Pressed and hovered button
            (false, true, true) => {
                **text = "Press".to_string();
                *color = PRESSED_BUTTON.into();
                border_color.set_all(RED);
            }

            // Hovered, unpressed button
            (false, true, false) => {
                **text = "Hover".to_string();
                *color = HOVERED_BUTTON.into();
                border_color.set_all(WHITE);
            }

            // Unhovered button (either pressed or not).
            (false, false, _) => {
                **text = "Button".to_string();
                *color = NORMAL_BUTTON.into();
                border_color.set_all(BLACK);
            }
        }
    }
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl RelationshipTarget for Children

const LINKED_SPAWN: bool = true

type Relationship = ChildOf

type Collection = Vec<Entity>