bevy_hierarchy/
lib.rs

1#![cfg_attr(docsrs, feature(doc_auto_cfg))]
2#![forbid(unsafe_code)]
3#![doc(
4    html_logo_url = "https://bevyengine.org/assets/icon.png",
5    html_favicon_url = "https://bevyengine.org/assets/icon.png"
6)]
7
8//! Parent-child relationships for Bevy entities.
9//!
10//! You should use the tools in this crate
11//! whenever you want to organize your entities in a hierarchical fashion,
12//! to make groups of entities more manageable,
13//! or to propagate properties throughout the entity hierarchy.
14//!
15//! This crate introduces various tools, including a [plugin]
16//! for managing parent-child relationships between entities.
17//! It provides two components, [`Parent`] and [`Children`],
18//! to store references to related entities.
19//! It also provides [command and world] API extensions
20//! to set and clear those relationships.
21//!
22//! More advanced users may also appreciate
23//! [query extension methods] to traverse hierarchies,
24//! and [events] to notify hierarchical changes.
25//! There is also a [diagnostic plugin] to validate property propagation.
26//!
27//! # Hierarchy management
28//!
29//! The methods defined in this crate fully manage
30//! the components responsible for defining the entity hierarchy.
31//! Mutating these components manually may result in hierarchy invalidation.
32//!
33//! Hierarchical relationships are always managed symmetrically.
34//! For example, assigning a child to an entity
35//! will always set the parent in the other,
36//! and vice versa.
37//! Similarly, unassigning a child in the parent
38//! will always unassign the parent in the child.
39//!
40//! ## Despawning entities
41//!
42//! The commands and methods provided by `bevy_ecs` to despawn entities
43//! are not capable of automatically despawning hierarchies of entities.
44//! In most cases, these operations will invalidate the hierarchy.
45//! Instead, you should use the provided [hierarchical despawn extension methods].
46//!
47//! [command and world]: BuildChildren
48//! [diagnostic plugin]: ValidParentCheckPlugin
49//! [events]: HierarchyEvent
50//! [hierarchical despawn extension methods]: DespawnRecursiveExt
51//! [plugin]: HierarchyPlugin
52//! [query extension methods]: HierarchyQueryExt
53
54extern crate alloc;
55
56mod components;
57pub use components::*;
58
59mod hierarchy;
60pub use hierarchy::*;
61
62mod child_builder;
63pub use child_builder::*;
64
65mod events;
66pub use events::*;
67
68mod valid_parent_check_plugin;
69pub use valid_parent_check_plugin::*;
70
71mod query_extension;
72pub use query_extension::*;
73
74/// The hierarchy prelude.
75///
76/// This includes the most common types in this crate, re-exported for your convenience.
77pub mod prelude {
78    #[doc(hidden)]
79    pub use crate::{child_builder::*, components::*, hierarchy::*, query_extension::*};
80
81    #[doc(hidden)]
82    #[cfg(feature = "bevy_app")]
83    pub use crate::{HierarchyPlugin, ValidParentCheckPlugin};
84}
85
86#[cfg(feature = "bevy_app")]
87use bevy_app::prelude::*;
88
89/// Provides hierarchy functionality to a Bevy app.
90///
91/// Check the [crate-level documentation] for all the features.
92///
93/// [crate-level documentation]: crate
94#[cfg(feature = "bevy_app")]
95#[derive(Default)]
96pub struct HierarchyPlugin;
97
98#[cfg(feature = "bevy_app")]
99impl Plugin for HierarchyPlugin {
100    fn build(&self, app: &mut App) {
101        app.register_type::<Children>()
102            .register_type::<Parent>()
103            .add_event::<HierarchyEvent>();
104    }
105}
bevy_hierarchy/lib.rs

bevy_hierarchy/
lib.rs
