Relationships (non-fragmenting, one-to-many)

[cart]

This adds support for one-to-many non-fragmenting relationships (with planned paths for fragmenting and non-fragmenting many-to-many relationships). "Non-fragmenting" means that entities with the same relationship type, but different relationship targets, are not forced into separate tables (which would cause "table fragmentation").

Functionally, this fills a similar niche as the current Parent/Children system. The biggest differences are:

1. Relationships have simpler internals and significantly improved performance and UX. Commands and specialized APIs are no longer necessary to keep everything in sync. Just spawn entities with the relationship components you want and everything "just works".
2. Relationships are generalized. Bevy can provide additional built in relationships, and users can define their own.

REQUEST TO REVIEWERS: please don't leave top level comments and instead comment on specific lines of code. That way we can take advantage of threaded discussions. Also dont leave comments simply pointing out CI failures as I can read those just fine.

Built on top of what we have

Relationships are implemented on top of the Bevy ECS features we already have: components, immutability, and hooks. This makes them immediately compatible with all of our existing (and future) APIs for querying, spawning, removing, scenes, reflection, etc. The fewer specialized APIs we need to build, maintain, and teach, the better.

Why focus on one-to-many non-fragmenting first?

1. This allows us to improve Parent/Children relationships immediately, in a way that is reasonably uncontroversial. Switching our hierarchy to fragmenting relationships would have significant performance implications. Flecs is heavily considering a switch to non-fragmenting relations after careful considerations of the performance tradeoffs. (Correction from @SanderMertens: Flecs is implementing non-fragmenting storage specialized for asset hierarchies, where asset hierarchies are many instances of small trees that have a well defined structure)
2. Adding generalized one-to-many relationships is currently a priority for the Next Generation Scene / UI effort. Specifically, we're interested in building reactions and observers on top.

The changes

This PR does the following:

1. Adds a generic one-to-many Relationship system
2. Ports the existing Parent/Children system to Relationships, which now lives in bevy_ecs::hierarchy. The old bevy_hierarchy crate has been removed.
3. Adds on_despawn component hooks
4. Relationships can opt-in to "despawn descendants" behavior, meaning that the entire relationship hierarchy is despawned when entity.despawn() is called. The built in Parent/Children hierarchies enable this behavior, and entity.despawn_recursive() has been removed.
5. world.spawn now applies commands after spawning. This ensures that relationship bookkeeping happens immediately and removes the need to manually flush. This is in line with the equivalent behaviors recently added to the other APIs (ex: insert).
6. Removes the ValidParentCheckPlugin (system-driven / poll based) in favor of a validate_parent_has_component hook.

Using Relationships

The Relationship trait looks like this:

pub trait Relationship: Component + Sized {
    type RelationshipSources: RelationshipSources<Relationship = Self>;
    fn get(&self) -> Entity;
    fn from(entity: Entity) -> Self;
}

A relationship is a component that:

1. Is a simple wrapper over a "target" Entity.
2. Has a corresponding RelationshipSources component, which is a simple wrapper over a collection of entities. Every "target entity" targeted by a "source entity" with a Relationship has a RelationshipSources component, which contains every "source entity" that targets it.

For example, the Parent component (as it currently exists in Bevy) is the Relationship component and the entity containing the Parent is the "source entity". The entity inside the Parent(Entity) component is the "target entity". And that target entity has a Children component (which implements RelationshipSources).

In practice, the Parent/Children relationship looks like this:

#[derive(Relationship)]
#[relationship(relationship_sources = Children)]
pub struct Parent(pub Entity);

#[derive(RelationshipSources)]
#[relationship_sources(relationship = Parent)]
pub struct Children(Vec<Entity>);

The Relationship and RelationshipSources derives automatically implement Component with the relevant configuration (namely, the hooks necessary to keep everything in sync).

The most direct way to add relationships is to spawn entities with relationship components:

let a = world.spawn_empty().id();
let b = world.spawn(Parent(a)).id();

assert_eq!(world.entity(a).get::<Children>().unwrap(), &[b]);

There are also convenience APIs for spawning more than one entity with the same relationship:

world.spawn_empty().with_related::<Children>(|s| {
    s.spawn_empty();
    s.spawn_empty();
})

The existing with_children API is now a simpler wrapper over with_related. This makes this change largely non-breaking for existing spawn patterns.

world.spawn_empty().with_children(|s| {
    s.spawn_empty();
    s.spawn_empty();
})

There are also other relationship APIs, such as add_related and despawn_related.

