From 9c8576996fef5d20debb857afd7e8b1ad790d5a9 Mon Sep 17 00:00:00 2001 From: Ben Frankel Date: Tue, 12 Dec 2023 11:44:05 -0800 Subject: [PATCH] Add a doc note about despawn footgun (#10889) # Objective The `Despawn` command breaks the hierarchy whenever you use it if the despawned entity has a parent or any children. This is a serious footgun because the `Despawn` command has the shortest name, the behavior is unexpected and not likely to be what you want, and the crash that it causes can be very difficult to track down. ## Solution Until this can be fixed by relations, add a note mentioning the footgun in the documentation. --- crates/bevy_ecs/src/system/commands/mod.rs | 10 ++++++++++ crates/bevy_ecs/src/world/mod.rs | 6 ++++++ 2 files changed, 16 insertions(+) diff --git a/crates/bevy_ecs/src/system/commands/mod.rs b/crates/bevy_ecs/src/system/commands/mod.rs index 7b0638103e..abcbfab0f3 100644 --- a/crates/bevy_ecs/src/system/commands/mod.rs +++ b/crates/bevy_ecs/src/system/commands/mod.rs @@ -857,6 +857,11 @@ 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 (such as parent-child relationships + /// if you're using `bevy_hierarchy`), which may leave the world in an invalid state. + /// /// # Panics /// /// The command will panic when applied if the associated entity does not exist. @@ -1056,6 +1061,11 @@ 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 (such as parent-child relationships +/// if you're using `bevy_hierarchy`), which may leave the world in an invalid state. #[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 397f38bc79..2f39483cd3 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 (such as parent-child relationships + /// if you're using `bevy_hierarchy`), which may leave the world in an invalid state. + /// /// ``` /// use bevy_ecs::{component::Component, world::World}; ///