Add despawn_children (#2903)

Adds a convenience method for despawning all the children of the entity, but not the entity itself.

crates/bevy_transform/src/hierarchy/hierarchy.rs

@@ -11,6 +11,11 @@ pub struct DespawnRecursive {
     entity: Entity,
 }
 
+#[derive(Debug)]
+pub struct DespawnChildrenRecursive {
+    entity: Entity,
+}
+
 pub fn despawn_with_children_recursive(world: &mut World, entity: Entity) {
     // first, make the entity's own parent forget about it
     if let Some(parent) = world.get::<Parent>(entity).map(|parent| parent.0) {
@@ -36,15 +41,32 @@ fn despawn_with_children_recursive_inner(world: &mut World, entity: Entity) {
     }
 }
 
+fn despawn_children(world: &mut World, entity: Entity) {
+    if let Some(mut children) = world.get_mut::<Children>(entity) {
+        for e in std::mem::take(&mut children.0) {
+            despawn_with_children_recursive_inner(world, e);
+        }
+    }
+}
+
 impl Command for DespawnRecursive {
     fn write(self, world: &mut World) {
         despawn_with_children_recursive(world, self.entity);
     }
 }
 
+impl Command for DespawnChildrenRecursive {
+    fn write(self, world: &mut World) {
+        despawn_children(world, self.entity);
+    }
+}
+
 pub trait DespawnRecursiveExt {
-    /// Despawns the provided entity and its children.
+    /// Despawns the provided entity alongside all descendants.
     fn despawn_recursive(self);
+
+    /// Despawns all descendants of the given entity.
+    fn despawn_descendants(&mut self);
 }
 
 impl<'w, 's, 'a> DespawnRecursiveExt for EntityCommands<'w, 's, 'a> {
@@ -53,6 +75,11 @@ impl<'w, 's, 'a> DespawnRecursiveExt for EntityCommands<'w, 's, 'a> {
         let entity = self.id();
         self.commands().add(DespawnRecursive { entity });
     }
+
+    fn despawn_descendants(&mut self) {
+        let entity = self.id();
+        self.commands().add(DespawnChildrenRecursive { entity });
+    }
 }
 
 impl<'w> DespawnRecursiveExt for EntityMut<'w> {
@@ -65,6 +92,15 @@ impl<'w> DespawnRecursiveExt for EntityMut<'w> {
             despawn_with_children_recursive(self.world_mut(), entity);
         }
     }
+
+    fn despawn_descendants(&mut self) {
+        let entity = self.id();
+        // SAFE: The location is updated.
+        unsafe {
+            despawn_children(self.world_mut(), entity);
+            self.update_location();
+        }
+    }
 }
 
 #[cfg(test)]