Automatic recursive despawn via the new on_despawn hook

RelationshipSources can opt-in to "despawn descendants" behavior, which will despawn all related entities in the relationship hierarchy:

#[derive(RelationshipSources)]
#[relationship_sources(relationship = Parent, despawn_descendants)]
pub struct Children(Vec<Entity>);

This means that entity.despawn_recursive() is no longer required. Instead, just use entity.despawn() and the relevant related entities will also be despawned.

To despawn an entity without despawning its parent/child descendants, you should remove the Children component first, which will also remove the related Parent components:

entity
    .remove::<Children>()
    .despawn()

This builds on the on_despawn hook introduced in this PR, which is fired when an entity is despawned (before other hooks).

Relationships are the source of truth

Relationship is the single source of truth component. RelationshipSources is merely a reflection of what all the Relationship components say. By embracing this, we are able to significantly improve the performance of the system as a whole. We can rely on component lifecycles to protect us against duplicates, rather than needing to scan at runtime to ensure entities don't already exist (which results in quadratic runtime). A single source of truth gives us constant-time inserts. This does mean that we cannot directly spawn populated Children components (or directly add or remove entities from those components). I personally think this is a worthwhile tradeoff, both because it makes the performance much better and because it means theres exactly one way to do things (which is a philosophy we try to employ for Bevy APIs).

As an aside: treating both sides of the relationship as "equivalent source of truth relations" does enable building simple and flexible many-to-many relationships. But this introduces an inherent need to scan (or hash) to protect against duplicates. evergreen_relations has a very nice implementation of the "symmetrical many-to-many" approach. Unfortunately I think the performance issues inherent to that approach make it a poor choice for Bevy's default relationship system.

Followup Work

• Discuss renaming Parent to ChildOf. I refrained from doing that in this PR to keep the diff reasonable, but I'm personally biased toward this change (and using that naming pattern generally for relationships).
• Improved spawning ergonomics
• Consider adding relationship observers/triggers for "relationship targets" whenever a source is added or removed. This would replace the current "hierarchy events" system, which is unused upstream but may have existing users downstream. I think triggers are the better fit for this than a buffered event queue, and would prefer not to add that back.
• Fragmenting relations: My current idea hinges on the introduction of "value components" (aka: components whose type and value determines their ComponentId, via something like Hashing / PartialEq). By labeling a Relationship component such as ChildOf(Entity) as a "value component", ChildOf(e1) and ChildOf(e2) would be considered "different components". This makes the transition between fragmenting and non-fragmenting a single flag, and everything else continues to work as expected.
• Many-to-many support
  • Non-fragmenting: We can expand Relationship to be a list of entities instead of a single entity. I have largely already written the code for this.
  • Fragmenting: With the "value component" impl mentioned above, we get many-to-many support "for free", as it would allow inserting multiple copies of a Relationship component with different target entities.

Fixes #3742 (If this PR is merged, I think we should open more targeted followup issues for the work above, with a fresh tracking issue free of the large amount of less-directed historical context)
Fixes #17301
Fixes #12235
Fixes #15299
Fixes #15308

Migration Guide

• Replace ChildBuilder with ChildSpawnerCommands.
• Replace calls to .set_parent(parent_id) with .insert(Parent(parent_id)).
• Replace calls to .replace_children() with .remove::<Children>() followed by .add_children(). Note that you'll need to manually despawn any children that are not carried over.
• Replace calls to .despawn_recursive() with .despawn().
• Replace calls to .despawn_descendants() with .despawn_related::<Children>().
• If you have any calls to .despawn() which depend on the children being preserved, you'll need to remove the Children component first.

[Carter0]

omg its happening

[bushrat011899]

Excellent to see this landing! Mostly comments, but I do have one question around the need for Component<Mutability = Mutable> on RelationshipSource.

[bushrat011899]

An ON_DESPAWN hook is also a great outcome form this PR in of itself. I assume there's negligible performance impacts from the addition of this hook?

[cart]

We can benchmark, but I don't expect significant degradation.

[bushrat011899]

I wouldn't expect any problems either, agreed.

[cBournhonesque]

Didn't read everything, added a couple comments.
Is there a test for the commands.remove::<Parent>().despawn() doesn't despawn descendants? I think that would be good to have

[viridia]

I've updated my repo to pick up the latest changes (using Component derive) and everything still works.

[alice-i-cecile]

@cart I have no concerns about this at this stage and we have plenty of community review; feel free to merge when you feel it's ready.