Crate bevy_hierarchy

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.

Structs

• AncestorIter
  An Iterator of Entitys over the ancestors of an Entity.
• ChildBuilder
  Struct for building children entities and adding them to a parent entity.
• Children
  Contains references to the child entities of this entity.
• ClearChildren
  Command that clears all children from an entity and removes Parent component from those children.
• DescendantIter
  An Iterator of Entitys over the descendants of an Entity.
• DespawnChildrenRecursive
  Despawns the given entity’s children recursively
• DespawnRecursive
  Despawns the given entity and all its children recursively
• HierarchyPlugin
  Provides hierarchy functionality to a Bevy app.
• InsertChildren
  Command that inserts a child at a given index of a parent’s children, shifting following children back.
• Parent
  Holds a reference to the parent entity of this entity. This component should only be present on entities that actually have a parent entity.
• PushChild
  Command that adds a child to an entity.
• PushChildren
  Command that pushes children to the end of the entity’s Children.
• RemoveChildren
  Command that removes children from an entity, and removes these children’s parent.
• RemoveParent
  Command that removes the parent of an entity, and removes that entity from the parent’s Children.
• ReplaceChildren
  Command that clear all children from an entity, replacing them with the given children.
• ReportHierarchyIssue
  When enabled, runs check_hierarchy_component_has_valid_parent<T>.
• ValidParentCheckPlugin
  Print a warning for each Entity with a T component whose parent doesn’t have a T component.
• WorldChildBuilder
  Struct for adding children to an entity directly through the World for use in exclusive systems.

Enums

• HierarchyEvent
  An Event that is fired whenever there is a change in the world’s hierarchy.

Traits

• BuildChildren
  Trait for removing, adding and replacing children and parents of an entity.
• BuildWorldChildren
  Trait that defines adding, changing and children and parents of an entity directly through the World.
• DespawnRecursiveExt
  Trait that holds functions for despawning recursively down the transform hierarchy
• HierarchyQueryExt
  An extension trait for Query that adds hierarchy related methods.

Functions

• check_hierarchy_component_has_valid_parent
  System to print a warning for each Entity with a T component which parent hasn’t a T component.
• despawn_with_children_recursive
  Function for despawning an entity and all its children
• on_hierarchy_reports_enabled
  Run criteria that only allows running when ReportHierarchyIssue<T> is enabled.