Skip to content
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.

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 by Bors] - Added docs for bevy_transform #3516

Closed
wants to merge 7 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 2 additions & 0 deletions crates/bevy_transform/src/components/children.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ use bevy_reflect::Reflect;
use smallvec::SmallVec;
use std::ops::Deref;

/// Contains references to the child entities of this entity
Copy link
Member

Choose a reason for hiding this comment

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

To me, references makes me think of &T.

Possibly references is the right term; if it is, we should ensure we're consistent about it (but that's not this PR's problem)

#[derive(Component, Default, Clone, Debug, Reflect)]
#[reflect(Component, MapEntities)]
pub struct Children(pub(crate) SmallVec<[Entity; 8]>);
Expand All @@ -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))
}
Expand Down
3 changes: 3 additions & 0 deletions crates/bevy_transform/src/components/global_transform.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down
3 changes: 3 additions & 0 deletions crates/bevy_transform/src/components/parent.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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);
Expand Down
26 changes: 26 additions & 0 deletions crates/bevy_transform/src/hierarchy/child_builder.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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]>,
Expand Down Expand Up @@ -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<C: Command + 'static>(&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;
}

Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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()
Expand All @@ -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;
}

Expand Down
4 changes: 4 additions & 0 deletions crates/bevy_transform/src/hierarchy/hierarchy.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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::<Parent>(entity).map(|parent| parent.0) {
Expand Down Expand Up @@ -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);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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<Parent>>,
Expand Down
9 changes: 9 additions & 0 deletions crates/bevy_transform/src/lib.rs
Original file line number Diff line number Diff line change
@@ -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};
Expand All @@ -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,
}

Expand Down