Parent-child relationships for Bevy entities.

You should use the tools in this crate whenever you want to organize your entities in a hierarchical fashion, to make groups of entities more manageable, or to propagate properties throughout the entity hierarchy.

This crate introduces various tools, including a plugin for managing parent-child relationships between entities. It provides two components, Parent and Children, to store references to related entities. It also provides command and world API extensions to set and clear those relationships.

More advanced users may also appreciate query extension methods to traverse hierarchies, and events to notify hierarchical changes. There is also a diagnostic plugin to validate property propagation.

Hierarchy management

The methods defined in this crate fully manage the components responsible for defining the entity hierarchy. Mutating these components manually may result in hierarchy invalidation.

Hierarchical relationships are always managed symmetrically. For example, assigning a child to an entity will always set the parent in the other, and vice versa. Similarly, unassigning a child in the parent will always unassign the parent in the child.

Despawning entities

The commands and methods provided by bevy_ecs to despawn entities are not capable of automatically despawning hierarchies of entities. In most cases, these operations will invalidate the hierarchy. Instead, you should use the provided hierarchical despawn extension methods.