Skip to content

Improve the docs for ChildOf and Children #17886

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Feb 17, 2025
Merged

Improve the docs for ChildOf and Children #17886

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bb5d2dd
Improve docs for ChildOf and Children
alice-i-cecile Feb 16, 2025
a29a12a
Add doc aliases
alice-i-cecile Feb 16, 2025
84ba0a4
Better usage notes
alice-i-cecile Feb 16, 2025
f3d9679
Clarify component ownership
alice-i-cecile Feb 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 21 additions & 5 deletions crates/bevy_ecs/src/hierarchy.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,9 @@ use core::slice;
use disqualified::ShortName;
use log::warn;

/// A [`Relationship`](crate::relationship::Relationship) component that creates the canonical
/// Stores the parent entity of this child entity with this component.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// Stores the parent entity of this child entity with this component.
/// This component stores the parent entity of this child entity.

///
/// This is a [`Relationship`](crate::relationship::Relationship) component, and creates the canonical
/// "parent / child" hierarchy. This is the "source of truth" component, and it pairs with
/// the [`Children`] [`RelationshipTarget`](crate::relationship::RelationshipTarget).
///
Expand All @@ -31,7 +33,6 @@ use log::warn;
/// 1. Organizing entities in a scene
/// 2. Propagating configuration or data inherited from a parent, such as "visibility" or "world-space global transforms".
/// 3. Ensuring a hierarchy is despawned when an entity is despawned.
/// 4.
///
/// [`ChildOf`] contains a single "target" [`Entity`]. When [`ChildOf`] is inserted on a "source" entity,
/// the "target" entity will automatically (and immediately, via a component hook) have a [`Children`]
Expand Down Expand Up @@ -92,10 +93,11 @@ use log::warn;
reflect(Component, PartialEq, Debug, FromWorld)
)]
#[relationship(relationship_target = Children)]
#[doc(alias = "IsChild", alias = "Parent")]
pub struct ChildOf(pub Entity);

impl ChildOf {
/// Returns the "target" entity.
/// Returns the parent entity, which is the "target" of this relationship.
pub fn get(&self) -> Entity {
self.0
}
Expand All @@ -121,15 +123,29 @@ impl FromWorld for ChildOf {
}
}

/// A [`RelationshipTarget`](crate::relationship::RelationshipTarget) collection component that is populated
/// Tracks which entities are children of this parent entity.
///
/// A [`RelationshipTarget`] collection component that is populated
/// with entities that "target" this entity with the [`ChildOf`] [`Relationship`](crate::relationship::Relationship) component.
///
/// Together, these components form the "canonical parent-child hierarchy". See the [`ChildOf`] component for all full
/// Together, these components form the "canonical parent-child hierarchy". See the [`ChildOf`] component for the full
/// description of this relationship and instructions on how to use it.
///
/// # Usage
///
/// Like all [`RelationshipTarget`] components, this data should not be directly manipulated to avoid desynchronization.
/// Instead, modify the [`ChildOf`] components on the "source" entities.
///
/// To access the children of an entity, you can iterate over the [`Children`] component,
/// using the [`IntoIterator`] trait.
/// For more complex access patterns, see the [`RelationshipTarget`] trait.
///
/// [`RelationshipTarget`]: crate::relationship::RelationshipTarget
#[derive(Component, Default, Debug, PartialEq, Eq)]
#[relationship_target(relationship = ChildOf, linked_spawn)]
#[cfg_attr(feature = "bevy_reflect", derive(bevy_reflect::Reflect))]
#[cfg_attr(feature = "bevy_reflect", reflect(Component, FromWorld))]
#[doc(alias = "IsParent")]
pub struct Children(Vec<Entity>);

impl<'a> IntoIterator for &'a Children {
Expand Down