Add TransformBundle

crates/bevy_gltf/src/loader.rs

@@ -20,7 +20,8 @@ use bevy_render::{
 use bevy_scene::Scene;
 use bevy_transform::{
     hierarchy::{BuildWorldChildren, WorldChildBuilder},
-    prelude::{GlobalTransform, Transform},
+    prelude::Transform,
+    TransformBundle,
 };
 use gltf::{
     mesh::Mode,
@@ -280,7 +281,7 @@ async fn load_gltf<'a, 'b>(
         let mut world = World::default();
         world
             .spawn()
-            .insert_bundle((Transform::identity(), GlobalTransform::identity()))
+            .insert_bundle(TransformBundle::identity())
             .with_children(|parent| {
                 for node in scene.nodes() {
                     let result = load_node(&node, parent, load_context, &buffer_data);
@@ -450,9 +451,8 @@ fn load_node(
 ) -> Result<(), GltfError> {
     let transform = gltf_node.transform();
     let mut gltf_error = None;
-    let mut node = world_builder.spawn_bundle((
+    let mut node = world_builder.spawn_bundle(TransformBundle::from_transform(
         Transform::from_matrix(Mat4::from_cols_array_2d(&transform.matrix())),
-        GlobalTransform::identity(),
     ));
 
     if let Some(name) = gltf_node.name() {

crates/bevy_transform/src/components/global_transform.rs

@@ -7,8 +7,9 @@ use std::ops::Mul;
 /// Describe the position of an entity relative to the reference frame.
 ///
 /// * To place or move an entity, you should set its [`Transform`].
-/// * To be displayed, an entity must have both a [`Transform`] and a [`GlobalTransform`].
 /// * To get the global position 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`] to guarantee this.
 ///
 /// ## [`Transform`] and [`GlobalTransform`]
 ///
@@ -20,16 +21,6 @@ use std::ops::Mul;
 /// [`GlobalTransform`] is updated from [`Transform`] in the system
 /// [`transform_propagate_system`](crate::transform_propagate_system::transform_propagate_system).
 ///
-/// In pseudo code:
-/// ```ignore
-/// for entity in entities_without_parent:
-///     set entity.global_transform to entity.transform
-///     recursively:
-///         set parent to current entity
-///         for child in parent.children:
-///             set child.global_transform to parent.global_transform * child.transform
-/// ```
-///
 /// This system runs in stage [`CoreStage::PostUpdate`](crate::CoreStage::PostUpdate). If you
 /// update the[`Transform`] of an entity in this stage or after, you will notice a 1 frame lag
 /// before the [`GlobalTransform`] is updated.

crates/bevy_transform/src/components/transform.rs

@@ -8,8 +8,9 @@ use std::ops::Mul;
 /// to its parent position.
 ///
 /// * To place or move an entity, you should set its [`Transform`].
-/// * To be displayed, an entity must have both a [`Transform`] and a [`GlobalTransform`].
 /// * To get the global position 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`] to guarantee this.
 ///
 /// ## [`Transform`] and [`GlobalTransform`]
 ///
@@ -21,16 +22,6 @@ use std::ops::Mul;
 /// [`GlobalTransform`] is updated from [`Transform`] in the system
 /// [`transform_propagate_system`](crate::transform_propagate_system::transform_propagate_system).
 ///
-/// In pseudo code:
-/// ```ignore
-/// for entity in entities_without_parent:
-///     set entity.global_transform to entity.transform
-///     recursively:
-///         set parent to current entity
-///         for child in parent.children:
-///             set child.global_transform to parent.global_transform * child.transform
-/// ```
-///
 /// This system runs in stage [`CoreStage::PostUpdate`](crate::CoreStage::PostUpdate). If you
 /// update the[`Transform`] of an entity in this stage or after, you will notice a 1 frame lag
 /// before the [`GlobalTransform`] is updated.

crates/bevy_transform/src/lib.rs

@@ -4,13 +4,73 @@ pub mod transform_propagate_system;
 
 pub mod prelude {
     #[doc(hidden)]
-    pub use crate::{components::*, hierarchy::*, TransformPlugin};
+    pub use crate::{components::*, hierarchy::*, TransformBundle, TransformPlugin};
 }
 
 use bevy_app::prelude::*;
-use bevy_ecs::schedule::{ParallelSystemDescriptorCoercion, SystemLabel};
+use bevy_ecs::{
+    bundle::Bundle,
+    schedule::{ParallelSystemDescriptorCoercion, SystemLabel},
+};
 use prelude::{parent_update_system, Children, GlobalTransform, Parent, PreviousParent, Transform};
 
+/// A [`Bundle`] of the [`Transform`] and [`GlobalTransform`]
+/// [`Component`](bevy_ecs::component::Component)s, which describe the position of an entity.
+///
+/// * To place or move an entity, you should set its [`Transform`].
+/// * To get the global position 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`] to guarantee this.
+///
+/// ## [`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`](Parent).
+///
+/// [`GlobalTransform`] is the position of an entity relative to the reference frame.
+///
+/// [`GlobalTransform`] is updated from [`Transform`] in the system
+/// [`transform_propagate_system`](crate::transform_propagate_system::transform_propagate_system).
+///
+/// This system runs in stage [`CoreStage::PostUpdate`](crate::CoreStage::PostUpdate). If you
+/// update the[`Transform`] of an entity in this stage or after, you will notice a 1 frame lag
+/// before the [`GlobalTransform`] is updated.
+#[derive(Default, Bundle, Clone, Debug)]
+pub struct TransformBundle {
+    pub local: Transform,
+    pub global: GlobalTransform,
+}
+
+impl TransformBundle {
+    /// Creates a new [`TransformBundle`] from a [`Transform`] and leaving [`GlobalTransform`] with
+    /// no translation, rotation, and a scale of 1 on all axes.
+    #[inline]
+    pub const fn from_transform(transform: Transform) -> Self {
+        TransformBundle {
+            local: transform,
+            // Note: `..Default::default()` cannot be used here, because it isn't const
+            ..Self::identity()
+        }
+    }
+
+    /// Creates a new identity [`TransformBundle`], with no translation, rotation, and a scale of 1
+    /// on all axes.
+    #[inline]
+    pub const fn identity() -> Self {
+        TransformBundle {
+            local: Transform::identity(),
+            global: GlobalTransform::identity(),
+        }
+    }
+}
+
+impl From<Transform> for TransformBundle {
+    #[inline]
+    fn from(transform: Transform) -> Self {
+        Self::from_transform(transform)
+    }
+}
+
 #[derive(Default)]
 pub struct TransformPlugin;
 

crates/bevy_transform/src/transform_propagate_system.rs

@@ -82,7 +82,10 @@ mod test {
     };
 
     use super::*;
-    use crate::hierarchy::{parent_update_system, BuildChildren, BuildWorldChildren};
+    use crate::{
+        hierarchy::{parent_update_system, BuildChildren, BuildWorldChildren},
+        TransformBundle,
+    };
 
     #[test]
     fn did_propagate() {
@@ -96,33 +99,31 @@ mod test {
         schedule.add_stage("update", update_stage);
 
         // Root entity
-        world.spawn().insert_bundle((
-            Transform::from_xyz(1.0, 0.0, 0.0),
-            GlobalTransform::identity(),
-        ));
+        world
+            .spawn()
+            .insert_bundle(TransformBundle::from_transform(Transform::from_xyz(
+                1.0, 0.0, 0.0,
+            )));
 
         let mut children = Vec::new();
         world
             .spawn()
-            .insert_bundle((
-                Transform::from_xyz(1.0, 0.0, 0.0),
-                GlobalTransform::identity(),
-            ))
+            .insert_bundle(TransformBundle::from_transform(Transform::from_xyz(
+                1.0, 0.0, 0.0,
+            )))
             .with_children(|parent| {
                 children.push(
                     parent
-                        .spawn_bundle((
-                            Transform::from_xyz(0.0, 2.0, 0.),
-                            GlobalTransform::identity(),
-                        ))
+                        .spawn_bundle(TransformBundle::from_transform(Transform::from_xyz(
+                            0.0, 2.0, 0.,
+                        )))
                         .id(),
                 );
                 children.push(
                     parent
-                        .spawn_bundle((
-                            Transform::from_xyz(0.0, 0.0, 3.),
-                            GlobalTransform::identity(),
-                        ))
+                        .spawn_bundle(TransformBundle::from_transform(Transform::from_xyz(
+                            0.0, 0.0, 3.,
+                        )))
                         .id(),
                 );
             });
@@ -155,25 +156,22 @@ mod test {
         let mut commands = Commands::new(&mut queue, &world);
         let mut children = Vec::new();
         commands
-            .spawn_bundle((
-                Transform::from_xyz(1.0, 0.0, 0.0),
-                GlobalTransform::identity(),
-            ))
+            .spawn_bundle(TransformBundle::from_transform(Transform::from_xyz(
+                1.0, 0.0, 0.0,
+            )))
             .with_children(|parent| {
                 children.push(
                     parent
-                        .spawn_bundle((
-                            Transform::from_xyz(0.0, 2.0, 0.0),
-                            GlobalTransform::identity(),
-                        ))
+                        .spawn_bundle(TransformBundle::from_transform(Transform::from_xyz(
+                            0.0, 2.0, 0.0,
+                        )))
                         .id(),
                 );
                 children.push(
                     parent
-                        .spawn_bundle((
-                            Transform::from_xyz(0.0, 0.0, 3.0),
-                            GlobalTransform::identity(),
-                        ))
+                        .spawn_bundle(TransformBundle::from_transform(Transform::from_xyz(
+                            0.0, 0.0, 3.0,
+                        )))
                         .id(),
                 );
             });

examples/3d/pbr.rs

@@ -55,7 +55,7 @@ fn setup(
     });
     // light
     commands.spawn_bundle(PointLightBundle {
-        transform: Transform::from_translation(Vec3::new(50.0, 50.0, 50.0)),
+        transform: Transform::from_xyz(50.0, 50.0, 50.0),
         point_light: PointLight {
             intensity: 50000.,
             range: 100.,
@@ -65,8 +65,7 @@ fn setup(
     });
     // camera
     commands.spawn_bundle(OrthographicCameraBundle {
-        transform: Transform::from_translation(Vec3::new(0.0, 0.0, 8.0))
-            .looking_at(Vec3::default(), Vec3::Y),
+        transform: Transform::from_xyz(0.0, 0.0, 8.0).looking_at(Vec3::default(), Vec3::Y),
         orthographic_projection: bevy::render::camera::OrthographicProjection {
             scale: 0.01,
             ..Default::default()

examples/3d/render_to_texture.rs

@@ -154,7 +154,7 @@ fn setup(
         .spawn_bundle(PbrBundle {
             mesh: cube_handle,
             material: cube_material_handle,
-            transform: Transform::from_translation(Vec3::new(0.0, 0.0, 1.0)),
+            transform: Transform::from_xyz(0.0, 0.0, 1.0),
             ..Default::default()
         })
         .insert(FirstPassCube)
@@ -164,7 +164,7 @@ fn setup(
     // light
     // note: currently lights are shared between passes!
     commands.spawn_bundle(PointLightBundle {
-        transform: Transform::from_translation(Vec3::new(0.0, 0.0, 10.0)),
+        transform: Transform::from_xyz(0.0, 0.0, 10.0),
         ..Default::default()
     });
 
@@ -176,8 +176,7 @@ fn setup(
                                       * calculation of projection matrix */
             ..Default::default()
         },
-        transform: Transform::from_translation(Vec3::new(0.0, 0.0, 15.0))
-            .looking_at(Vec3::default(), Vec3::Y),
+        transform: Transform::from_xyz(0.0, 0.0, 15.0).looking_at(Vec3::default(), Vec3::Y),
         ..Default::default()
     };
     active_cameras.add(FIRST_PASS_CAMERA);
@@ -220,8 +219,7 @@ fn setup(
         .insert(MainPassCube);
 
     commands.spawn_bundle(PerspectiveCameraBundle {
-        transform: Transform::from_translation(Vec3::new(0.0, 0.0, 15.0))
-            .looking_at(Vec3::default(), Vec3::Y),
+        transform: Transform::from_xyz(0.0, 0.0, 15.0).looking_at(Vec3::default(), Vec3::Y),
         ..Default::default()
     });
 }

examples/3d/update_gltf_scene.rs

@@ -38,10 +38,9 @@ fn setup(
     // Spawn the scene as a child of another entity. This first scene will be translated backward
     // with its parent
     commands
-        .spawn_bundle((
-            Transform::from_xyz(0.0, 0.0, -1.0),
-            GlobalTransform::identity(),
-        ))
+        .spawn_bundle(TransformBundle::from_transform(Transform::from_xyz(
+            0.0, 0.0, -1.0,
+        )))
         .with_children(|parent| {
             parent.spawn_scene(asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0"));
         });

examples/async_tasks/async_compute.rs

@@ -60,7 +60,7 @@ fn spawn_tasks(mut commands: Commands, thread_pool: Res<AsyncComputeTaskPool>) {
                     }
 
                     // Such hard work, all done!
-                    Transform::from_translation(Vec3::new(x as f32, y as f32, z as f32))
+                    Transform::from_xyz(x as f32, y as f32, z as f32)
                 });
 
                 // Spawn new entity and add our new task as a component
@@ -107,13 +107,13 @@ fn setup_env(mut commands: Commands) {
 
     // lights
     commands.spawn_bundle(PointLightBundle {
-        transform: Transform::from_translation(Vec3::new(4.0, 12.0, 15.0)),
+        transform: Transform::from_xyz(4.0, 12.0, 15.0),
         ..Default::default()
     });
 
     // camera
     commands.spawn_bundle(PerspectiveCameraBundle {
-        transform: Transform::from_translation(Vec3::new(offset, offset, 15.0))
+        transform: Transform::from_xyz(offset, offset, 15.0)
             .looking_at(Vec3::new(offset, offset, 0.0), Vec3::Y),
         ..Default::default()
     });

examples/ecs/iter_combinations.rs

@@ -104,10 +104,7 @@ fn generate_bodies(
     commands
         .spawn_bundle(BodyBundle {
             pbr: PbrBundle {
-                transform: Transform {
-                    scale: Vec3::splat(0.5),
-                    ..Default::default()
-                },
+                transform: Transform::from_scale(Vec3::splat(0.5)),
                 mesh: meshes.add(Mesh::from(shape::Icosphere {
                     radius: 1.0,
                     subdivisions: 5,