Add EntityCommands::with_child and EntityMut::with_child (#6716)

# Objective

- Adding a single child is very cumbersome, and requires the use of a complex closure.
- Fixes #6712.

## Solution

Add a `with_child(b: impl Bundle)` API.

## Changelog

Added `EntityCommands::with_child(b: impl Bundle)`  and an equivelent method on `EntityMut`  (for direct world access).

## Migration Guide

When spawning a single child with no children of its own, consider using `commands.entity(parent).with_child(child_bundle)` to make your code clearer.

Author: alice-i-cecile

crates/bevy_hierarchy/src/child_builder.rs

@@ -252,6 +252,12 @@ impl<'w, 's, 'a> ChildBuilder<'w, 's, 'a> {
 
 /// Trait defining how to build children
 pub trait BuildChildren {
+    /// Spawns a new entity for the provided `bundle`, and adds it as a child entity to the parent.
+    ///
+    /// Returns the original reference to the parent,
+    /// which can be used to spawn siblings by calling this method repeatedly.
+    fn with_child(&mut self, bundle: impl Bundle) -> &mut Self;
+
     /// Creates a [`ChildBuilder`] with the given children built in the given closure
     ///
     /// Compared to [`add_children`][BuildChildren::add_children], this method returns self
@@ -316,6 +322,14 @@ pub trait BuildChildren {
 }
 
 impl<'w, 's, 'a> BuildChildren for EntityCommands<'w, 's, 'a> {
+    fn with_child(&mut self, bundle: impl Bundle) -> &mut Self {
+        let parent_entity = self.id();
+        self.commands().add(move |world| {
+            world.entity_mut(parent_entity).with_child(bundle);
+        });
+        self
+    }
+
     fn with_children(&mut self, spawn_children: impl FnOnce(&mut ChildBuilder)) -> &mut Self {
         self.add_children(spawn_children);
         self
@@ -436,6 +450,8 @@ impl<'w> WorldChildBuilder<'w> {
 
 /// Trait that defines adding children to an entity directly through the [`World`]
 pub trait BuildWorldChildren {
+    /// Spawns a new entity for the provided `bundle`, and adds it as a child entity to the parent
+    fn with_child(&mut self, bundle: impl Bundle) -> &mut Self;
     /// Creates a [`WorldChildBuilder`] with the given children built in the given closure
     fn with_children(&mut self, spawn_children: impl FnOnce(&mut WorldChildBuilder)) -> &mut Self;
     /// Pushes children to the back of the builder's children
@@ -447,6 +463,14 @@ pub trait BuildWorldChildren {
 }
 
 impl<'w> BuildWorldChildren for EntityMut<'w> {
+    fn with_child(&mut self, bundle: impl Bundle) -> &mut Self {
+        let parent_entity = self.id();
+        self.world_scope(|world| {
+            world.spawn(bundle).set_parent(parent_entity);
+        });
+        self
+    }
+
     fn with_children(&mut self, spawn_children: impl FnOnce(&mut WorldChildBuilder)) -> &mut Self {
         let parent = self.id();
         self.world_scope(|world| {
@@ -496,6 +520,76 @@ impl<'w> BuildWorldChildren for EntityMut<'w> {
     }
 }
 
+impl<'w> BuildWorldChildren for WorldChildBuilder<'w> {
+    fn with_child(&mut self, bundle: impl Bundle) -> &mut Self {
+        self.with_children(|world_child_builder| {
+            world_child_builder.spawn(bundle);
+        });
+        self
+    }
+
+    fn with_children(
+        &mut self,
+        spawn_children: impl FnOnce(&mut WorldChildBuilder<'w>),
+    ) -> &mut Self {
+        let current_entity = self
+            .current_entity
+            .expect("Cannot add children without a parent. Try creating an entity first.");
+        self.parent_entities.push(current_entity);
+        self.current_entity = None;
+
+        spawn_children(self);
+
+        self.current_entity = self.parent_entities.pop();
+        self
+    }
+
+    fn push_children(&mut self, children: &[Entity]) -> &mut Self {
+        let parent = self
+            .current_entity
+            .expect("Cannot add children without a parent. Try creating an entity first.");
+        update_old_parents(self.world, parent, children);
+        if let Some(mut children_component) = self.world.get_mut::<Children>(parent) {
+            children_component
+                .0
+                .retain(|value| !children.contains(value));
+            children_component.0.extend(children.iter().cloned());
+        } else {
+            self.world
+                .entity_mut(parent)
+                .insert(Children::from_entities(children));
+        }
+        self
+    }
+
+    fn insert_children(&mut self, index: usize, children: &[Entity]) -> &mut Self {
+        let parent = self
+            .current_entity
+            .expect("Cannot add children without a parent. Try creating an entity first.");
+        update_old_parents(self.world, parent, children);
+        if let Some(mut children_component) = self.world.get_mut::<Children>(parent) {
+            children_component
+                .0
+                .retain(|value| !children.contains(value));
+            children_component.0.insert_from_slice(index, children);
+        } else {
+            self.world
+                .entity_mut(parent)
+                .insert(Children::from_entities(children));
+        }
+        self
+    }
+
+    fn remove_children(&mut self, children: &[Entity]) -> &mut Self {
+        let parent = self
+            .current_entity
+            .expect("Cannot remove children without a parent. Try creating an entity first.");
+
+        remove_children(parent, children, self.world);
+        self
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::{BuildChildren, BuildWorldChildren};

errors/B0004.md

@@ -30,17 +30,15 @@ fn setup_cube(
 ) {
     commands
         .spawn(TransformBundle::default())
-        .with_children(|parent| {
-            // cube
-            parent.spawn(PbrBundle {
+        // Cube
+        .with_child(PbrBundle {
                 mesh: meshes.add(Mesh::from(shape::Cube { size: 1.0 })),
                 material: materials.add(Color::rgb(0.8, 0.7, 0.6).into()),
                 transform: Transform::from_xyz(0.0, 0.5, 0.0),
                 ..default()
             });
-        });
 
-    // camera
+    // Camera
     commands.spawn(Camera3dBundle {
         transform: Transform::from_xyz(-2.0, 2.5, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
         ..default()
@@ -77,14 +75,12 @@ fn setup_cube(
         // ComputedVisibility component needed to display the cube,
         // In addition to the Transform and GlobalTransform components.
         .spawn(SpatialBundle::default())
-        .with_children(|parent| {
-            // cube
-            parent.spawn(PbrBundle {
+        // Cube
+        .with_child(PbrBundle {
                 mesh: meshes.add(Mesh::from(shape::Cube { size: 1.0 })),
                 material: materials.add(Color::rgb(0.8, 0.7, 0.6).into()),
                 transform: Transform::from_xyz(0.0, 0.5, 0.0),
                 ..default()
-            });
         });
 
     // camera

examples/3d/lighting.rs

@@ -110,19 +110,17 @@ fn setup(
             },
             ..default()
         })
-        .with_children(|builder| {
-            builder.spawn(PbrBundle {
-                mesh: meshes.add(Mesh::from(shape::UVSphere {
-                    radius: 0.1,
-                    ..default()
-                })),
-                material: materials.add(StandardMaterial {
-                    base_color: Color::RED,
-                    emissive: Color::rgba_linear(100.0, 0.0, 0.0, 0.0),
-                    ..default()
-                }),
+        .with_child(PbrBundle {
+            mesh: meshes.add(Mesh::from(shape::UVSphere {
+                radius: 0.1,
                 ..default()
-            });
+            })),
+            material: materials.add(StandardMaterial {
+                base_color: Color::RED,
+                emissive: Color::rgba_linear(100.0, 0.0, 0.0, 0.0),
+                ..default()
+            }),
+            ..default()
         });
 
     // green spot light
@@ -140,21 +138,19 @@ fn setup(
             },
             ..default()
         })
-        .with_children(|builder| {
-            builder.spawn(PbrBundle {
-                transform: Transform::from_rotation(Quat::from_rotation_x(PI / 2.0)),
-                mesh: meshes.add(Mesh::from(shape::Capsule {
-                    depth: 0.125,
-                    radius: 0.1,
-                    ..default()
-                })),
-                material: materials.add(StandardMaterial {
-                    base_color: Color::GREEN,
-                    emissive: Color::rgba_linear(0.0, 100.0, 0.0, 0.0),
-                    ..default()
-                }),
+        .with_child(PbrBundle {
+            transform: Transform::from_rotation(Quat::from_rotation_x(PI / 2.0)),
+            mesh: meshes.add(Mesh::from(shape::Capsule {
+                depth: 0.125,
+                radius: 0.1,
+                ..default()
+            })),
+            material: materials.add(StandardMaterial {
+                base_color: Color::GREEN,
+                emissive: Color::rgba_linear(0.0, 100.0, 0.0, 0.0),
                 ..default()
-            });
+            }),
+            ..default()
         });
 
     // blue point light
@@ -170,19 +166,17 @@ fn setup(
             },
             ..default()
         })
-        .with_children(|builder| {
-            builder.spawn(PbrBundle {
-                mesh: meshes.add(Mesh::from(shape::UVSphere {
-                    radius: 0.1,
-                    ..default()
-                })),
-                material: materials.add(StandardMaterial {
-                    base_color: Color::BLUE,
-                    emissive: Color::rgba_linear(0.0, 0.0, 100.0, 0.0),
-                    ..default()
-                }),
+        .with_child(PbrBundle {
+            mesh: meshes.add(Mesh::from(shape::UVSphere {
+                radius: 0.1,
+                ..default()
+            })),
+            material: materials.add(StandardMaterial {
+                base_color: Color::BLUE,
+                emissive: Color::rgba_linear(0.0, 0.0, 100.0, 0.0),
                 ..default()
-            });
+            }),
+            ..default()
         });
 
     // directional 'sun' light

examples/3d/parenting.rs

@@ -45,14 +45,12 @@ fn setup(
             },
             Rotator,
         ))
-        .with_children(|parent| {
-            // child cube
-            parent.spawn(PbrBundle {
-                mesh: cube_handle,
-                material: cube_material_handle,
-                transform: Transform::from_xyz(0.0, 0.0, 3.0),
-                ..default()
-            });
+        // child cube
+        .with_child(PbrBundle {
+            mesh: cube_handle,
+            material: cube_material_handle,
+            transform: Transform::from_xyz(0.0, 0.0, 3.0),
+            ..default()
         });
     // light
     commands.spawn(PointLightBundle {

examples/3d/spherical_area_lights.rs

@@ -60,16 +60,14 @@ fn setup(
                     .with_scale(Vec3::splat(radius)),
                 ..default()
             })
-            .with_children(|children| {
-                children.spawn(PointLightBundle {
-                    point_light: PointLight {
-                        intensity: 1500.0,
-                        radius,
-                        color: Color::rgb(0.2, 0.2, 1.0),
-                        ..default()
-                    },
+            .with_child(PointLightBundle {
+                point_light: PointLight {
+                    intensity: 1500.0,
+                    radius,
+                    color: Color::rgb(0.2, 0.2, 1.0),
                     ..default()
-                });
+                },
+                ..default()
             });
     }
 }

examples/animation/animated_transform.rs

@@ -133,18 +133,16 @@ fn setup(
                 // Add the Name component
                 orbit_controller,
             ))
-            .with_children(|p| {
-                // The satellite, placed at a distance of the planet
-                p.spawn((
-                    PbrBundle {
-                        transform: Transform::from_xyz(1.5, 0.0, 0.0),
-                        mesh: meshes.add(Mesh::from(shape::Cube { size: 0.5 })),
-                        material: materials.add(Color::rgb(0.3, 0.9, 0.3).into()),
-                        ..default()
-                    },
-                    // Add the Name component
-                    satellite,
-                ));
-            });
+            // The satellite, placed at a distance of the planet
+            .with_child((
+                PbrBundle {
+                    transform: Transform::from_xyz(1.5, 0.0, 0.0),
+                    mesh: meshes.add(Mesh::from(shape::Cube { size: 0.5 })),
+                    material: materials.add(Color::rgb(0.3, 0.9, 0.3).into()),
+                    ..default()
+                },
+                // Add the Name component
+                satellite,
+            ));
         });
 }

examples/ecs/hierarchy.rs

@@ -23,18 +23,15 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
             texture: texture.clone(),
             ..default()
         })
-        // With that entity as a parent, run a lambda that spawns its children
-        .with_children(|parent| {
-            // parent is a ChildBuilder, which has a similar API to Commands
-            parent.spawn(SpriteBundle {
-                transform: Transform::from_xyz(250.0, 0.0, 0.0).with_scale(Vec3::splat(0.75)),
-                texture: texture.clone(),
-                sprite: Sprite {
-                    color: Color::BLUE,
-                    ..default()
-                },
+        // Add a child entity
+        .with_child(SpriteBundle {
+            transform: Transform::from_xyz(250.0, 0.0, 0.0).with_scale(Vec3::splat(0.75)),
+            texture: texture.clone(),
+            sprite: Sprite {
+                color: Color::BLUE,
                 ..default()
-            });
+            },
+            ..default()
         })
         // Store parent entity for next sections
         .id();

examples/ecs/iter_combinations.rs

@@ -136,17 +136,15 @@ fn generate_bodies(
             },
             Star,
         ))
-        .with_children(|p| {
-            p.spawn(PointLightBundle {
-                point_light: PointLight {
-                    color: Color::WHITE,
-                    intensity: 400.0,
-                    range: 100.0,
-                    radius: star_radius,
-                    ..default()
-                },
+        .with_child(PointLightBundle {
+            point_light: PointLight {
+                color: Color::WHITE,
+                intensity: 400.0,
+                range: 100.0,
+                radius: star_radius,
                 ..default()
-            });
+            },
+            ..default()
         });
     commands.spawn(Camera3dBundle {
         transform: Transform::from_xyz(0.0, 10.5, -30.0).looking_at(Vec3::ZERO, Vec3::Y),