From 6dbe3600ed7e50d48280bb2a42aaa30a5de3b095 Mon Sep 17 00:00:00 2001
From: Trashtalk217 <trashtalk217@gmail.com>
Date: Mon, 23 Jun 2025 00:48:35 +0200
Subject: [PATCH] Add `num_entities()` to World (#19780)

# Objective

There is a lot of `world.entities().len()`, especially in tests. In
tests, usually, the assumption is made that empty worlds do not contain
any entities. This is about to change (#19711), and as such all of these
tests are failing for that PR.

## Solution

`num_entities` is a convenience method that returns the number of
entities inside a world. It can later be adapted to exclude 'unexpected'
entities, associated with internal data structures such as Resources,
Queries, Systems. In general I argue for a separation of concepts where
`World` ignores internal entities in methods such as `iter_entities()`
and `clear_entities()`, that discussion is, however, separate from this
PR.

## Testing

I replaced most occurrences of `world.entities().len()` with
`world.num_entities()` and the tests passed.

---------

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
---
 crates/bevy_app/src/app.rs                 | 2 +-
 crates/bevy_ecs/src/lib.rs                 | 4 ++--
 crates/bevy_ecs/src/observer/mod.rs        | 2 +-
 crates/bevy_ecs/src/system/commands/mod.rs | 2 +-
 crates/bevy_ecs/src/world/command_queue.rs | 6 +++---
 crates/bevy_ecs/src/world/mod.rs           | 8 ++++++++
 6 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs
index af5183b159..6c2c25d845 100644
--- a/crates/bevy_app/src/app.rs
+++ b/crates/bevy_app/src/app.rs
@@ -1582,7 +1582,7 @@ mod tests {
         app.add_systems(EnterMainMenu, (foo, bar));
 
         app.world_mut().run_schedule(EnterMainMenu);
-        assert_eq!(app.world().entities().len(), 2);
+        assert_eq!(app.world().num_entities(), 2);
     }
 
     #[test]
diff --git a/crates/bevy_ecs/src/lib.rs b/crates/bevy_ecs/src/lib.rs
index ecd77b028f..3fff349376 100644
--- a/crates/bevy_ecs/src/lib.rs
+++ b/crates/bevy_ecs/src/lib.rs
@@ -1637,7 +1637,7 @@ mod tests {
 
         assert_eq!(q1.iter(&world).len(), 1);
         assert_eq!(q2.iter(&world).len(), 1);
-        assert_eq!(world.entities().len(), 2);
+        assert_eq!(world.num_entities(), 2);
 
         world.clear_entities();
 
@@ -1652,7 +1652,7 @@ mod tests {
             "world should not contain sparse set components"
         );
         assert_eq!(
-            world.entities().len(),
+            world.num_entities(),
             0,
             "world should not have any entities"
         );
diff --git a/crates/bevy_ecs/src/observer/mod.rs b/crates/bevy_ecs/src/observer/mod.rs
index b3a8b3b5cd..ad0956f6d9 100644
--- a/crates/bevy_ecs/src/observer/mod.rs
+++ b/crates/bevy_ecs/src/observer/mod.rs
@@ -1315,7 +1315,7 @@ mod tests {
         world.spawn(A).flush();
         assert_eq!(vec!["add_2", "add_1"], world.resource::<Order>().0);
         // Our A entity plus our two observers
-        assert_eq!(world.entities().len(), 3);
+        assert_eq!(world.num_entities(), 3);
     }
 
     #[test]
diff --git a/crates/bevy_ecs/src/system/commands/mod.rs b/crates/bevy_ecs/src/system/commands/mod.rs
index 84f9784228..9f594402a3 100644
--- a/crates/bevy_ecs/src/system/commands/mod.rs
+++ b/crates/bevy_ecs/src/system/commands/mod.rs
@@ -2342,7 +2342,7 @@ mod tests {
             .spawn((W(1u32), W(2u64)))
             .id();
         command_queue.apply(&mut world);
-        assert_eq!(world.entities().len(), 1);
+        assert_eq!(world.num_entities(), 1);
         let results = world
             .query::<(&W<u32>, &W<u64>)>()
             .iter(&world)
diff --git a/crates/bevy_ecs/src/world/command_queue.rs b/crates/bevy_ecs/src/world/command_queue.rs
index e8f820c066..8e2776de46 100644
--- a/crates/bevy_ecs/src/world/command_queue.rs
+++ b/crates/bevy_ecs/src/world/command_queue.rs
@@ -423,12 +423,12 @@ mod test {
         let mut world = World::new();
         queue.apply(&mut world);
 
-        assert_eq!(world.entities().len(), 2);
+        assert_eq!(world.num_entities(), 2);
 
         // The previous call to `apply` cleared the queue.
         // This call should do nothing.
         queue.apply(&mut world);
-        assert_eq!(world.entities().len(), 2);
+        assert_eq!(world.num_entities(), 2);
     }
 
     #[expect(
@@ -462,7 +462,7 @@ mod test {
         queue.push(SpawnCommand);
         queue.push(SpawnCommand);
         queue.apply(&mut world);
-        assert_eq!(world.entities().len(), 3);
+        assert_eq!(world.num_entities(), 3);
     }
 
     #[test]
diff --git a/crates/bevy_ecs/src/world/mod.rs b/crates/bevy_ecs/src/world/mod.rs
index 2fb8f2d0eb..63e5d85435 100644
--- a/crates/bevy_ecs/src/world/mod.rs
+++ b/crates/bevy_ecs/src/world/mod.rs
@@ -216,6 +216,14 @@ impl World {
         &mut self.entities
     }
 
+    /// Retrieves the number of [`Entities`] in the world.
+    ///
+    /// This is helpful as a diagnostic, but it can also be used effectively in tests.
+    #[inline]
+    pub fn num_entities(&self) -> u32 {
+        self.entities.len()
+    }
+
     /// Retrieves this world's [`Archetypes`] collection.
     #[inline]
     pub fn archetypes(&self) -> &Archetypes {