Clarify Transform and GlobalTransform documentation

crates/bevy_transform/src/components/global_transform.rs

@@ -5,34 +5,62 @@ use bevy_ecs::{component::Component, reflect::ReflectComponent};
 use bevy_math::{Affine3A, Mat4, Quat, Vec3, Vec3A};
 use bevy_reflect::{std_traits::ReflectDefault, Reflect};
 
-/// Describe the position of an entity relative to the reference frame.
+/// Describe the absolute transform (translation, rotation, scale) of an entity in space,
+/// relative to the main reference frame.
+///
+/// ## Usage
 ///
 /// * 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 a 1 frame lag.
+///   * You can use [`compute_transform`] to get the global `translation`, `rotation` and `scale`.
 /// * [`GlobalTransform`] is fully managed by bevy, you cannot mutate it, use
-///   [`Transform`] instead.
-/// * 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::TransformBundle) to guarantee this.
+///   [`Transform`] instead, the [`GlobalTransform`] will be automatically updated with [`TransformPropagate`].
+///   * You may use the [`TransformBundle`](crate::TransformBundle) to guarantee
+/// an entity has both components.
+///
+/// ## `translation`, `rotation` and `scale`
+///
+/// [`GlobalTransform`] represents:
+/// - The position of an entity in space, defined as a `translation` from the origin,
+/// [`Vec3::ZERO`]. The unit doesn't have a predefined meaning, but the convention
+/// is usually to use `1.0` is 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 vertices position attribute
+/// have the same unit than the values used inside `translation`.
 ///
 /// ## [`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 in this schedule 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`]
+/// - 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`]: 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://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs
+/// [`transforms folder`]: https://github.com/bevyengine/bevy/tree/latest/examples/transforms
+/// [`parenting example`]: https://bevyengine.org/examples/3d/parenting/
 #[derive(Component, Debug, PartialEq, Clone, Copy, Reflect)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 #[reflect(Component, Default, PartialEq)]

crates/bevy_transform/src/components/transform.rs

@@ -5,36 +5,73 @@ use bevy_reflect::prelude::*;
 use bevy_reflect::Reflect;
 use std::ops::Mul;
 
-/// Describe the position of an entity. If the entity has a parent, the position is relative
-/// to its parent position.
+/// Describe 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 a 1 frame lag.
 /// * To be displayed, an entity must have both a [`Transform`] and a [`GlobalTransform`].
-///   * You may use the [`TransformBundle`](crate::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 vertices position attribute
+/// 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`]
-/// - [`global_vs_local_translation`]
+/// - 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.
 ///
-/// [`global_vs_local_translation`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/global_vs_local_translation.rs
-/// [`transform`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs
-/// [`Transform`]: super::Transform
+/// [`TransformBundle`]: crate::TransformBundle
+/// [`TransformPropagate`]: crate::TransformSystem::TransformPropagate
+/// [`PostUpdate`]: bevy_app::PostUpdate
+/// [`Parent`]: bevy_hierarchy::Parent
+/// [`transform example`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs
+/// [`transforms folder`]: https://github.com/bevyengine/bevy/tree/latest/examples/transforms
+/// [`parenting example`]: https://bevyengine.org/examples/3d/parenting/
 #[derive(Component, Debug, PartialEq, Clone, Copy, Reflect)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 #[reflect(Component, Default, PartialEq)]