From 40c02d3ad346d262450afe72955ed7285dd8f907 Mon Sep 17 00:00:00 2001
From: David Taralla <davidtaralla@gmail.com>
Date: Sat, 5 Mar 2022 13:40:25 -0500
Subject: [PATCH 1/8] Parenting example could feature the base case where
 parent is "empty"

For new users (me included!) coming from engines like Unity, it's easy to not be aware that a parent must also have a GlobalTransform along the obvious Transform.
They then ask themselves why their hierarchy doesn't work properly when using a single Transform instead of a PbrBundle.
---
 examples/3d/parenting.rs | 35 ++++++++++++++++++++++++++++++-----
 1 file changed, 30 insertions(+), 5 deletions(-)

diff --git a/examples/3d/parenting.rs b/examples/3d/parenting.rs
index 8601e98f616b1..17b1b0b2b7fb0 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -1,7 +1,8 @@
 use bevy::prelude::*;
 
 /// This example illustrates how to create parent->child relationships between entities how parent
-/// transforms are propagated to their descendants
+/// transforms are propagated to their descendants.
+/// Any entity with a Transform _and_ a GlobalTransform can be a parent.
 fn main() {
     App::new()
         .insert_resource(Msaa { samples: 4 })
@@ -11,18 +12,20 @@ fn main() {
         .run();
 }
 
-/// this component indicates what entities should rotate
+/// This component indicates what entities should rotate.
 #[derive(Component)]
 struct Rotator;
 
-/// rotates the parent, which will result in the child also rotating
+/// Rotates the parent, which will result in the child also rotating.
 fn rotator_system(time: Res<Time>, mut query: Query<&mut Transform, With<Rotator>>) {
     for mut transform in query.iter_mut() {
         transform.rotation *= Quat::from_rotation_x(3.0 * time.delta_seconds());
     }
 }
 
-/// set up a simple scene with a "parent" cube and a "child" cube
+/// Set up a simple scene with two hierarchies:
+/// - a "parent" cube and a "child" cube
+/// - a "parent" empty (= invisible entity, just a transform) and a "child" capsule
 fn setup(
     mut commands: Commands,
     mut meshes: ResMut<Assets<Mesh>>,
@@ -34,12 +37,18 @@ fn setup(
         ..default()
     });
 
+    let capsule_handle = meshes.add(Mesh::from(shape::Capsule::default()));
+    let capsule_material_handle = materials.add(StandardMaterial {
+        base_color: Color::rgb(0.7, 0.8, 0.6),
+        ..default()
+    });
+
     // parent cube
     commands
         .spawn_bundle(PbrBundle {
             mesh: cube_handle.clone(),
             material: cube_material_handle.clone(),
-            transform: Transform::from_xyz(0.0, 0.0, 1.0),
+            transform: Transform::from_xyz(-2.0, 0.0, 1.0),
             ..default()
         })
         .insert(Rotator)
@@ -52,6 +61,22 @@ fn setup(
                 ..default()
             });
         });
