mirror of
https://github.com/bevyengine/bevy
synced 2024-09-20 14:32:06 +00:00
Added docs for bevy_transform (#3516)
# Objective bevy_transform needed documentation and warn(missing_docs) as requested by #3492 ## Solution warn(missing_docs) was activated and documentation was added to cover the crate Co-authored-by: Troels Jessen <kairyuka@gmail.com>
This commit is contained in:
parent
17bb812d5d
commit
39db8ecd03
7 changed files with 48 additions and 0 deletions
|
@ -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))
|
||||
}
|
||||
|
|
|
@ -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,
|
||||
}
|
||||
|
||||
|
|
|
@ -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);
|
||||
|
|
|
@ -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<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;
|
||||
}
|
||||
|
||||
|
@ -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;
|
||||
}
|
||||
|
||||
|
|
|
@ -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) {
|
||||
|
@ -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);
|
||||
|
|
|
@ -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>>,
|
||||
|
|
|
@ -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,
|
||||
}
|
||||
|
||||
|
|
Loading…
Reference in a new issue