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:
Federico Rinaldi 2024-01-02 20:40:14 +01:00 committed by GitHub
parent 0f71dcbf1a
commit 2440aa8475
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -1,8 +1,50 @@
#![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
//! from the [`Parent`] to its [`Children`].
//! 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].
//!
//! [command]: BuildChildren
//! [diagnostic plugin]: ValidParentCheckPlugin
//! [events]: HierarchyEvent
//! [hierarchical despawn extension methods]: DespawnRecursiveExt
//! [plugin]: HierarchyPlugin
//! [query extension methods]: HierarchyQueryExt
//! [world]: BuildWorldChildren
mod components;
pub use components::*;
@ -35,7 +77,11 @@ pub mod prelude {
#[cfg(feature = "bevy_app")]
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)]
pub struct HierarchyPlugin;