+    // parent "empty"
+    commands
+        .spawn_bundle((
+            Transform::from_xyz(2.0, 0.0, 1.0),
+            GlobalTransform::default(),
+        ))
+        .insert(Rotator)
+        .with_children(|parent| {
+            // child capsule
+            parent.spawn_bundle(PbrBundle {
+                mesh: capsule_handle,
+                material: capsule_material_handle,
+                transform: Transform::from_xyz(0.0, 0.0, 3.0),
+                ..default()
+            });
+        });
     // light
     commands.spawn_bundle(PointLightBundle {
         transform: Transform::from_xyz(4.0, 5.0, -4.0),

From 7e9c397c0944fd0c0946dfc11ceecfcfe0e28801 Mon Sep 17 00:00:00 2001
From: David Taralla <davidtaralla@gmail.com>
Date: Sat, 5 Mar 2022 13:56:41 -0500
Subject: [PATCH 2/8] Fix comment style

---
 examples/3d/parenting.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/3d/parenting.rs b/examples/3d/parenting.rs
index 17b1b0b2b7fb0..2d5d0ea254134 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -2,7 +2,7 @@ use bevy::prelude::*;
 
 /// This example illustrates how to create parent->child relationships between entities how parent
 /// transforms are propagated to their descendants.
-/// Any entity with a Transform _and_ a GlobalTransform can be a parent.
+/// Any entity with a `Transform` _and_ a `GlobalTransform` can be a parent.
 fn main() {
     App::new()
         .insert_resource(Msaa { samples: 4 })

From 927c6a5ebd59824d0a659b313be62000cedd4cea Mon Sep 17 00:00:00 2001
From: David Taralla <davidtaralla@gmail.com>
Date: Sat, 5 Mar 2022 13:57:07 -0500
Subject: [PATCH 3/8] Use the new TransformBundle instead of an anonymous one

---
 examples/3d/parenting.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/examples/3d/parenting.rs b/examples/3d/parenting.rs
index 2d5d0ea254134..406582b3a5527 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -63,10 +63,10 @@ fn setup(
         });
     // parent "empty"
     commands
-        .spawn_bundle((
-            Transform::from_xyz(2.0, 0.0, 1.0),
-            GlobalTransform::default(),
-        ))
+        .spawn_bundle(TransformBundle {
+            local: Transform::from_xyz(2.0, 0.0, 1.0),
+            global: GlobalTransform::default()
+        })
         .insert(Rotator)
         .with_children(|parent| {
             // child capsule

From 4610d08f0e61c1d125c9ca01ae99b74583915fb2 Mon Sep 17 00:00:00 2001
From: David Taralla <davidtaralla@gmail.com>
Date: Sat, 5 Mar 2022 14:07:34 -0500
Subject: [PATCH 4/8] Run rustfmt

---
 examples/3d/parenting.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/3d/parenting.rs b/examples/3d/parenting.rs
index 406582b3a5527..c23049549d598 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -65,7 +65,7 @@ fn setup(
     commands
         .spawn_bundle(TransformBundle {
             local: Transform::from_xyz(2.0, 0.0, 1.0),
-            global: GlobalTransform::default()
+            global: GlobalTransform::default(),
         })
         .insert(Rotator)
         .with_children(|parent| {

From c74cdc80117bad2ba40f78ce3dd9486592895d79 Mon Sep 17 00:00:00 2001
From: David Taralla <davidtaralla@gmail.com>
Date: Sat, 5 Mar 2022 14:49:37 -0500
Subject: [PATCH 5/8] Simplify code unrelated to parenting

Remove distinct material for capsule and use simpler Color for material
---
 examples/3d/parenting.rs | 15 +++++----------
 1 file changed, 5 insertions(+), 10 deletions(-)

diff --git a/examples/3d/parenting.rs b/examples/3d/parenting.rs
index c23049549d598..15237d700b001 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -32,14 +32,9 @@ fn setup(
     mut materials: ResMut<Assets<StandardMaterial>>,
 ) {
     let cube_handle = meshes.add(Mesh::from(shape::Cube { size: 2.0 }));
-    let cube_material_handle = materials.add(StandardMaterial {
-        base_color: Color::rgb(0.8, 0.7, 0.6),
-        ..default()
-    });
-
     let capsule_handle = meshes.add(Mesh::from(shape::Capsule::default()));
-    let capsule_material_handle = materials.add(StandardMaterial {
-        base_color: Color::rgb(0.7, 0.8, 0.6),
+    let material_handle = materials.add(StandardMaterial {
+        base_color: Color::BISQUE,
         ..default()
     });
 
@@ -47,7 +42,7 @@ fn setup(
     commands
         .spawn_bundle(PbrBundle {
             mesh: cube_handle.clone(),
-            material: cube_material_handle.clone(),
+            material: material_handle.clone(),
             transform: Transform::from_xyz(-2.0, 0.0, 1.0),
             ..default()
         })
@@ -56,7 +51,7 @@ fn setup(
             // child cube
             parent.spawn_bundle(PbrBundle {
                 mesh: cube_handle,
-                material: cube_material_handle,
+                material: material_handle.clone(),
                 transform: Transform::from_xyz(0.0, 0.0, 3.0),
                 ..default()
             });
@@ -72,7 +67,7 @@ fn setup(
             // child capsule
             parent.spawn_bundle(PbrBundle {
                 mesh: capsule_handle,
-                material: capsule_material_handle,
+                material: material_handle,
                 transform: Transform::from_xyz(0.0, 0.0, 3.0),
                 ..default()
             });

From 637d7d8d2a46df32ad9b82674230c36cc117f519 Mon Sep 17 00:00:00 2001
From: David Taralla <davidtaralla@gmail.com>
Date: Sat, 5 Mar 2022 14:56:06 -0500
Subject: [PATCH 6/8] Clarify comments

Remove notion of "empty"
---
 examples/3d/parenting.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/3d/parenting.rs b/examples/3d/parenting.rs
index 15237d700b001..46db43c88d3b2 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -25,7 +25,7 @@ fn rotator_system(time: Res<Time>, mut query: Query<&mut Transform, With<Rotator
 
 /// Set up a simple scene with two hierarchies:
 /// - a "parent" cube and a "child" cube
-/// - a "parent" empty (= invisible entity, just a transform) and a "child" capsule
+/// - an invisible "parent" (that has a transform, but not a mesh) and a "child" capsule
 fn setup(
     mut commands: Commands,
     mut meshes: ResMut<Assets<Mesh>>,
@@ -56,7 +56,7 @@ fn setup(
                 ..default()
             });
         });
-    // parent "empty"
+    // invisible parent
     commands
         .spawn_bundle(TransformBundle {
             local: Transform::from_xyz(2.0, 0.0, 1.0),

From a731a62904e2d8a68bfe8cbb032f55b18baaac6d Mon Sep 17 00:00:00 2001
From: David Taralla <davidtaralla@gmail.com>
Date: Sat, 5 Mar 2022 15:18:03 -0500
Subject: [PATCH 7/8] Reword rules of transform inheritance

Make it more future-proof.

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
---
 examples/3d/parenting.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/3d/parenting.rs b/examples/3d/parenting.rs
index 46db43c88d3b2..519fc8783da2a 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -2,7 +2,7 @@ use bevy::prelude::*;
 
 /// This example illustrates how to create parent->child relationships between entities how parent
 /// transforms are propagated to their descendants.
-/// Any entity with a `Transform` _and_ a `GlobalTransform` can be a parent.
+///  `Transform` can be inherited from any entity with both the `Transform` and `GlobalTransform` components.
 fn main() {
     App::new()
         .insert_resource(Msaa { samples: 4 })

From e5f5f6a83829cdb4e0376d29ff6386c27543ca30 Mon Sep 17 00:00:00 2001
From: David Taralla <davidtaralla@gmail.com>
Date: Sat, 5 Mar 2022 15:35:59 -0500
Subject: [PATCH 8/8] Fix comment style
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: François <mockersf@gmail.com>
---
 examples/3d/parenting.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/3d/parenting.rs b/examples/3d/parenting.rs
index 519fc8783da2a..e6f868596cb7f 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -2,7 +2,7 @@ use bevy::prelude::*;
 
 /// This example illustrates how to create parent->child relationships between entities how parent
 /// transforms are propagated to their descendants.
-///  `Transform` can be inherited from any entity with both the `Transform` and `GlobalTransform` components.
+/// `Transform` can be inherited from any entity with both the `Transform` and `GlobalTransform` components.
 fn main() {
     App::new()
         .insert_resource(Msaa { samples: 4 })