From c9e32858d7d33a1b4eda84a42598429bae637611 Mon Sep 17 00:00:00 2001
From: Rob Parrett <robparrett@gmail.com>
Date: Mon, 11 Mar 2024 11:16:13 -0700
Subject: [PATCH] Fix leftover references to children when despawning audio
 entities (#12407)

# Objective

Fixes #12402

## Solution

Use `despawn_recursive` instead of `despawn` for despawning
`PlaybackMode::Despawn` audio.

## Migration Guide

`PlaybackSettings::DESPAWN` (`PlaybackMode::Despawn`) now despawns the
audio entity's children as well. If you were relying on the previous
behavior, you may be able to use `PlaybackMode::Remove`, or you may need
to use `PlaybackMode::Once` and manage your audio component lifecycle
manually.
---
 crates/bevy_audio/Cargo.toml          | 1 +
 crates/bevy_audio/src/audio.rs        | 2 +-
 crates/bevy_audio/src/audio_output.rs | 5 +++--
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/crates/bevy_audio/Cargo.toml b/crates/bevy_audio/Cargo.toml
index 2d0e7e32890b6..3f831ce3e4a2e 100644
--- a/crates/bevy_audio/Cargo.toml
+++ b/crates/bevy_audio/Cargo.toml
@@ -13,6 +13,7 @@ keywords = ["bevy"]
 bevy_app = { path = "../bevy_app", version = "0.14.0-dev" }
 bevy_asset = { path = "../bevy_asset", version = "0.14.0-dev" }
 bevy_ecs = { path = "../bevy_ecs", version = "0.14.0-dev" }
+bevy_hierarchy = { path = "../bevy_hierarchy", version = "0.14.0-dev" }
 bevy_math = { path = "../bevy_math", version = "0.14.0-dev" }
 bevy_reflect = { path = "../bevy_reflect", version = "0.14.0-dev", features = [
   "bevy",
diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index bbddfbb689d90..cbe05b6a56887 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -37,7 +37,7 @@ pub enum PlaybackMode {
     Once,
     /// Repeat the sound forever.
     Loop,
-    /// Despawn the entity when the sound finishes playing.
+    /// Despawn the entity and its children when the sound finishes playing.
     Despawn,
     /// Remove the audio components from the entity, when the sound finishes playing.
     Remove,
diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index 75a7f6451b488..cfe344c1cebe0 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -4,6 +4,7 @@ use crate::{
 };
 use bevy_asset::{Asset, Assets, Handle};
 use bevy_ecs::{prelude::*, system::SystemParam};
+use bevy_hierarchy::DespawnRecursiveExt;
 use bevy_math::Vec3;
 use bevy_transform::prelude::GlobalTransform;
 use bevy_utils::tracing::warn;
@@ -253,12 +254,12 @@ pub(crate) fn cleanup_finished_audio<T: Decodable + Asset>(
 ) {
     for (entity, sink) in &query_nonspatial_despawn {
         if sink.sink.empty() {
-            commands.entity(entity).despawn();
+            commands.entity(entity).despawn_recursive();
         }
     }
     for (entity, sink) in &query_spatial_despawn {
         if sink.sink.empty() {
-            commands.entity(entity).despawn();
+            commands.entity(entity).despawn_recursive();
         }
     }
     for (entity, sink) in &query_nonspatial_remove {