Clarify `Transform` and `GlobalTransform` documentation (adopted) by bas-ie · Pull Request #15358 · bevyengine/bevy

bas-ie · 2024-09-22T06:00:50Z

NOTE: this is adopted from Selene-Amanita's #9182. I've:

updated the branch
tried to apply rparrett's suggestions

Original PR description follows. Because it's from last year, it'd be great to get fresh eyes on it to see if it inadvertently removes things we'd like to keep. I also have one question about documentation links, below.

Objective

The doc about Transform and GlobalTransform mention "the reference frame", which can be confusing for two reasons:

a reference frame is y definition relative, Transform is in the reference frame of the parent,

not everybody is familiar with this term, and some people might see "frame" and think it is talking about viewport coordinates. (I actually helped someone on discord who was confused because of that, hence this PR)

Also:

some links are broken

the documentation doesn't detail the meaning of translation, rotation and scale

the documentation uses the term "position" which is misleading

This PR tries to fix that.

Solution

Specify "local" and "absolute"

Specify "in space" (I could have said "in the world" but that could be confusing because of the ECS world, I would also have said "2D/3D space")

Specify "main reference frame"

fix the links

add a section to detail the meaning of translation, rotation and scale

use the term "transform", after defining it, instead of "position"

pablo-lua

Looks clear and now populated with useful examples of what to do or how to do. All good.

mweatherley · 2024-09-22T15:34:22Z

 use bevy_reflect::{ReflectDeserialize, ReflectSerialize};

-/// [`GlobalTransform`] is an affine transformation from entity-local coordinates to worldspace coordinates.
+/// Describes the absolute transform (translation, rotation, scale) of an entity in space,


The (translation, rotation, scale) part is a bit misleading, since GlobalTransform is not a TRS transformation in general. This also applies to the later part of this doc comment which breaks down translation, rotation, and scale.

Right, I might see if I can walk that part back a bit.

Would you mind re-checking, just to see if I've understood you correctly? Cheers!

Co-authored-by: Matty <weatherleymatthew@gmail.com>

rparrett · 2024-09-22T16:01:59Z

Could we remove my tagged username from the description so it doesn't end up in a commit message?

alice-i-cecile · 2024-09-22T16:28:16Z

Could we remove my tagged username from the description so it doesn't end up in a commit message?

Removed to prevent endless notification spam for both of you.

bas-ie · 2024-09-22T19:09:04Z

Could we remove my tagged username from the description so it doesn't end up in a commit message?

Sorry!

BenjaminBrienen · 2025-01-23T07:09:47Z

+///
+/// [`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.


Suggested change

/// [`GlobalTransform`], otherwise, it's relative to the main reference frame.

/// [`GlobalTransform`]; otherwise, it's relative to the main reference frame.

BenjaminBrienen · 2025-01-23T07:15:50Z

+/// [`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`].


Suggested change

/// [`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`].

/// [`Transform`] is the local transform of an entity in space relative to its parent transform;

/// if it doesn't have a [`Parent`], then it is equivalent to the global transform relative to the main reference frame.

I think I'd go with a separate sentence here.

BenjaminBrienen · 2025-01-23T07:21:31Z

+/// - The `scale` is relative to the parent's [`GlobalTransform`], it is multiplied
+///   by it.


Suggested change

/// - The `scale` is relative to the parent's [`GlobalTransform`], it is multiplied

/// by it.

/// - The `scale` is relative to the parent's [`GlobalTransform`] (it is multiplied in)

Hrm, I'm not particularly convinced by either one. Maybe simply,

The scale is multiplied by the parent entity's [GlobalTransform].

?

BenjaminBrienen · 2025-01-23T07:23:19Z

+/// [`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`].


Suggested change

/// [`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`].

/// [`Transform`] is the local transform of an entity in space relative to its parent transform;

/// if it doesn't have a [`Parent`], then it is the global transform relative to the main reference frame.

Think I'll add a sentence here too.

BenjaminBrienen · 2025-01-23T07:24:13Z

+/// [`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.


Suggested change

/// you may notice a 1 frame lag before the [`GlobalTransform`] is updated.

/// you may notice 1 frame of lag before the [`GlobalTransform`] is updated.

I should update to use "one" 🤔

Co-authored-by: Benjamin Brienen <benjamin.brienen@outlook.com>

bas-ie · 2025-01-28T20:02:46Z

