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.

Modules

prelude

The hierarchy prelude.

Structs

AddChild

Command that adds a child to an entity.

AddChildren

Command that pushes children to the end of the entity’s Children.

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.

DescendantDepthFirstIter

An Iterator of Entitys over the descendants of an Entity.

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

HierarchyPluginbevy_app

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.

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.

ChildBuild

Trait for building children entities and adding them to a parent entity. This is used in implementations of BuildChildren as a bound on the Builder associated type. The closure passed to BuildChildren::with_children accepts an implementation of ChildBuild so that children can be spawned via ChildBuild::spawn.

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_parentbevy_app

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.