From 15b6aab7500eb63d72505d62d992e7fae8448179 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= Date: Mon, 17 Jul 2023 02:09:09 +0100 Subject: [PATCH 01/14] Clarify Transform and GlobalTransform documentation --- .../bevy_transform/src/components/global_transform.rs | 9 +++++---- crates/bevy_transform/src/components/transform.rs | 10 +++++----- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index 4e1480c44b0b5..139d04595913e 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -5,7 +5,8 @@ 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 position of an entity in space, +/// relative to the main reference frame. /// /// * To place or move an entity, you should set its [`Transform`]. /// * [`GlobalTransform`] is fully managed by bevy, you cannot mutate it, use @@ -16,10 +17,10 @@ use bevy_reflect::{std_traits::ReflectDefault, Reflect}; /// /// ## [`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 position of an entity in space relative to its parent position, +/// or the global position relative to the main reference frame if it doesn't have a [`Parent`](bevy_hierarchy::Parent). /// -/// [`GlobalTransform`] is the position of an entity relative to the reference frame. +/// [`GlobalTransform`] is the global position 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). diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index 5f6f42ab0b91f..650295ac7474a 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -5,8 +5,8 @@ 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 position of an entity in space. If the entity has a parent, +/// the position is relative to its parent position. /// /// * To place or move an entity, you should set its [`Transform`]. /// * To get the global transform of an entity, you should get its [`GlobalTransform`]. @@ -15,10 +15,10 @@ use std::ops::Mul; /// /// ## [`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 position of an entity in space relative to its parent position, +/// or the global position relative to the main reference frame if it doesn't have a [`Parent`](bevy_hierarchy::Parent). /// -/// [`GlobalTransform`] is the position of an entity relative to the reference frame. +/// [`GlobalTransform`] is the global position 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). From 79372445e79eea89098ad0a586a2e5aca195e7bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= Date: Mon, 17 Jul 2023 02:15:33 +0100 Subject: [PATCH 02/14] global -> absolute --- crates/bevy_transform/src/components/transform.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index 650295ac7474a..fc79c8f9cfaa4 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -18,7 +18,7 @@ use std::ops::Mul; /// [`Transform`] is the local position of an entity in space relative to its parent position, /// or the global position relative to the main reference frame if it doesn't have a [`Parent`](bevy_hierarchy::Parent). /// -/// [`GlobalTransform`] is the global position of an entity in space relative to the main reference frame. +/// [`GlobalTransform`] is the absolute position 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). From a3a2c8bae02a89d66f2c5f16df280c3caf609d4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= Date: Mon, 17 Jul 2023 02:23:40 +0100 Subject: [PATCH 03/14] global -> absolute 2 --- crates/bevy_transform/src/components/global_transform.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index 139d04595913e..ee02b90e8fec0 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -20,7 +20,7 @@ use bevy_reflect::{std_traits::ReflectDefault, Reflect}; /// [`Transform`] is the local position of an entity in space relative to its parent position, /// or the global position relative to the main reference frame if it doesn't have a [`Parent`](bevy_hierarchy::Parent). /// -/// [`GlobalTransform`] is the global position of an entity in space relative to the main reference frame. +/// [`GlobalTransform`] is the absolute position 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). From 9c918764a3186646640b8ddba1153aa35edccd60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= Date: Wed, 19 Jul 2023 09:40:22 +0100 Subject: [PATCH 04/14] Improve transform and global transform documentation --- .../src/components/global_transform.rs | 57 +++++++++++---- .../src/components/transform.rs | 71 ++++++++++++++----- 2 files changed, 96 insertions(+), 32 deletions(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index ee02b90e8fec0..12378a80b5c98 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -5,35 +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 absolute position of an entity in space, +/// 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 local position of an entity in space relative to its parent position, -/// or the global position relative to the main 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 absolute position of an entity in space, relative to the main 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)] diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index fc79c8f9cfaa4..904fc59498107 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/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 in space. 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 local position of an entity in space relative to its parent position, -/// or the global position relative to the main 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 absolute position of an entity in space, relative to the main 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)] From d5159a2cb1842ebc62493aaa129ccd8e933d8db8 Mon Sep 17 00:00:00 2001 From: Rich Churcher Date: Sun, 22 Sep 2024 18:22:04 +1200 Subject: [PATCH 05/14] Fix TransformBundle links --- crates/bevy_transform/src/components/global_transform.rs | 2 +- crates/bevy_transform/src/components/transform.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index e4ae1f7471740..ce9dd5ba3a23d 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -20,7 +20,7 @@ use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; /// * 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, the [`GlobalTransform`] will be automatically updated with [`TransformPropagate`]. -/// * You may use the [`TransformBundle`](crate::TransformBundle) to guarantee +/// * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee /// an entity has both components. /// /// ## `translation`, `rotation` and `scale` diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index 76178658bc185..1db5bfaae6a03 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -66,7 +66,7 @@ use std::ops::Mul; /// to learn how to use the [`Transform`] of an entity. /// - The [`parenting example`], to learn how [`Transform`] behaves in a hierarchy. /// -/// [`TransformBundle`]: crate::TransformBundle +/// [`TransformBundle`]: crate::bundles::TransformBundle /// [`TransformPropagate`]: crate::TransformSystem::TransformPropagate /// [`PostUpdate`]: bevy_app::PostUpdate /// [`Parent`]: bevy_hierarchy::Parent From 494e9faaae9dc5ca560230bcd15f0246831de401 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 22 Sep 2024 12:00:01 -0400 Subject: [PATCH 06/14] Should not mutate GlobalTransform, not cannot Co-authored-by: Matty --- crates/bevy_transform/src/components/global_transform.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index ce9dd5ba3a23d..746a31e4afd42 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -18,8 +18,8 @@ use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; /// * 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, the [`GlobalTransform`] will be automatically updated with [`TransformPropagate`]. +/// * [`GlobalTransform`] is fully managed by bevy and should not be mutated directly. +/// Use [`Transform`] instead, and the [`GlobalTransform`] will be automatically updated with [`TransformPropagate`]. /// * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee /// an entity has both components. /// From 1b7b9394cbb594b4b40f4fc892ce9a0fe5076f44 Mon Sep 17 00:00:00 2001 From: Rich Churcher Date: Mon, 23 Sep 2024 10:02:04 +1200 Subject: [PATCH 07/14] Update example links to bevyengine.org --- .../bevy_transform/src/components/global_transform.rs | 5 ++--- crates/bevy_transform/src/components/transform.rs | 11 +++++------ 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index 746a31e4afd42..9729075348471 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -62,9 +62,8 @@ use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; /// [`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/ +/// [`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 1db5bfaae6a03..1fff1bb3b21a1 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -70,9 +70,8 @@ use std::ops::Mul; /// [`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-rendering/parenting/ +/// [`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( @@ -101,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, } @@ -338,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; From f112da94b498badc9eb59996b890d4664e0b7c01 Mon Sep 17 00:00:00 2001 From: Rich Churcher Date: Mon, 23 Sep 2024 10:10:26 +1200 Subject: [PATCH 08/14] Avoid leaning into TRS transform language --- .../src/components/global_transform.rs | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index 9729075348471..1ce7a7a948867 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -9,8 +9,8 @@ use bevy_reflect::{std_traits::ReflectDefault, Reflect}; #[cfg(all(feature = "bevy-support", feature = "serialize"))] use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; -/// Describes the absolute transform (translation, rotation, scale) of an entity in space, -/// relative to the main reference frame. +/// [`GlobalTransform`] is an affine transformation from entity-local coordinates to worldspace +/// coordinates. /// /// ## Usage /// @@ -23,21 +23,6 @@ use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; /// * You may use the [`TransformBundle`](crate::bundles::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 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`. -/// /// ## [`Transform`] and [`GlobalTransform`] /// /// [`Transform`] is the local transform of an entity in space relative to its parent transform, From a7448b11871dddc570460d7cc80a286594d5f966 Mon Sep 17 00:00:00 2001 From: Rich Churcher Date: Wed, 29 Jan 2025 08:52:53 +1300 Subject: [PATCH 09/14] Update crates/bevy_transform/src/components/global_transform.rs Co-authored-by: Benjamin Brienen --- crates/bevy_transform/src/components/global_transform.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index 1ce7a7a948867..05919eb590108 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -15,7 +15,7 @@ use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; /// ## 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`], +/// * 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 and should not be mutated directly. From 628076241a0247f0908c3b374ab17748552c6f7e Mon Sep 17 00:00:00 2001 From: Rich Churcher Date: Wed, 29 Jan 2025 08:53:18 +1300 Subject: [PATCH 10/14] Update crates/bevy_transform/src/components/global_transform.rs Co-authored-by: Benjamin Brienen --- crates/bevy_transform/src/components/global_transform.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index 05919eb590108..f5ed273484848 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -16,7 +16,7 @@ use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; /// /// * 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. +/// 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. /// Use [`Transform`] instead, and the [`GlobalTransform`] will be automatically updated with [`TransformPropagate`]. From 0a3bfb4116142919104289a919e806d4b82807fd Mon Sep 17 00:00:00 2001 From: Rich Churcher Date: Wed, 29 Jan 2025 08:53:36 +1300 Subject: [PATCH 11/14] Update crates/bevy_transform/src/components/global_transform.rs Co-authored-by: Benjamin Brienen --- crates/bevy_transform/src/components/global_transform.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index f5ed273484848..fa3ee6a26d670 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -18,8 +18,8 @@ use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; /// * 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. -/// Use [`Transform`] instead, and the [`GlobalTransform`] will be automatically updated with [`TransformPropagate`]. +/// * [`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. /// From bb18c4feaade5bfe2aea3140ec29e9f2690a3bcb Mon Sep 17 00:00:00 2001 From: Rich Churcher Date: Wed, 29 Jan 2025 08:57:21 +1300 Subject: [PATCH 12/14] Update crates/bevy_transform/src/components/transform.rs Co-authored-by: Benjamin Brienen --- crates/bevy_transform/src/components/transform.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index 1fff1bb3b21a1..067c2cd0a4a13 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -13,8 +13,8 @@ use std::ops::Mul; /// ## 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. +/// * 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`] to guarantee this. /// From c8d2998813a0821181ae8ddcfbbc633758a33273 Mon Sep 17 00:00:00 2001 From: Rich Churcher Date: Wed, 29 Jan 2025 08:57:45 +1300 Subject: [PATCH 13/14] Update crates/bevy_transform/src/components/transform.rs Co-authored-by: Benjamin Brienen --- crates/bevy_transform/src/components/transform.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index 067c2cd0a4a13..3b94434cab3da 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -30,7 +30,7 @@ use std::ops::Mul; /// 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 +/// 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: From ccf1071aaee8551db349aaad424774bdbd29fdeb Mon Sep 17 00:00:00 2001 From: Rich Churcher Date: Wed, 29 Jan 2025 09:01:40 +1300 Subject: [PATCH 14/14] Update crates/bevy_transform/src/components/transform.rs Co-authored-by: Benjamin Brienen --- crates/bevy_transform/src/components/transform.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index 3b94434cab3da..005c981a9e5e6 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -52,7 +52,7 @@ use std::ops::Mul; /// [`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 absolute transform of an entity in space, relative to the main 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`].