Trait Relationship

pub trait Relationship: Component + Sized {
    type RelationshipTarget: RelationshipTarget<Relationship = Self>;

    // Required methods
    fn get(&self) -> Entity;
    fn from(entity: Entity) -> Self;
    fn set_risky(&mut self, entity: Entity);

    // Provided methods
    fn on_insert(world: DeferredWorld<'_>, _: HookContext) { ... }
    fn on_replace(world: DeferredWorld<'_>, _: HookContext) { ... }
}

A Component on a “source” Entity that references another target Entity, creating a “relationship” between them. Every Relationship has a corresponding RelationshipTarget type (and vice-versa), which exists on the “target” entity of a relationship and contains the list of all “source” entities that relate to the given “target”

The Relationship component is the “source of truth” and the RelationshipTarget component reflects that source of truth. When a Relationship component is inserted on an Entity, the corresponding RelationshipTarget component is immediately inserted on the target component if it does not already exist, and the “source” entity is automatically added to the RelationshipTarget collection (this is done via “component hooks”).

A common example of a Relationship is the parent / child relationship. Bevy ECS includes a canonical form of this via the ChildOf Relationship and the Children RelationshipTarget.

Relationship and RelationshipTarget should always be derived via the Component trait to ensure the hooks are set up properly.

Derive

Relationship and RelationshipTarget can only be derived for structs with a single unnamed field, single named field or for named structs where one field is annotated with #[relationship]. If there are additional fields, they must all implement Default.

RelationshipTarget also requires that the relationship field is private to prevent direct mutation, ensuring the correctness of relationships.

#[derive(Component)]
#[relationship(relationship_target = Children)]
pub struct ChildOf {
    #[relationship]
    pub parent: Entity,
    internal: u8,
};

#[derive(Component)]
#[relationship_target(relationship = ChildOf)]
pub struct Children(Vec<Entity>);

When deriving RelationshipTarget you can specify the #[relationship_target(linked_spawn)] attribute to automatically despawn entities stored in an entity’s RelationshipTarget when that entity is despawned:

#[derive(Component)]
#[relationship(relationship_target = Children)]
pub struct ChildOf(pub Entity);

#[derive(Component)]
#[relationship_target(relationship = ChildOf, linked_spawn)]
pub struct Children(Vec<Entity>);

Required Associated Types

type RelationshipTarget: RelationshipTarget<Relationship = Self>

The Component added to the “target” entities of this Relationship, which contains the list of all “source” entities that relate to the “target”.

Required Methods

fn get(&self) -> Entity

Gets the Entity ID of the related entity.

fn from(entity: Entity) -> Self

Creates this Relationship from the given entity.

fn set_risky(&mut self, entity: Entity)

Changes the current Entity ID of the entity containing the RelationshipTarget to another one.

This is useful for updating the relationship without overwriting other fields stored in Self.

Warning

This should generally not be called by user code, as modifying the related entity could invalidate the relationship. If this method is used, then the hooks on_replace have to run before and on_insert after it. This happens automatically when this method is called with EntityWorldMut::modify_component.

Prefer to use regular means of insertions when possible.

Provided Methods

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

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

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

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

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 Relationship for ChildOf

type RelationshipTarget = Children