From 416a33e6133064a557b88e75652584da260ad292 Mon Sep 17 00:00:00 2001
From: JoJoJet <21144246+JoJoJet@users.noreply.github.com>
Date: Mon, 28 Nov 2022 13:40:10 +0000
Subject: [PATCH] Add const `Entity::PLACEHOLDER` (#6761)

# Objective

One of the use-cases for the function `Entity::from_raw` is creating placeholder entity ids, which are meant to be overwritten later. If we use a constant for this instead of `from_raw`, it is more ergonomic and self-documenting.

## Solution

Add a constant that returns an entity ID with an index of `u32::MAX` and a generation of zero. Users are instructed to overwrite this value before using it.
---
 crates/bevy_ecs/src/entity/mod.rs             | 37 ++++++++++---------
 .../bevy_hierarchy/src/components/parent.rs   |  2 +-
 crates/bevy_sprite/src/render/mod.rs          |  2 +-
 3 files changed, 21 insertions(+), 20 deletions(-)

diff --git a/crates/bevy_ecs/src/entity/mod.rs b/crates/bevy_ecs/src/entity/mod.rs
index 844885413716e..4f7d937810aee 100644
--- a/crates/bevy_ecs/src/entity/mod.rs
+++ b/crates/bevy_ecs/src/entity/mod.rs
@@ -116,21 +116,8 @@ pub enum AllocAtWithoutReplacement {
 }
 
 impl Entity {
-    /// Creates a new entity reference with the specified `index` and a generation of 0.
-    ///
-    /// # Note
-    ///
-    /// Spawning a specific `entity` value is __rarely the right choice__. Most apps should favor
-    /// [`Commands::spawn`](crate::system::Commands::spawn). This method should generally
-    /// only be used for sharing entities across apps, and only when they have a scheme
-    /// worked out to share an index space (which doesn't happen by default).
-    ///
-    /// In general, one should not try to synchronize the ECS by attempting to ensure that
-    /// `Entity` lines up between instances, but instead insert a secondary identifier as
-    /// a component.
-    ///
-    /// There are still some use cases where it might be appropriate to use this function
-    /// externally.
+    /// An entity ID with a placeholder value. This may or may not correspond to an actual entity,
+    /// and should be overwritten by a new value before being used.
     ///
     /// ## Examples
     ///
@@ -138,8 +125,8 @@ impl Entity {
     ///
     /// ```no_run
     /// # use bevy_ecs::prelude::*;
-    /// // Create a new array of size 10 and initialize it with (invalid) entities.
-    /// let mut entities: [Entity; 10] = [Entity::from_raw(0); 10];
+    /// // Create a new array of size 10 filled with invalid entity ids.
+    /// let mut entities: [Entity; 10] = [Entity::PLACEHOLDER; 10];
     ///
     /// // ... replace the entities with valid ones.
     /// ```
@@ -158,11 +145,25 @@ impl Entity {
     /// impl FromWorld for MyStruct {
     ///     fn from_world(_world: &mut World) -> Self {
     ///         Self {
-    ///             entity: Entity::from_raw(u32::MAX),
+    ///             entity: Entity::PLACEHOLDER,
     ///         }
     ///     }
     /// }
     /// ```
+    pub const PLACEHOLDER: Self = Self::from_raw(u32::MAX);
+
+    /// Creates a new entity ID with the specified `index` and a generation of 0.
+    ///
+    /// # Note
+    ///
+    /// Spawning a specific `entity` value is __rarely the right choice__. Most apps should favor
+    /// [`Commands::spawn`](crate::system::Commands::spawn). This method should generally
+    /// only be used for sharing entities across apps, and only when they have a scheme
+    /// worked out to share an index space (which doesn't happen by default).
+    ///
+    /// In general, one should not try to synchronize the ECS by attempting to ensure that
+    /// `Entity` lines up between instances, but instead insert a secondary identifier as
+    /// a component.
     pub const fn from_raw(index: u32) -> Entity {
         Entity {
             index,
diff --git a/crates/bevy_hierarchy/src/components/parent.rs b/crates/bevy_hierarchy/src/components/parent.rs
index d22fa67d3fce7..3e573be5a6952 100644
--- a/crates/bevy_hierarchy/src/components/parent.rs
+++ b/crates/bevy_hierarchy/src/components/parent.rs
@@ -31,7 +31,7 @@ impl Parent {
 // better ways to handle cases like this.
 impl FromWorld for Parent {
     fn from_world(_world: &mut World) -> Self {
-        Parent(Entity::from_raw(u32::MAX))
+        Parent(Entity::PLACEHOLDER)
     }
 }
 
diff --git a/crates/bevy_sprite/src/render/mod.rs b/crates/bevy_sprite/src/render/mod.rs
index d99fdc8d4d98c..faea10d86ee0a 100644
--- a/crates/bevy_sprite/src/render/mod.rs
+++ b/crates/bevy_sprite/src/render/mod.rs
@@ -543,7 +543,7 @@ pub fn queue_sprites(
                 image_handle_id: HandleId::Id(Uuid::nil(), u64::MAX),
                 colored: false,
             };
-            let mut current_batch_entity = Entity::from_raw(u32::MAX);
+            let mut current_batch_entity = Entity::PLACEHOLDER;
             let mut current_image_size = Vec2::ZERO;
             // Add a phase item for each sprite, and detect when succesive items can be batched.
             // Spawn an entity with a `SpriteBatch` component for each possible batch.