From dd92a7705d8da02f14575114a2a145ccae3afbd8 Mon Sep 17 00:00:00 2001
From: TheBigCheese <32036861+13ros27@users.noreply.github.com>
Date: Mon, 30 Sep 2024 18:23:52 +0100
Subject: [PATCH] Small addition to `World::flush_commands` explaining how
 `spawn` will cause it to panic. (#15411)

# Objective
`World::flush_commands` will cause a panic with `error[B0003]: Could not
insert a bundle [...] for entity [...] because it doesn't exist in this
World` if there was a `spawn` command in the queue and you should
instead use `flush` for this but this isn't mentioned in the docs

## Solution
Add a note to the docs suggesting to use `World::flush` in this context.
This error doesn't appear to happen with `spawn_batch` so I didn't add
that to the note although you can cause it with
`commands.spawn_empty().insert(...)` but I wasn't sure that was worth
the documentation complexity as it is pretty unlikely (and equivalent to
`commands.spawn(...)`.
---
 crates/bevy_ecs/src/world/mod.rs | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/crates/bevy_ecs/src/world/mod.rs b/crates/bevy_ecs/src/world/mod.rs
index 3867905685..15e4c61464 100644
--- a/crates/bevy_ecs/src/world/mod.rs
+++ b/crates/bevy_ecs/src/world/mod.rs
@@ -2226,6 +2226,9 @@ impl World {
 
     /// Applies any commands in the world's internal [`CommandQueue`].
     /// This does not apply commands from any systems, only those stored in the world.
+    ///
+    /// This will panic if any of the queued commands are [`spawn`](Commands::spawn).
+    /// If this is possible, you should instead use [`flush`](Self::flush).
     pub fn flush_commands(&mut self) {
         // SAFETY: `self.command_queue` is only de-allocated in `World`'s `Drop`
         if !unsafe { self.command_queue.is_empty() } {