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 | 51 ++++++++++++------- 1 file changed, 34 insertions(+), 17 deletions(-) diff --git a/release-content/migration-guides/convert-coordinates.md b/release-content/migration-guides/convert-coordinates.md index 85ab80ed2053e..f925d1b4fec11 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: + +> 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. + +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 + +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: - forward: Z - up: Y - right: -X -and Bevy uses: +but cameras and lights loaded from glTFs use 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! +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. -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! -Not to mention that any bugs in the conversion code would be incredibly frustating for users. +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. -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: +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. -> 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. +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. 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 f925d1b4fec11..47a03087b97fc 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 47a03087b97fc..54a8ad31bbfa2 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 54a8ad31bbfa2..36f518866766a 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 36f518866766a..26ffa037887d1 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 26ffa037887d1..2af89221183d1 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 2af89221183d1..d1eef64e0c7d6 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 d1eef64e0c7d6..c3daabcfbfb4e 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 c3daabcfbfb4e..e054d39d2c5fd 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!