Trait aery::relation::Relation

source · 
pub trait Relation: 'static + Sized + Send + Sync {
    const CLEANUP_POLICY: CleanupPolicy = CleanupPolicy::Orphan;
    const EXCLUSIVE: bool = true;
    const SYMMETRIC: bool = false;
}
Expand description

The relation trait. This is what controls the cleanup, exclusivity & symmetry of a relation. Relations can be thought of as arrows. The terms Aery uses for the base and head of this arrow are “host” and “target” respectively. With both the host and target being entities. Exclusive relations that face bottom up in hierarchies have many favorable properties so these are the default.

Note that relations:

  • Must be a ZST. This simply means that there can be no data on the edge. A compile error will be produced if you try to use a relation that isn’t one.
  • Cannot be self referential. Ie. an entity cannot target itself with a relationship it hosts. If this is ever attempted a warning will be logged & the relationship will not be set.

Aery only supports relations that are non-fragmenting. Ie. an entities archetype is not affected by the targets of its relations. See this article for more information. This isn’t necessarily good or bad. Archetype fragmentation is a more advanced topic but to keep it short and simple the archetype fragmentation is comparable to bevy_hierarchy if it supported multiple hierarchy types.

§Derive examples

use aery::prelude::*;

// Simple derive with defaults:
// - Orphaning
// - Exclusive
// - Asymmetric
#[derive(Relation)]
struct R;

// Override edge exclusivity
#[derive(Relation)]
#[aery(Poly)]
struct Poly;

// Override edge symmetry
#[derive(Relation)]
#[aery(Symmetric)]
struct Symmetric;

// Override cleanup policy
#[derive(Relation)]
#[aery(Recursive)] // Available: Counted, Recursive, Total
struct Recursive;

// Override multiple properties
#[derive(Relation)]
#[aery(Poly, Symmetric, Counted)]
struct Multi;

Provided Associated Constants§

source

const CLEANUP_POLICY: CleanupPolicy = CleanupPolicy::Orphan

How to clean up entities and relations when an entity with a relation is despawned or when a relation is unset.

source

const EXCLUSIVE: bool = true

Whether or not an entity is allowed to host more than 1 of this relation type. Entities can still be targeted multiple times by different entities with this relation. Entities cannot however host more than 1 of this relation at a time. Setting an exclusive relation that is already set will unset the existing relation.

source

const SYMMETRIC: bool = false

Whether or not a relation is symmetric. Ie:

  • When e0 -R-> e1
  • Then e0 <-R- e1

For example it would make sense for a MarriedTo relation to be symmetric.

Object Safety§

This trait is not object safe.

Implementors§