Trait Relationship

Source

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

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

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

Expand description

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>);