Thanks for the review! I've neglected this PR, will try to get back to it today.

ChristopherBiscardi · 2026-05-22T10:53:44Z

This is still desired but needs to be revived

Selene-Amanita and others added 5 commits July 17, 2023 02:09

Clarify Transform and GlobalTransform documentation

15b6aab

global -> absolute

7937244

global -> absolute 2

a3a2c8b

Improve transform and global transform documentation

9c91876

Merge branch 'main' into clarify-transform-doc

1094728

bas-ie commented Sep 22, 2024

View reviewed changes

Comment thread crates/bevy_transform/src/components/global_transform.rs Outdated

bas-ie mentioned this pull request Sep 22, 2024

Clarify Transform and GlobalTransform documentation #9182

Closed

Fix TransformBundle links

d5159a2

alice-i-cecile requested review from Selene-Amanita and rparrett September 22, 2024 14:16

alice-i-cecile approved these changes Sep 22, 2024

View reviewed changes

alice-i-cecile added C-Docs An addition or correction to our documentation A-Transform Translations, rotations and scales D-Straightforward Simple bug fixes and API improvements, docs, test and examples S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Sep 22, 2024

pablo-lua approved these changes Sep 22, 2024

View reviewed changes

pablo-lua added S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Sep 22, 2024

alice-i-cecile added this pull request to the merge queue Sep 22, 2024

mweatherley suggested changes Sep 22, 2024

View reviewed changes

alice-i-cecile removed this pull request from the merge queue due to a manual request Sep 22, 2024

Should not mutate GlobalTransform, not cannot

494e9fa

Co-authored-by: Matty <weatherleymatthew@gmail.com>

alice-i-cecile added S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged and removed S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it labels Sep 22, 2024

bas-ie added 3 commits September 23, 2024 10:02

Update example links to bevyengine.org

1b7b939

Merge branch 'main' into clarify-transform-doc

6e08f16

Avoid leaning into TRS transform language

f112da9

bas-ie requested a review from mweatherley September 22, 2024 22:13

BenjaminBrienen suggested changes Jan 23, 2025

View reviewed changes

bas-ie and others added 6 commits January 29, 2025 08:52

Update crates/bevy_transform/src/components/global_transform.rs

a7448b1

Co-authored-by: Benjamin Brienen <benjamin.brienen@outlook.com>

Update crates/bevy_transform/src/components/global_transform.rs

6280762

Co-authored-by: Benjamin Brienen <benjamin.brienen@outlook.com>

Update crates/bevy_transform/src/components/global_transform.rs

0a3bfb4

Co-authored-by: Benjamin Brienen <benjamin.brienen@outlook.com>

Update crates/bevy_transform/src/components/transform.rs

bb18c4f

Co-authored-by: Benjamin Brienen <benjamin.brienen@outlook.com>

Update crates/bevy_transform/src/components/transform.rs

c8d2998

Co-authored-by: Benjamin Brienen <benjamin.brienen@outlook.com>

Update crates/bevy_transform/src/components/transform.rs

ccf1071

Co-authored-by: Benjamin Brienen <benjamin.brienen@outlook.com>

cart force-pushed the main branch from af894e5 to 017ffc5 Compare May 4, 2026 23:35

cart closed this May 5, 2026

cart reopened this May 5, 2026

ChristopherBiscardi closed this May 22, 2026

	/// [`GlobalTransform`], otherwise, it's relative to the main reference frame.
	/// [`GlobalTransform`]; otherwise, it's relative to the main reference frame.

		/// [`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`].

		/// - The `scale` is relative to the parent's [`GlobalTransform`], it is multiplied
		/// by it.

	/// you may notice a 1 frame lag before the [`GlobalTransform`] is updated.
	/// you may notice 1 frame of lag before the [`GlobalTransform`] is updated.

Uh oh!

Uh oh!

Conversation

bas-ie commented Sep 22, 2024 • edited by alice-i-cecile Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Uh oh!

Uh oh!

pablo-lua left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rparrett commented Sep 22, 2024

Uh oh!

alice-i-cecile commented Sep 22, 2024

Uh oh!

bas-ie commented Sep 22, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bas-ie commented Jan 28, 2025

Uh oh!

ChristopherBiscardi commented May 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

bas-ie commented Sep 22, 2024 •

edited by alice-i-cecile

Loading