Crate bevy_hierarchy
source ·Expand description
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§
- Struct for building children entities and adding them to a parent entity.
- Contains references to the child entities of this entity.
- Command that clears all children from an entity and removes
Parent
component from those children. - Despawns the given entity’s children recursively
- Despawns the given entity and all its children recursively
- Provides hierarchy functionality to a Bevy app.
- Command that inserts a child at a given index of a parent’s children, shifting following children back.
- Holds a reference to the parent entity of this entity. This component should only be present on entities that actually have a parent entity.
- Command that adds a child to an entity.
- Command that pushes children to the end of the entity’s
Children
. - Command that removes children from an entity, and removes these children’s parent.
- Command that removes the parent of an entity, and removes that entity from the parent’s
Children
. - Command that clear all children from an entity, replacing them with the given children.
- When enabled, runs
check_hierarchy_component_has_valid_parent<T>
. - Print a warning for each
Entity
with aT
component whose parent doesn’t have aT
component. - Struct for adding children to an entity directly through the
World
for use in exclusive systems.
Enums§
- An
Event
that is fired whenever there is a change in the world’s hierarchy.
Traits§
- Trait for removing, adding and replacing children and parents of an entity.
- Trait that defines adding, changing and children and parents of an entity directly through the
World
. - Trait that holds functions for despawning recursively down the transform hierarchy
- An extension trait for
Query
that adds hierarchy related methods.
Functions§
- Function for despawning an entity and all its children
- Run criteria that only allows running when
ReportHierarchyIssue<T>
is enabled.