diff --git a/crates/bevy_ecs/src/system/commands/mod.rs b/crates/bevy_ecs/src/system/commands/mod.rs index 5f081804da5575..b6fce6f2df9517 100644 --- a/crates/bevy_ecs/src/system/commands/mod.rs +++ b/crates/bevy_ecs/src/system/commands/mod.rs @@ -860,6 +860,12 @@ impl<'w, 's, 'a> EntityCommands<'w, 's, 'a> { /// /// See [`World::despawn`] for more details. /// + /// # Note + /// + /// This won't clean up external references to the entity, which will leave the + /// hierarchy in an invalid state if the entity has a parent or any children. You can use + /// `despawn_recursive` or `despawn_descendants` instead to preserve the hierarchy. + /// /// # Panics /// /// The command will panic when applied if the associated entity does not exist. @@ -1062,6 +1068,12 @@ where /// A [`Command`] that despawns a specific entity. /// This will emit a warning if the entity does not exist. +/// +/// # Note +/// +/// This won't clean up external references to the entity, which will leave the +/// hierarchy in an invalid state if the entity has a parent or any children. You can use +/// `DespawnRecursive` or `DespawnDescendants` instead to preserve the hierarchy. #[derive(Debug)] pub struct Despawn { /// The entity that will be despawned. diff --git a/crates/bevy_ecs/src/world/mod.rs b/crates/bevy_ecs/src/world/mod.rs index 397f38bc795f37..d335aff17818e3 100644 --- a/crates/bevy_ecs/src/world/mod.rs +++ b/crates/bevy_ecs/src/world/mod.rs @@ -852,6 +852,12 @@ impl World { /// Despawns the given `entity`, if it exists. This will also remove all of the entity's /// [`Component`]s. Returns `true` if the `entity` is successfully despawned and `false` if /// the `entity` does not exist. + /// + /// # Note + /// + /// This won't clean up external references to the entity, which will leave the + /// hierarchy in an invalid state if the entity has a parent or any children. + /// /// ``` /// use bevy_ecs::{component::Component, world::World}; ///