mirror of
https://github.com/bevyengine/bevy
synced 2024-11-21 20:23:28 +00:00
Add bevy_hierarchy
Crate and plugin documentation (#10951)
This PR is part of a project aimed at improving the API documentation of `bevy_hierarchy`. Other PRs will be based on this. This PR in particular is also an experiment in providing a high level overview of the tools provided by a Bevy plugin/crate. It also provides general information about universal invariants, so statement repetition in crate items can be dramatically reduced. ## Other changes The other PRs of this project that expand on this one: - #10952 - #10953 - #10954 - #10955 - #10956 - #10957 --------- Co-authored-by: GitGhillie <jillisnoordhoek@gmail.com>
This commit is contained in:
parent
0f71dcbf1a
commit
2440aa8475
1 changed files with 50 additions and 4 deletions
|
@ -1,8 +1,50 @@
|
||||||
#![warn(missing_docs)]
|
#![warn(missing_docs)]
|
||||||
//! `bevy_hierarchy` can be used to define hierarchies of entities.
|
//! Parent-child relationships for Bevy entities.
|
||||||
//!
|
//!
|
||||||
//! Most commonly, these hierarchies are used for inheriting `Transform` values
|
//! You should use the tools in this crate
|
||||||
//! from the [`Parent`] to its [`Children`].
|
//! 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].
|
||||||
|
//!
|
||||||
|
//! [command]: BuildChildren
|
||||||
|
//! [diagnostic plugin]: ValidParentCheckPlugin
|
||||||
|
//! [events]: HierarchyEvent
|
||||||
|
//! [hierarchical despawn extension methods]: DespawnRecursiveExt
|
||||||
|
//! [plugin]: HierarchyPlugin
|
||||||
|
//! [query extension methods]: HierarchyQueryExt
|
||||||
|
//! [world]: BuildWorldChildren
|
||||||
|
|
||||||
mod components;
|
mod components;
|
||||||
pub use components::*;
|
pub use components::*;
|
||||||
|
@ -35,7 +77,11 @@ pub mod prelude {
|
||||||
#[cfg(feature = "bevy_app")]
|
#[cfg(feature = "bevy_app")]
|
||||||
use bevy_app::prelude::*;
|
use bevy_app::prelude::*;
|
||||||
|
|
||||||
/// The base plugin for handling [`Parent`] and [`Children`] components
|
/// Provides hierarchy functionality to a Bevy app.
|
||||||
|
///
|
||||||
|
/// Check the [crate-level documentation] for all the features.
|
||||||
|
///
|
||||||
|
/// [crate-level documentation]: crate
|
||||||
#[derive(Default)]
|
#[derive(Default)]
|
||||||
pub struct HierarchyPlugin;
|
pub struct HierarchyPlugin;
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue