diff --git a/crates/bevy_transform/src/components/children.rs b/crates/bevy_transform/src/components/children.rs index af523d77ea90d..96097a1da8a59 100644 --- a/crates/bevy_transform/src/components/children.rs +++ b/crates/bevy_transform/src/components/children.rs @@ -7,6 +7,7 @@ use bevy_reflect::Reflect; use smallvec::SmallVec; use std::ops::Deref; +/// Contains references to the child entities of this entity #[derive(Component, Default, Clone, Debug, Reflect)] #[reflect(Component, MapEntities)] pub struct Children(pub(crate) SmallVec<[Entity; 8]>); @@ -22,6 +23,7 @@ impl MapEntities for Children { } impl Children { + /// Builds and returns a [`Children`] component with the given entities pub fn with(entity: &[Entity]) -> Self { Self(SmallVec::from_slice(entity)) } diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index 141308def70a2..7540fd90dff6e 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -36,8 +36,11 @@ use std::ops::Mul; #[derive(Component, Debug, PartialEq, Clone, Copy, Reflect)] #[reflect(Component, PartialEq)] pub struct GlobalTransform { + /// The position of the global transform pub translation: Vec3, + /// The rotation of the global transform pub rotation: Quat, + /// The scale of the global transform pub scale: Vec3, } diff --git a/crates/bevy_transform/src/components/parent.rs b/crates/bevy_transform/src/components/parent.rs index 5f03dc06535c6..ddc0e2a634ee6 100644 --- a/crates/bevy_transform/src/components/parent.rs +++ b/crates/bevy_transform/src/components/parent.rs @@ -7,6 +7,8 @@ use bevy_ecs::{ use bevy_reflect::Reflect; use std::ops::{Deref, DerefMut}; +/// Holds a reference to the parent entity of this entity. +/// This component should only be present on entities that actually have a parent entity. #[derive(Component, Debug, Copy, Clone, Eq, PartialEq, Reflect)] #[reflect(Component, MapEntities, PartialEq)] pub struct Parent(pub Entity); @@ -42,6 +44,7 @@ impl DerefMut for Parent { } } +/// Component that holds the [`Parent`] this entity had previously #[derive(Component, Debug, Copy, Clone, Eq, PartialEq, Reflect)] #[reflect(Component, MapEntities, PartialEq)] pub struct PreviousParent(pub(crate) Entity); diff --git a/crates/bevy_transform/src/hierarchy/child_builder.rs b/crates/bevy_transform/src/hierarchy/child_builder.rs index 56f6a073d8b5b..3dd47da3878a6 100644 --- a/crates/bevy_transform/src/hierarchy/child_builder.rs +++ b/crates/bevy_transform/src/hierarchy/child_builder.rs @@ -7,9 +7,12 @@ use bevy_ecs::{ }; use smallvec::SmallVec; +/// Command that adds a child to an entity #[derive(Debug)] pub struct AddChild { + /// Parent entity to add the child to pub parent: Entity, + /// Child entity to add pub child: Entity, } @@ -29,6 +32,7 @@ impl Command for AddChild { } } +/// Command that inserts a child at a given index of a parent's children, shifting following children back #[derive(Debug)] pub struct InsertChildren { parent: Entity, @@ -56,6 +60,7 @@ impl Command for InsertChildren { } } +/// Command that pushes children to the end of the entity's children #[derive(Debug)] pub struct PushChildren { parent: Entity, @@ -88,6 +93,7 @@ impl Command for PushChildren { } } +/// Command that removes children from an entity, and removes that child's parent and inserts it into the previous parent component pub struct RemoveChildren { parent: Entity, children: SmallVec<[Entity; 8]>, @@ -123,39 +129,50 @@ impl Command for RemoveChildren { } } +/// Struct for building children onto an entity pub struct ChildBuilder<'w, 's, 'a> { commands: &'a mut Commands<'w, 's>, push_children: PushChildren, } impl<'w, 's, 'a> ChildBuilder<'w, 's, 'a> { + /// Spawns an entity with the given bundle and inserts it into the children defined by the [`ChildBuilder`] pub fn spawn_bundle(&mut self, bundle: impl Bundle) -> EntityCommands<'w, 's, '_> { let e = self.commands.spawn_bundle(bundle); self.push_children.children.push(e.id()); e } + /// Spawns an [`Entity`] with no components and inserts it into the children defined by the [`ChildBuilder`] which adds the [`Parent`] component to it. pub fn spawn(&mut self) -> EntityCommands<'w, 's, '_> { let e = self.commands.spawn(); self.push_children.children.push(e.id()); e } + /// Returns the parent entity of this [`ChildBuilder`] pub fn parent_entity(&self) -> Entity { self.push_children.parent } + /// Adds a command to this [`ChildBuilder`] pub fn add_command(&mut self, command: C) -> &mut Self { self.commands.add(command); self } } +/// Trait defining how to build children pub trait BuildChildren { + /// Creates a [`ChildBuilder`] with the given children built in the given closure fn with_children(&mut self, f: impl FnOnce(&mut ChildBuilder)) -> &mut Self; + /// Pushes children to the back of the builder's children fn push_children(&mut self, children: &[Entity]) -> &mut Self; + /// Inserts children at the given index fn insert_children(&mut self, index: usize, children: &[Entity]) -> &mut Self; + /// Removes the given children fn remove_children(&mut self, children: &[Entity]) -> &mut Self; + /// Adds a single child fn add_child(&mut self, child: Entity) -> &mut Self; } @@ -213,6 +230,7 @@ impl<'w, 's, 'a> BuildChildren for EntityCommands<'w, 's, 'a> { } } +/// Struct for adding children to an entity directly through the [`World`] for use in exclusive systems #[derive(Debug)] pub struct WorldChildBuilder<'w> { world: &'w mut World, @@ -221,6 +239,7 @@ pub struct WorldChildBuilder<'w> { } impl<'w> WorldChildBuilder<'w> { + /// Spawns an entity with the given bundle and inserts it into the children defined by the [`WorldChildBuilder`] pub fn spawn_bundle(&mut self, bundle: impl Bundle + Send + Sync + 'static) -> EntityMut<'_> { let parent_entity = self.parent_entity(); let entity = self @@ -240,6 +259,7 @@ impl<'w> WorldChildBuilder<'w> { self.world.entity_mut(entity) } + /// Spawns an [`Entity`] with no components and inserts it into the children defined by the [`WorldChildBuilder`] which adds the [`Parent`] component to it. pub fn spawn(&mut self) -> EntityMut<'_> { let parent_entity = self.parent_entity(); let entity = self @@ -258,6 +278,7 @@ impl<'w> WorldChildBuilder<'w> { self.world.entity_mut(entity) } + /// Returns the parent entity of this [`WorldChildBuilder`] pub fn parent_entity(&self) -> Entity { self.parent_entities .last() @@ -266,10 +287,15 @@ impl<'w> WorldChildBuilder<'w> { } } +/// Trait that defines adding children to an entity directly through the [`World`] pub trait BuildWorldChildren { + /// Creates a [`WorldChildBuilder`] with the given children built in the given closure fn with_children(&mut self, spawn_children: impl FnOnce(&mut WorldChildBuilder)) -> &mut Self; + /// Pushes children to the back of the builder's children fn push_children(&mut self, children: &[Entity]) -> &mut Self; + /// Inserts children at the given index fn insert_children(&mut self, index: usize, children: &[Entity]) -> &mut Self; + /// Removes the given children fn remove_children(&mut self, children: &[Entity]) -> &mut Self; } diff --git a/crates/bevy_transform/src/hierarchy/hierarchy.rs b/crates/bevy_transform/src/hierarchy/hierarchy.rs index f674ade461082..0820742c34b75 100644 --- a/crates/bevy_transform/src/hierarchy/hierarchy.rs +++ b/crates/bevy_transform/src/hierarchy/hierarchy.rs @@ -6,16 +6,19 @@ use bevy_ecs::{ }; use bevy_utils::tracing::debug; +/// Despawns the given entity and all its children recursively #[derive(Debug)] pub struct DespawnRecursive { entity: Entity, } +/// Despawns the given entity's children recursively #[derive(Debug)] pub struct DespawnChildrenRecursive { entity: Entity, } +/// Function for despawning an entity and all its children pub fn despawn_with_children_recursive(world: &mut World, entity: Entity) { // first, make the entity's own parent forget about it if let Some(parent) = world.get::(entity).map(|parent| parent.0) { @@ -61,6 +64,7 @@ impl Command for DespawnChildrenRecursive { } } +/// Trait that holds functions for despawning recursively down the transform hierarchy pub trait DespawnRecursiveExt { /// Despawns the provided entity alongside all descendants. fn despawn_recursive(self); diff --git a/crates/bevy_transform/src/hierarchy/hierarchy_maintenance_system.rs b/crates/bevy_transform/src/hierarchy/hierarchy_maintenance_system.rs index 75b5dfc1a2f52..dbbeacab12e8f 100644 --- a/crates/bevy_transform/src/hierarchy/hierarchy_maintenance_system.rs +++ b/crates/bevy_transform/src/hierarchy/hierarchy_maintenance_system.rs @@ -8,6 +8,7 @@ use bevy_ecs::{ use bevy_utils::HashMap; use smallvec::SmallVec; +/// Updates parents when the hierarchy is changed pub fn parent_update_system( mut commands: Commands, removed_parent_query: Query<(Entity, &PreviousParent), Without>, diff --git a/crates/bevy_transform/src/lib.rs b/crates/bevy_transform/src/lib.rs index fa917bf40d889..d9ddf29507078 100644 --- a/crates/bevy_transform/src/lib.rs +++ b/crates/bevy_transform/src/lib.rs @@ -1,9 +1,14 @@ +#![warn(missing_docs)] #![doc = include_str!("../README.md")] +/// The basic components of the transform crate pub mod components; +/// Establishing and updating the transform hierarchy pub mod hierarchy; +/// Propagating transform changes down the transform hierarchy pub mod transform_propagate_system; +#[doc(hidden)] pub mod prelude { #[doc(hidden)] pub use crate::{components::*, hierarchy::*, TransformPlugin}; @@ -13,12 +18,16 @@ use bevy_app::prelude::*; use bevy_ecs::schedule::{ParallelSystemDescriptorCoercion, SystemLabel}; use prelude::{parent_update_system, Children, GlobalTransform, Parent, PreviousParent, Transform}; +/// The base plugin for handling [`Transform`] components #[derive(Default)] pub struct TransformPlugin; +/// Label enum for the types of systems relating to transform #[derive(Debug, Hash, PartialEq, Eq, Clone, SystemLabel)] pub enum TransformSystem { + /// Propagates changes in transform to childrens' [`GlobalTransform`] TransformPropagate, + /// Updates [`Parent`] when changes in the hierarchy occur ParentUpdate, }