diff --git a/crates/bevy_transform/src/bundles.rs b/crates/bevy_transform/src/bundles.rs index dc8931824a7fd..8e755b9062ed8 100644 --- a/crates/bevy_transform/src/bundles.rs +++ b/crates/bevy_transform/src/bundles.rs @@ -12,8 +12,10 @@ use crate::prelude::{GlobalTransform, Transform}; /// /// ## [`Transform`] and [`GlobalTransform`] /// -/// [`Transform`] is the position of an entity relative to its parent position, or the reference -/// frame if it doesn't have a parent. +/// +/// [`Transform`] is the local transform (translation, rotation, scale) of an entity in space. +/// If the entity has a parent, the local transform is relative to its parent's +/// [`GlobalTransform`], otherwise, it's relative to the main reference frame. /// /// [`GlobalTransform`] is the position of an entity relative to the reference frame. /// diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index 0b377567966d9..fa3ee6a26d670 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -9,33 +9,46 @@ use bevy_reflect::{std_traits::ReflectDefault, Reflect}; #[cfg(all(feature = "bevy-support", feature = "serialize"))] use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; -/// [`GlobalTransform`] is an affine transformation from entity-local coordinates to worldspace coordinates. +/// [`GlobalTransform`] is an affine transformation from entity-local coordinates to worldspace +/// coordinates. /// -/// You cannot directly mutate [`GlobalTransform`]; instead, you change an entity's transform by manipulating -/// its [`Transform`], which indirectly causes Bevy to update its [`GlobalTransform`]. +/// ## Usage /// -/// * To get the global transform of an entity, you should get its [`GlobalTransform`]. -/// * For transform hierarchies to work correctly, you must have both a [`Transform`] and a [`GlobalTransform`]. -/// * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee this. +/// * To place or move an entity, you should set its [`Transform`]. +/// * To get the absolute transform of an entity, you should get its [`GlobalTransform`] +/// after [`TransformPropagate`] or [`PostUpdate`] to avoid being 1 frame out of date. +/// * You can use [`compute_transform`] to get the global `translation`, `rotation` and `scale`. +/// * [`GlobalTransform`] is fully managed by bevy and should not be mutated directly. + /// Instead, use [`Transform`]. Then, the [`GlobalTransform`] will be automatically updated by [`TransformPropagate`]. +/// * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee +/// an entity has both components. /// /// ## [`Transform`] and [`GlobalTransform`] /// -/// [`Transform`] transforms an entity relative to its parent's reference frame, or relative to world space coordinates, -/// if it doesn't have a [`Parent`](bevy_hierarchy::Parent). +/// [`Transform`] is the local transform of an entity in space relative to its parent transform, +/// or the global transform relative to the main reference frame if it doesn't have a [`Parent`]. /// -/// [`GlobalTransform`] is managed by Bevy; it is computed by successively applying the [`Transform`] of each ancestor -/// entity which has a Transform. This is done automatically by Bevy-internal systems in the system set -/// [`TransformPropagate`](crate::TransformSystem::TransformPropagate). +/// [`GlobalTransform`] is the absolute transform of an entity in space, relative to the main reference frame. /// -/// This system runs during [`PostUpdate`](bevy_app::PostUpdate). If you -/// update the [`Transform`] of an entity in this schedule or after, you will notice a 1 frame lag -/// before the [`GlobalTransform`] is updated. +/// [`GlobalTransform`] is updated from [`Transform`] by systems in the system set +/// [`TransformPropagate`]. +/// Those systems run during [`PostUpdate`]. +/// If you update the [`Transform`] of an entity in this schedule or after, +/// you may notice a 1 frame lag before the [`GlobalTransform`] is updated. /// /// # Examples /// -/// - [`transform`][transform_example] +/// - The [`transform example`], or the other examples in the [`transforms folder`], +/// to learn how to use the [`Transform`] of an entity. +/// - The [`parenting example`], to learn how [`Transform`] behaves in a hierarchy. /// -/// [transform_example]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs +/// [`compute_transform`]: GlobalTransform::compute_transform +/// [`TransformBundle`]: crate::TransformBundle +/// [`TransformPropagate`]: crate::TransformSystem::TransformPropagate +/// [`PostUpdate`]: bevy_app::PostUpdate +/// [`Parent`]: bevy_hierarchy::Parent +/// [`transform example`]: https://bevyengine.org/examples/transforms/transform +/// [`parenting example`]: https://bevyengine.org/examples/3d-rendering/parenting #[derive(Debug, PartialEq, Clone, Copy)] #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))] #[cfg_attr( diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index 9202b0618c940..005c981a9e5e6 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -6,33 +6,72 @@ use bevy_math::{Affine3A, Dir3, Isometry3d, Mat3, Mat4, Quat, Vec3}; use bevy_reflect::prelude::*; use std::ops::Mul; -/// Describe the position of an entity. If the entity has a parent, the position is relative -/// to its parent position. +/// Describes the local transform (translation, rotation, scale) of an entity in space. +/// If the entity has a parent, the local transform is relative to its parent's +/// [`GlobalTransform`], otherwise, it's relative to the main reference frame. +/// +/// ## Usage /// /// * To place or move an entity, you should set its [`Transform`]. -/// * To get the global transform of an entity, you should get its [`GlobalTransform`]. +/// * To get the absolute transform of an entity, you should get its [`GlobalTransform`] +/// after [`TransformPropagate`] or [`PostUpdate`] to avoid being a frame out of date. /// * To be displayed, an entity must have both a [`Transform`] and a [`GlobalTransform`]. -/// * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee this. +/// * You may use the [`TransformBundle`] to guarantee this. +/// +/// ## `translation`, `rotation` and `scale` +/// +/// If the entity has no parent, [`Transform`] is relative to the main reference frame: +/// - The position of an entity in space, defined as a `translation` from the origin, +/// [`Vec3::ZERO`]. The length unit doesn't have a predefined meaning, but the convention +/// is usually to consider `1.0` equivalent to 1 meter. +/// - The `rotation` of an entity in space, [`Quat::IDENTITY`] representing the rotation +/// where [`Vec3::Z`] is forward and [`Vec3::Y`] is up. +/// - The `scale` of an entity, `1.0` representing the "size values" of the entity +/// matching the main reference frame coordinates. +/// It can be seen as a ratio of the main reference frame length unit to +/// the entity's length unit. +/// For example, if the scale is `1.0` for a `Mesh`, its vertex position attributes +/// have the same unit than the values used inside `translation`. +/// +/// If the entity has a parent: +/// - The `translation` is relative to the parent's [`GlobalTransform`], it is +/// added to it. +/// Another way of seeing it is that the `translation`'s origin is the +/// parent global position. +/// - The `rotation` is relative to the parent's [`GlobalTransform`], it is multiplied +/// by it. +/// Another way of seeing it is that [`Quat::IDENTITY`] represents the rotation +/// where the parent's global forward axis is forward and the parent's global up axis is up. +/// - The `scale` is relative to the parent's [`GlobalTransform`], it is multiplied +/// by it. +/// Another way of seeing it is to consider the parent has its own length unit +/// used by the child. /// /// ## [`Transform`] and [`GlobalTransform`] /// -/// [`Transform`] is the position of an entity relative to its parent position, or the reference -/// frame if it doesn't have a [`Parent`](bevy_hierarchy::Parent). +/// [`Transform`] is the local transform of an entity in space relative to its parent transform, +/// or the global transform relative to the main reference frame if it doesn't have a [`Parent`]. /// -/// [`GlobalTransform`] is the position of an entity relative to the reference frame. +/// [`GlobalTransform`] is the absolute transform of an entity in space relative to the main reference frame. /// /// [`GlobalTransform`] is updated from [`Transform`] by systems in the system set -/// [`TransformPropagate`](crate::TransformSystem::TransformPropagate). -/// -/// This system runs during [`PostUpdate`](bevy_app::PostUpdate). If you -/// update the [`Transform`] of an entity during this set or after, you will notice a 1 frame lag -/// before the [`GlobalTransform`] is updated. +/// [`TransformPropagate`]. +/// Those systems run during [`PostUpdate`]. +/// If you update the [`Transform`] of an entity in this schedule or after, +/// you may notice a 1 frame lag before the [`GlobalTransform`] is updated. /// /// # Examples /// -/// - [`transform`][transform_example] +/// - The [`transform example`], or the other examples in the [`transforms folder`], +/// to learn how to use the [`Transform`] of an entity. +/// - The [`parenting example`], to learn how [`Transform`] behaves in a hierarchy. /// -/// [transform_example]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs +/// [`TransformBundle`]: crate::bundles::TransformBundle +/// [`TransformPropagate`]: crate::TransformSystem::TransformPropagate +/// [`PostUpdate`]: bevy_app::PostUpdate +/// [`Parent`]: bevy_hierarchy::Parent +/// [`transform example`]: https://bevyengine.org/examples/transforms/transform +/// [`parenting example`]: https://bevyengine.org/examples/3d-rendering/parenting #[derive(Debug, PartialEq, Clone, Copy)] #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))] #[cfg_attr( @@ -61,7 +100,7 @@ pub struct Transform { /// /// See the [`scale`] example for usage. /// - /// [`scale`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/scale.rs + /// [`scale`]: https://bevyengine.org/examples/transforms/scale pub scale: Vec3, } @@ -298,9 +337,9 @@ impl Transform { /// /// # Examples /// - /// - [`3d_rotation`] + /// - [`3d-rotation`] /// - /// [`3d_rotation`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/3d_rotation.rs + /// [`3d-rotation`]: https://bevyengine.org/examples/transforms/3d-rotation #[inline] pub fn rotate(&mut self, rotation: Quat) { self.rotation = rotation * self.rotation;