From 5bf895275be3085fba7a06f47e42c82979dcce47 Mon Sep 17 00:00:00 2001 From: Jan Hohenheim Date: Mon, 14 Jul 2025 04:04:15 +0200 Subject: [PATCH 1/9] Improve glTF coordinate migration guide --- .../migration-guides/convert-coordinates.md | 59 ++++++++++++------- 1 file changed, 38 insertions(+), 21 deletions(-) diff --git a/release-content/migration-guides/convert-coordinates.md b/release-content/migration-guides/convert-coordinates.md index 85ab80ed20..f925d1b4fe 100644 --- a/release-content/migration-guides/convert-coordinates.md +++ b/release-content/migration-guides/convert-coordinates.md @@ -4,34 +4,52 @@ authors: ["@janhohenheim"] pull_requests: [19633, 19685, 19816] --- -glTF uses the following coordinate system: +If you're loading a glTF, you will be greeted by the following deprecation warning: -- forward: Z -- up: Y -- right: -X +> Starting from Bevy 0.18, by default all imported glTF scenes will be rotated by 180 degrees around the Y axis to align with Bevy's coordinate system. +> You are currently importing glTF scenes using the old behavior. Consider opting-in to the new import behavior by enabling the `gltf_convert_coordinates_default` feature. +> If you encounter any issues please file a bug! +> If you want to continue using the old behavior going forward (even when the default changes in 0.18), manually set the corresponding option in the `GltfPlugin` or `GltfLoaderSettings`. +> See the migration guide for more details. -and Bevy uses: +As the warning says, this means that from now on, glTF scenes will be rotated by 180 degrees around the Y axis. To understand why this is desirable, +we need to take a look at coordinate systems. + +Bevy uses the following coordinate system: - forward: -Z - up: Y - right: X -This means that to correctly import glTFs into Bevy, vertex data should be rotated by 180 degrees around the Y axis. -For the longest time, Bevy has simply ignored this distinction. That caused issues when working across programs, as most software respects the -glTF coordinate system when importing and exporting glTFs. Your scene might have looked correct in Blender, Maya, TrenchBroom, etc. but everything would be flipped when importing it into Bevy! +Even though we never explicitly stated this anywhere, it was implicitly accepted that this coordinate system was used for all things that have a `Transform`, +as indicated by e.g. `Transform::forward()` returning the local -Z direction. In contrast, glTF is a bit more complicated. Models loaded from glTF scenes use the following coordinate system: -Long-term, we'd like to fix our glTF imports to use the correct coordinate system by default. -But changing the import behavior would mean that *all* imported glTFs of *all* users would suddenly look different, breaking their scenes! +- forward: Z +- up: Y +- right: -X + +but cameras and lights loaded from glTFs use the following coordinate system: + +- forward: -Z +- up: Y +- right: X + +As you can see, this clashes with how Bevy assumes that everything in the world uses the same coordinate system. +In the past, we have imported glTFs using the camera / light coordinate system for everything, as it is already aligned with Bevy. +In other words, the glTF imported simply assumed that models used -Z as their forward direction, even though they use +Z. + +But that meant that a glTF model's `Transform::forward()` would actually point backwards from the point of view of the glTF model, +which is counterintuitive and very annoying when working across different art pipelines. + +To remedy this, we want to change the default glTF import behavior to instead load the scene so that the coordinate system of models is aligned with Bevy. +In practice, this means rotating the scene as described above. +The downside is that glTF cameras that have an identity transform in glTF will now look to +Z instead of -Z in Bevy. In practice, this should not be a problem, +as the whole scene rotated anyways, so the end result on your screen will look the exact same. + +But changing the import behavior right now in one swoop would mean that *all* imported glTFs of *all* users would suddenly look different, breaking their scenes! Not to mention that any bugs in the conversion code would be incredibly frustating for users. -This is why we are now gradually rolling out support for corrected glTF imports. You will now be greeted by the following warning when using the old behavior: - -> Starting from Bevy 0.18, by default all imported glTF models will be rotated by 180 degrees around the Y axis to align with Bevy's coordinate system. -> You are currently importing glTF files using the old behavior. Consider opting-in to the new import behavior by enabling the `gltf_convert_coordinates_default` feature. -> If you encounter any issues please file a bug! -> If you want to continue using the old behavior going forward (even when the default changes in 0.18), manually set the corresponding option in the `GltfPlugin` or `GltfLoaderSettings`. -> See the migration guide for more details. - +This is why we are now gradually rolling out support for corrected glTF imports. As the warning says, you can opt into the new behavior by enabling the `gltf_convert_coordinates_default` feature in your `Cargo.toml`: ```toml @@ -79,10 +97,9 @@ let handle = asset_server.load_with_settings( ); ``` -After opting into the new behavior, your scene will be oriented such that your modeling software's forward direction correctly corresponds to Bevy's forward direction. +After opting into the new behavior, your scene will be oriented such that other software's model forward direction correctly corresponds to Bevy's forward direction. -For example, Blender assumes -Y to be forward, so exporting the following model to glTF and loading it in Bevy with the new settings will ensure everything is -oriented the right way across all programs in your pipeline: +For example, Blender assumes -Y to be forward for models, so exporting the following model to glTF and loading it in Bevy with the new settings will ensure that the fox looks to -Z in Bevy: ![Blender Coordinate System](blender-coords.png) From d60ba1fb33cece275305ff0807483c4b84b382b0 Mon Sep 17 00:00:00 2001 From: Jan Hohenheim Date: Mon, 14 Jul 2025 04:07:25 +0200 Subject: [PATCH 2/9] Improve phrase --- release-content/migration-guides/convert-coordinates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/release-content/migration-guides/convert-coordinates.md b/release-content/migration-guides/convert-coordinates.md index f925d1b4fe..47a03087b9 100644 --- a/release-content/migration-guides/convert-coordinates.md +++ b/release-content/migration-guides/convert-coordinates.md @@ -12,8 +12,8 @@ If you're loading a glTF, you will be greeted by the following deprecation warni > If you want to continue using the old behavior going forward (even when the default changes in 0.18), manually set the corresponding option in the `GltfPlugin` or `GltfLoaderSettings`. > See the migration guide for more details. -As the warning says, this means that from now on, glTF scenes will be rotated by 180 degrees around the Y axis. To understand why this is desirable, -we need to take a look at coordinate systems. +As the warning says, this means that from now on glTF scenes will imported with a 180 degree rotation around the Y axis when compared to the old behavior. +To understand why this is desirable, we need to take a look at coordinate systems. Bevy uses the following coordinate system: From 7527ee6144cf5c060dd75abff87d448d388b8ebe Mon Sep 17 00:00:00 2001 From: Jan Hohenheim Date: Mon, 14 Jul 2025 04:08:11 +0200 Subject: [PATCH 3/9] Improve phrase --- release-content/migration-guides/convert-coordinates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-content/migration-guides/convert-coordinates.md b/release-content/migration-guides/convert-coordinates.md index 47a03087b9..54a8ad31bb 100644 --- a/release-content/migration-guides/convert-coordinates.md +++ b/release-content/migration-guides/convert-coordinates.md @@ -36,7 +36,7 @@ but cameras and lights loaded from glTFs use the following coordinate system: As you can see, this clashes with how Bevy assumes that everything in the world uses the same coordinate system. In the past, we have imported glTFs using the camera / light coordinate system for everything, as it is already aligned with Bevy. -In other words, the glTF imported simply assumed that models used -Z as their forward direction, even though they use +Z. +In other words, the glTF imported simply assumed that glTF models used -Z as their forward direction, even though they use +Z. But that meant that a glTF model's `Transform::forward()` would actually point backwards from the point of view of the glTF model, which is counterintuitive and very annoying when working across different art pipelines. From 95cce42e83970d4fd5b52de3f467b8ef4f2c637e Mon Sep 17 00:00:00 2001 From: Jan Hohenheim Date: Mon, 14 Jul 2025 04:08:38 +0200 Subject: [PATCH 4/9] Improve phrase --- release-content/migration-guides/convert-coordinates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-content/migration-guides/convert-coordinates.md b/release-content/migration-guides/convert-coordinates.md index 54a8ad31bb..36f5188667 100644 --- a/release-content/migration-guides/convert-coordinates.md +++ b/release-content/migration-guides/convert-coordinates.md @@ -38,7 +38,7 @@ As you can see, this clashes with how Bevy assumes that everything in the world In the past, we have imported glTFs using the camera / light coordinate system for everything, as it is already aligned with Bevy. In other words, the glTF imported simply assumed that glTF models used -Z as their forward direction, even though they use +Z. -But that meant that a glTF model's `Transform::forward()` would actually point backwards from the point of view of the glTF model, +But that meant that a glTF model's `Transform::forward()` would actually point backwards from the point of view of the model, which is counterintuitive and very annoying when working across different art pipelines. To remedy this, we want to change the default glTF import behavior to instead load the scene so that the coordinate system of models is aligned with Bevy. From 722df2cac66e6b9e3cfc682edbe6609921673ea8 Mon Sep 17 00:00:00 2001 From: Jan Hohenheim Date: Mon, 14 Jul 2025 04:09:00 +0200 Subject: [PATCH 5/9] Improve phrase --- release-content/migration-guides/convert-coordinates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-content/migration-guides/convert-coordinates.md b/release-content/migration-guides/convert-coordinates.md index 36f5188667..26ffa03788 100644 --- a/release-content/migration-guides/convert-coordinates.md +++ b/release-content/migration-guides/convert-coordinates.md @@ -41,7 +41,7 @@ In other words, the glTF imported simply assumed that glTF models used -Z as the But that meant that a glTF model's `Transform::forward()` would actually point backwards from the point of view of the model, which is counterintuitive and very annoying when working across different art pipelines. -To remedy this, we want to change the default glTF import behavior to instead load the scene so that the coordinate system of models is aligned with Bevy. +To remedy this, we want to change the default glTF import behavior to instead load the scene so that the coordinate system of *models* instead of *cameras* is aligned with Bevy. In practice, this means rotating the scene as described above. The downside is that glTF cameras that have an identity transform in glTF will now look to +Z instead of -Z in Bevy. In practice, this should not be a problem, as the whole scene rotated anyways, so the end result on your screen will look the exact same. From 55f8e1d16403a531bcc12c0d12f19256ae372523 Mon Sep 17 00:00:00 2001 From: Jan Hohenheim Date: Mon, 14 Jul 2025 04:09:59 +0200 Subject: [PATCH 6/9] Improve phrase --- release-content/migration-guides/convert-coordinates.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/release-content/migration-guides/convert-coordinates.md b/release-content/migration-guides/convert-coordinates.md index 26ffa03788..2af8922118 100644 --- a/release-content/migration-guides/convert-coordinates.md +++ b/release-content/migration-guides/convert-coordinates.md @@ -41,10 +41,10 @@ In other words, the glTF imported simply assumed that glTF models used -Z as the But that meant that a glTF model's `Transform::forward()` would actually point backwards from the point of view of the model, which is counterintuitive and very annoying when working across different art pipelines. -To remedy this, we want to change the default glTF import behavior to instead load the scene so that the coordinate system of *models* instead of *cameras* is aligned with Bevy. +To remedy this, we want to change the default glTF import behavior so that the coordinate system of glTF *models* instead of glTF *cameras* is aligned with Bevy. In practice, this means rotating the scene as described above. -The downside is that glTF cameras that have an identity transform in glTF will now look to +Z instead of -Z in Bevy. In practice, this should not be a problem, -as the whole scene rotated anyways, so the end result on your screen will look the exact same. +The downside is that glTF cameras that have an identity transform in glTF will now look to +Z instead of -Z in Bevy. +This should not be a problem, as the whole scene rotated anyways, so the end result on your screen will look the exact same. But changing the import behavior right now in one swoop would mean that *all* imported glTFs of *all* users would suddenly look different, breaking their scenes! Not to mention that any bugs in the conversion code would be incredibly frustating for users. From 737ff6d4c79c8e9614172983cfc4c3e0b77937a4 Mon Sep 17 00:00:00 2001 From: Jan Hohenheim Date: Mon, 14 Jul 2025 04:10:34 +0200 Subject: [PATCH 7/9] Improve phrase --- release-content/migration-guides/convert-coordinates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-content/migration-guides/convert-coordinates.md b/release-content/migration-guides/convert-coordinates.md index 2af8922118..d1eef64e0c 100644 --- a/release-content/migration-guides/convert-coordinates.md +++ b/release-content/migration-guides/convert-coordinates.md @@ -46,7 +46,7 @@ In practice, this means rotating the scene as described above. The downside is that glTF cameras that have an identity transform in glTF will now look to +Z instead of -Z in Bevy. This should not be a problem, as the whole scene rotated anyways, so the end result on your screen will look the exact same. -But changing the import behavior right now in one swoop would mean that *all* imported glTFs of *all* users would suddenly look different, breaking their scenes! +But changing the import behavior right now in one swoop would mean that *almost all* imported glTFs of users would suddenly look different, breaking their scenes! Not to mention that any bugs in the conversion code would be incredibly frustating for users. This is why we are now gradually rolling out support for corrected glTF imports. From 00a51bb52c807c1fe68e8b83b7cd55bf8857d83e Mon Sep 17 00:00:00 2001 From: Jan Hohenheim Date: Mon, 14 Jul 2025 04:12:08 +0200 Subject: [PATCH 8/9] Improve phrase --- release-content/migration-guides/convert-coordinates.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/release-content/migration-guides/convert-coordinates.md b/release-content/migration-guides/convert-coordinates.md index d1eef64e0c..c3daabcfbf 100644 --- a/release-content/migration-guides/convert-coordinates.md +++ b/release-content/migration-guides/convert-coordinates.md @@ -46,8 +46,9 @@ In practice, this means rotating the scene as described above. The downside is that glTF cameras that have an identity transform in glTF will now look to +Z instead of -Z in Bevy. This should not be a problem, as the whole scene rotated anyways, so the end result on your screen will look the exact same. -But changing the import behavior right now in one swoop would mean that *almost all* imported glTFs of users would suddenly look different, breaking their scenes! -Not to mention that any bugs in the conversion code would be incredibly frustating for users. +But, since most users load only models and not cameras through glTF, +changing the import behavior in one big swoop would mean that most imported glTF models would suddenly look different, breaking users' scenes! +Not to mention that any bugs in the conversion code would be incredibly frustrating for users. This is why we are now gradually rolling out support for corrected glTF imports. As the warning says, you can opt into the new behavior by enabling the `gltf_convert_coordinates_default` feature in your `Cargo.toml`: From 3b75737a20e146dd4a9f11cafc9d456a231b4ed4 Mon Sep 17 00:00:00 2001 From: Jan Hohenheim Date: Mon, 14 Jul 2025 09:05:22 +0200 Subject: [PATCH 9/9] Update convert-coordinates.md Co-authored-by: IceSentry --- release-content/migration-guides/convert-coordinates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-content/migration-guides/convert-coordinates.md b/release-content/migration-guides/convert-coordinates.md index c3daabcfbf..e054d39d2c 100644 --- a/release-content/migration-guides/convert-coordinates.md +++ b/release-content/migration-guides/convert-coordinates.md @@ -44,7 +44,7 @@ which is counterintuitive and very annoying when working across different art pi To remedy this, we want to change the default glTF import behavior so that the coordinate system of glTF *models* instead of glTF *cameras* is aligned with Bevy. In practice, this means rotating the scene as described above. The downside is that glTF cameras that have an identity transform in glTF will now look to +Z instead of -Z in Bevy. -This should not be a problem, as the whole scene rotated anyways, so the end result on your screen will look the exact same. +This should not be a problem, as the whole scene is rotated anyways, so the end result on your screen will look the exact same. But, since most users load only models and not cameras through glTF, changing the import behavior in one big swoop would mean that most imported glTF models would suddenly look different, breaking users' scenes!