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.

fn len(&self) -> usize

Returns the number of entities in this collection.

fn is_empty(&self) -> bool

Returns true if this entity collection is empty.

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>