Migrate bevy_transform to required components (#14964)

The first step in the migration to required components! This PR removes
`GlobalTransform` from all user-facing code, since it's now added
automatically wherever `Transform` is used.

## Testing

- None of the examples I tested were broken, and I assume breaking
transforms in any way would be visible *everywhere*

---

## Changelog

- Make `Transform` require `GlobalTransform`
~~- Remove `GlobalTransform` from all engine bundles~~
- Remove in-engine insertions of GlobalTransform and TransformBundle
- Deprecate `TransformBundle`
- update docs to reflect changes

## Migration Guide

Replace all insertions of `GlobalTransform` and/or `TransformBundle`
with `Transform` alone.

---------

Co-authored-by: Alice Cecile <[email protected]>
Co-authored-by: Tim <[email protected]>

Author: 3 people

crates/bevy_transform/src/bundles.rs

@@ -1,3 +1,4 @@
+#![expect(deprecated)]
 use bevy_ecs::bundle::Bundle;
 
 use crate::prelude::{GlobalTransform, Transform};
@@ -24,6 +25,10 @@ use crate::prelude::{GlobalTransform, Transform};
 /// update the [`Transform`] of an entity in this schedule or after, you will notice a 1 frame lag
 /// before the [`GlobalTransform`] is updated.
 #[derive(Clone, Copy, Debug, Default, Bundle)]
+#[deprecated(
+    since = "0.15.0",
+    note = "Use the `Transform` component instead. Inserting `Transform` will now also insert a `GlobalTransform` automatically."
+)]
 pub struct TransformBundle {
     /// The transform of the entity.
     pub local: Transform,

crates/bevy_transform/src/components/global_transform.rs

@@ -17,7 +17,9 @@ use {
 ///
 /// * 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::bundles::TransformBundle) to guarantee this.
+///   ~* You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee this.~
+///   * [`TransformBundle`](crate::bundles::TransformBundle) is now deprecated.
+///     [`GlobalTransform`] is automatically inserted whenever [`Transform`] is inserted.
 ///
 /// ## [`Transform`] and [`GlobalTransform`]
 ///

crates/bevy_transform/src/components/transform.rs

@@ -13,7 +13,9 @@ use {
 /// * 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 be displayed, an entity must have both a [`Transform`] and a [`GlobalTransform`].
-///   * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee this.
+///   ~* You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee this.~
+///   * [`TransformBundle`](crate::bundles::TransformBundle) is now deprecated.
+///     [`GlobalTransform`] is inserted automatically whenever [`Transform`] is inserted.
 ///
 /// ## [`Transform`] and [`GlobalTransform`]
 ///
@@ -39,6 +41,7 @@ use {
 #[cfg_attr(
     feature = "bevy-support",
     derive(Component, Reflect),
+    require(GlobalTransform),
     reflect(Component, Default, PartialEq, Debug)
 )]
 #[cfg_attr(

crates/bevy_transform/src/helper.rs

@@ -88,7 +88,6 @@ mod tests {
     use bevy_math::{Quat, Vec3};
 
     use crate::{
-        bundles::TransformBundle,
         components::{GlobalTransform, Transform},
         helper::TransformHelper,
         plugins::TransformPlugin,
@@ -122,7 +121,7 @@ mod tests {
         let mut entity = None;
 
         for transform in transforms {
-            let mut e = app.world_mut().spawn(TransformBundle::from(transform));
+            let mut e = app.world_mut().spawn(transform);
 
             if let Some(entity) = entity {
                 e.set_parent(entity);

crates/bevy_transform/src/lib.rs

@@ -32,6 +32,8 @@ pub mod systems;
 /// The transform prelude.
 ///
 /// This includes the most common types in this crate, re-exported for your convenience.
+#[doc(hidden)]
+#[expect(deprecated)]
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::components::*;

crates/bevy_transform/src/systems.rs

@@ -190,7 +190,7 @@ mod test {
     use bevy_math::{vec3, Vec3};
     use bevy_tasks::{ComputeTaskPool, TaskPool};
 
-    use crate::{bundles::TransformBundle, systems::*};
+    use crate::systems::*;
     use bevy_hierarchy::{BuildChildren, ChildBuild};
 
     #[test]
@@ -199,8 +199,7 @@ mod test {
         let mut world = World::default();
         let offset_global_transform =
             |offset| GlobalTransform::from(Transform::from_xyz(offset, offset, offset));
-        let offset_transform =
-            |offset| TransformBundle::from_transform(Transform::from_xyz(offset, offset, offset));
+        let offset_transform = |offset| Transform::from_xyz(offset, offset, offset);
 
         let mut schedule = Schedule::default();
         schedule.add_systems((sync_simple_transforms, propagate_transforms));
@@ -257,22 +256,14 @@ mod test {
         schedule.add_systems((sync_simple_transforms, propagate_transforms));
 
         // Root entity
-        world.spawn(TransformBundle::from(Transform::from_xyz(1.0, 0.0, 0.0)));
+        world.spawn(Transform::from_xyz(1.0, 0.0, 0.0));
 
         let mut children = Vec::new();
         world
-            .spawn(TransformBundle::from(Transform::from_xyz(1.0, 0.0, 0.0)))
+            .spawn(Transform::from_xyz(1.0, 0.0, 0.0))
             .with_children(|parent| {
-                children.push(
-                    parent
-                        .spawn(TransformBundle::from(Transform::from_xyz(0.0, 2.0, 0.)))
-                        .id(),
-                );
-                children.push(
-                    parent
-                        .spawn(TransformBundle::from(Transform::from_xyz(0.0, 0.0, 3.)))
-                        .id(),
-                );
+                children.push(parent.spawn(Transform::from_xyz(0.0, 2.0, 0.)).id());
+                children.push(parent.spawn(Transform::from_xyz(0.0, 0.0, 3.)).id());
             });
         schedule.run(&mut world);
 
@@ -299,18 +290,10 @@ mod test {
         let mut commands = Commands::new(&mut queue, &world);
         let mut children = Vec::new();
         commands
-            .spawn(TransformBundle::from(Transform::from_xyz(1.0, 0.0, 0.0)))
+            .spawn(Transform::from_xyz(1.0, 0.0, 0.0))
             .with_children(|parent| {
-                children.push(
-                    parent
-                        .spawn(TransformBundle::from(Transform::from_xyz(0.0, 2.0, 0.0)))
-                        .id(),
-                );
-                children.push(
-                    parent
-                        .spawn(TransformBundle::from(Transform::from_xyz(0.0, 0.0, 3.0)))
-                        .id(),
-                );
+                children.push(parent.spawn(Transform::from_xyz(0.0, 2.0, 0.0)).id());
+                children.push(parent.spawn(Transform::from_xyz(0.0, 0.0, 3.0)).id());
             });
         queue.apply(&mut world);
         schedule.run(&mut world);
@@ -417,15 +400,12 @@ mod test {
         let mut grandchild = Entity::from_raw(1);
         let parent = app
             .world_mut()
-            .spawn((
-                Transform::from_translation(translation),
-                GlobalTransform::IDENTITY,
-            ))
+            .spawn(Transform::from_translation(translation))
             .with_children(|builder| {
                 child = builder
-                    .spawn(TransformBundle::IDENTITY)
+                    .spawn(Transform::IDENTITY)
                     .with_children(|builder| {
-                        grandchild = builder.spawn(TransformBundle::IDENTITY).id();
+                        grandchild = builder.spawn(Transform::IDENTITY).id();
                     })
                     .id();
             })
@@ -462,9 +442,9 @@ mod test {
         fn setup_world(world: &mut World) -> (Entity, Entity) {
             let mut grandchild = Entity::from_raw(0);
             let child = world
-                .spawn(TransformBundle::IDENTITY)
+                .spawn(Transform::IDENTITY)
                 .with_children(|builder| {
-                    grandchild = builder.spawn(TransformBundle::IDENTITY).id();
+                    grandchild = builder.spawn(Transform::IDENTITY).id();
                 })
                 .id();
             (child, grandchild)
@@ -477,7 +457,7 @@ mod test {
         assert_eq!(temp_grandchild, grandchild);
 
         app.world_mut()
-            .spawn(TransformBundle::IDENTITY)
+            .spawn(Transform::IDENTITY)
             .add_children(&[child]);
         core::mem::swap(
             &mut *app.world_mut().get_mut::<Parent>(child).unwrap(),
@@ -496,14 +476,9 @@ mod test {
         let mut schedule = Schedule::default();
         schedule.add_systems((sync_simple_transforms, propagate_transforms));
 
-        // Spawn a `TransformBundle` entity with a local translation of `Vec3::ONE`
-        let mut spawn_transform_bundle = || {
-            world
-                .spawn(TransformBundle::from_transform(
-                    Transform::from_translation(translation),
-                ))
-                .id()
-        };
+        // Spawn a `Transform` entity with a local translation of `Vec3::ONE`
+        let mut spawn_transform_bundle =
+            || world.spawn(Transform::from_translation(translation)).id();
 
         // Spawn parent and child with identical transform bundles
         let parent = spawn_transform_bundle();

errors/B0004.md

@@ -29,7 +29,7 @@ fn setup_cube(
     mut materials: ResMut<Assets<StandardMaterial>>,
 ) {
     commands
-        .spawn(TransformBundle::default())
+        .spawn(Transform::default())
         .with_children(|parent| {
             // cube
             parent.spawn(PbrBundle {
@@ -61,8 +61,7 @@ doesn't have a [`ViewVisibility`] or [`InheritedVisibility`] component.
 Since the cube is spawned as a child of an entity without the
 visibility components, it will not be visible at all.
 
-To fix this, you must use [`SpatialBundle`] over [`TransformBundle`],
-as follows:
+To fix this, you must use [`SpatialBundle`], as follows:
 
 ```rust,no_run
 use bevy::prelude::*;
@@ -73,7 +72,7 @@ fn setup_cube(
     mut materials: ResMut<Assets<StandardMaterial>>,
 ) {
     commands
-        // We use SpatialBundle instead of TransformBundle, it contains the
+        // We use SpatialBundle instead of Transform, it contains the
         // visibility components needed to display the cube,
         // In addition to the Transform and GlobalTransform components.
         .spawn(SpatialBundle::default())
@@ -103,18 +102,15 @@ fn main() {
 ```
 
 A similar problem occurs when the [`GlobalTransform`] component is missing.
-However, when a parent [`GlobalTransform`] is missing,
-it will simply prevent all transform propagation,
-including when updating the [`Transform`] component of the child.
+However, it will be automatically inserted whenever `Transform` is
+inserted, as it's a required component.
 
 You will most likely encounter this warning when loading a scene
 as a child of a pre-existing [`Entity`] that does not have the proper components.
 
 [`InheritedVisibility`]: https://docs.rs/bevy/*/bevy/render/view/struct.InheritedVisibility.html
 [`ViewVisibility`]: https://docs.rs/bevy/*/bevy/render/view/struct.ViewVisibility.html
 [`GlobalTransform`]: https://docs.rs/bevy/*/bevy/transform/components/struct.GlobalTransform.html
-[`Transform`]: https://docs.rs/bevy/*/bevy/transform/components/struct.Transform.html
 [`Parent`]: https://docs.rs/bevy/*/bevy/hierarchy/struct.Parent.html
 [`Entity`]: https://docs.rs/bevy/*/bevy/ecs/entity/struct.Entity.html
 [`SpatialBundle`]: https://docs.rs/bevy/*/bevy/render/prelude/struct.SpatialBundle.html
-[`TransformBundle`]: https://docs.rs/bevy/*/bevy/transform/struct.TransformBundle.html

examples/animation/custom_skinned_mesh.rs

@@ -130,15 +130,9 @@ fn setup(
     for i in -5..5 {
         // Create joint entities
         let joint_0 = commands
-            .spawn(TransformBundle::from(Transform::from_xyz(
-                i as f32 * 1.5,
-                0.0,
-                i as f32 * 0.1,
-            )))
-            .id();
-        let joint_1 = commands
-            .spawn((AnimatedJoint, TransformBundle::IDENTITY))
+            .spawn(Transform::from_xyz(i as f32 * 1.5, 0.0, i as f32 * 0.1))
             .id();
+        let joint_1 = commands.spawn((AnimatedJoint, Transform::IDENTITY)).id();
 
         // Set joint_1 as a child of joint_0.
         commands.entity(joint_0).add_children(&[joint_1]);

examples/asset/asset_decompression.rs

@@ -111,7 +111,7 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
             ..default()
         },
         Sprite::default(),
-        TransformBundle::default(),
+        Transform::default(),
         VisibilityBundle::default(),
     ));
 }

examples/stress_tests/transform_hierarchy.rs

@@ -380,7 +380,7 @@ fn spawn_tree(
     }
 
     // insert root
-    ents.push(commands.spawn(TransformBundle::from(root_transform)).id());
+    ents.push(commands.spawn(root_transform).id());
 
     let mut result = InsertResult::default();
     let mut rng = rand::thread_rng();
@@ -426,7 +426,7 @@ fn spawn_tree(
             };
 
             // only insert the components necessary for the transform propagation
-            cmd = cmd.insert(TransformBundle::from(transform));
+            cmd = cmd.insert(transform);
 
             cmd.id()
         };