Add entities alongside resources #19711

Trashtalk217 · 2025-06-18T00:21:47Z

Objective

First step towards resources as components as described in #17485.

Solution

We add an entity alongside every Resource. We do not store any data on it yet, just to see if anything breaks. We also added a small cache that links ComponentIDs to entities for Resources.

Testing

I should probably add a test that checks how good the cache works.

Discussion

As outlined in this Hackmd doc, we want to keep the Resources conceptually separate from 'normal' entities, and as such for every single method that deals with entities we can play a fun gameshow game: "Does this method account for Resources?"

Here's a table with my opinion of how it should work. The third column tells you if this is how it currently works in this PR.

Method or Code snippet	Should it account for Resources?	Is that how it works in this PR?
`world.entities.len()`	No	Yes, but there should probably a method to count entities, that excludes resources.
`world.query::<()>`	Yes	No, this returns every single entity (except disabled ones)
`world.clear_entities()`	Yes	No, and `world.clear_resources()` should also be changed.
`world.iter_entities()` and `world.iter_entities_mut()`	Yes	No

This table can easily be expanded, but the more we add, the less of a good idea it is to tackle this in a single PR.

github-actions · 2025-06-18T00:26:43Z

It looks like your PR is a breaking change, but you didn't provide a migration guide.

Please review the instructions for writing migration guides, then expand or revise the content in the migration guides directory to reflect your changes.

crates/bevy_ecs/src/component.rs

crates/bevy_ecs/src/resource.rs

alice-i-cecile

I really like this as an incremental step forward. In this PR, I would like to:

Use hooks to keep the resource storage / resource entities in sync.
Use hooks to ensure resource entity uniqueness.
Add IsResource to our default query filters.

With that in place, I think we can probably merge this safely as an incremental, mildly useful step forward.

Trashtalk217 · 2025-06-22T19:53:33Z

Due to a couple of issues, I've decided to simplify this PR to the bare minimum. There are so many tests that assume that the world starts off with zero entities, that I've decided to only address that in this PR. So I removed the component hook (it will return) and used the simplest cache.

In particular I need a bit of help with the bevy_scene tests. It's complaining that I don't have IsResource and ResourceEntity registered through Reflection and I don't know how Reflection works.

alice-i-cecile · 2025-06-22T21:28:28Z

It's complaining that I don't have IsResource and ResourceEntity registered through Reflection and I don't know how Reflection works.

You're going to want to derive Reflect (gated behind a bevy_reflect feature), and then call .register_type for those types. Search to see where we do that for the other bevy_ecs component types!

# 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>

tbillington · 2025-06-30T08:36:13Z

I haven't followed any prior discussion on this, so apologies in advance!

I can't see a justification in the hackmd for entities.len() ignoring "resource entities". Is this just for test ergonomics? Perhaps a private test helper function can solve this rather than "lying" from what seems like a very fundamental API for lack of a better word.

I'm also unsure why a blank, newly created world would have entities. I assume there's a reason for it I'm unaware of but this PR doesn't give rationale for it. If we no longer assume a "default" world will be empty, will there be a world constructor that does create an empty world?

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 (bevyengine#19711), and as such all of these tests are failing for that PR. `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. 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>

Trashtalk217 · 2025-07-10T21:00:18Z

One of these days I'll get better at git
:\

…ce_entity_lookup

Trashtalk217 · 2025-07-12T13:11:07Z

@tbillington
entity_count does give a 'wrong' count of the number of entities (although it is documented that this doesn't count Resources). The reason for this is twofold: first, there's test ergonomics. A lot of tests simply assume that a new world is empty and I expect that this is going to become less and less true in the future (components as entities for example, will increase the number of entities that exists in a world).
Secondly, throughout the World module, a distinction is made between resources and entities: iter_resources and iter_entities, or clear_entities and clear_resources. I've come to the conclusion that it's preferable to keep these concepts separate. It would be surprising to iterate through entities and find resources, similarly it is confusing to count entities and have resources be included in the count.

For the old behaviour, there's still world.entities().len(), world.entity_count() is a convenience method.

As for your second question: Why is a new world not empty? DefaultQueryFilters is a Resource added at world creation, that holds all the components that are automatically excluded from queries.

chescock · 2025-07-12T13:44:36Z

crates/bevy_ecs/src/world/mod.rs

@@ -169,6 +170,7 @@ impl World {

        // This sets up `Disabled` as a disabling component, via the FromWorld impl
        self.init_resource::<DefaultQueryFilters>();
+        self.register_disabling_component::<IsResource>();


This should probably be added in impl FromWorld for DefaultQueryFilters alongside the registration for Disabled. That way, users can do DefaultQueryFilters::from_world(world) to recreate the default value.

chescock · 2025-07-12T13:45:11Z

crates/bevy_ecs/src/query/builder.rs

@@ -485,6 +487,7 @@ mod tests {

        let mut query = QueryBuilder::<(FilteredEntityMut, EntityMutExcept<A>)>::new(&mut world)
            .data::<EntityMut>()
+            .filter::<Without<IsResource>>()


These should no longer be necessary now that you have a default query filter, right?

chescock · 2025-07-12T13:47:41Z

crates/bevy_ecs/src/query/state.rs

@@ -2175,6 +2177,7 @@ mod tests {
        let mut df = DefaultQueryFilters::empty();
        df.register_disabling_component(world.register_component::<C>());
        world.insert_resource(df);
+        world.register_disabling_component::<IsResource>();


These tests might be more robust if they start with the default DefaultQueryFilters instead of an empty() one. So, just calling

world.register_disabling_component::<C>();

instead of creating and inserting df manually.

chescock · 2025-07-12T13:48:24Z

crates/bevy_ecs/src/resource.rs

+    reflect(Component, Default, Debug)
+)]
+#[derive(Component, Default, Debug)]
+pub struct IsResource;


Would it be valuable to stick the ComponentId of the resource in here so we can map in the other direction? I guess that would mean you couldn't use required components, though.

chescock · 2025-07-12T13:59:24Z

crates/bevy_ecs/src/world/mod.rs

+            .resource_entities
+            .contains_key(&component_id)
+        {
+            // Since we don't know the type, we use a placeholder type.


Do we need to handle the case where someone uses the untyped API to insert a typed resource? I can imagine things like the editor or BRP needing to do that. This will add ResourceEntity::<TypeErasedResource> even if the resource has a type.

You might need to register the ComponentId of the appropriate ResourceEntity<R> type when you register the resource, and then add it dynamically here (which should be possible, since it's a ZST). I think you could store the extra ComponentId inside the resource's ComponentDescriptor. That would even let you register a unique ComponentId for each untyped resource!

Do we need to handle the case where someone uses the untyped API to insert a typed resource? I can imagine things like the editor or BRP needing to do that. This will add ResourceEntity::<TypeErasedResource> even if the resource has a type.

Wait, no, I'm wrong, those will use reflection, which is built on the typed API.

So, there's technically a hole here, but user code would have to go out of its way to use the untyped API in order to trigger it, so it's probably not a big deal.

chescock · 2025-07-12T14:03:36Z

crates/bevy_ecs/src/world/mod.rs

+        if !self
+            .components
+            .resource_entities
+            .contains_key(&component_id)
+        {
+            let entity = self.spawn(ResourceEntity::<R>::default()).id();
+            self.components
+                .resource_entities
+                .insert(component_id, entity);
+        }
+


I think these could use entry to avoid the double lookup.

Suggested change

if !self

.components

.resource_entities

.contains_key(&component_id)

{

let entity = self.spawn(ResourceEntity::<R>::default()).id();

self.components

.resource_entities

.insert(component_id, entity);

}

self.components

.resource_entities

.entry(component_id)

.or_insert_with(|| self.spawn(ResourceEntity::<R>::default()).id());

Trashtalk217 added A-ECS M-Needs-Migration-Guide D-Modest labels Jun 18, 2025

alice-i-cecile added the S-Waiting-on-Author label Jun 18, 2025

alice-i-cecile reviewed Jun 18, 2025

View reviewed changes

crates/bevy_ecs/src/component.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Jun 18, 2025

View reviewed changes

crates/bevy_ecs/src/resource.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Jun 18, 2025

View reviewed changes

crates/bevy_ecs/src/resource.rs Show resolved Hide resolved

alice-i-cecile requested changes Jun 18, 2025

View reviewed changes

Trashtalk217 mentioned this pull request Jun 19, 2025

Resources as Components Tracking Issue #19731

Open

8 tasks

Trashtalk217 added D-Complex S-Needs-Help and removed D-Modest S-Waiting-on-Author labels Jun 22, 2025

Trashtalk217 mentioned this pull request Jun 22, 2025

Add num_entities() to World #19780

Merged

add back all changes

042337f

Trashtalk217 force-pushed the resource_entity_lookup branch from f4e2b35 to 042337f Compare July 10, 2025 22:25

Trashtalk217 added 7 commits July 10, 2025 22:37

Merge branch 'main' of https://github.com/bevyengine/bevy into resour…

47c20a5

…ce_entity_lookup

cargo fmt

64eac9a

cargo clippy

956c1a6

add entities with resources, auto disabled IsResource

073df4b

fixed and tests

6c8281d

fixed more tests

f9dc9f1

fixed moore tests

07723ac

Trashtalk217 added 6 commits July 12, 2025 11:16

fix ci

1ba7af2

fix mooore tests (benches)

b89c042

fix docs

9b33933

add migration guide

c7b4f1d

fixed spelling errors to prove I'm not AI

96aef45

Merge branch 'main' of https://github.com/bevyengine/bevy into resour…

e3ccd1b

…ce_entity_lookup

Trashtalk217 removed the M-Needs-Migration-Guide label Jul 12, 2025

chescock reviewed Jul 12, 2025

View reviewed changes

Uh oh!

Add entities alongside resources #19711

Are you sure you want to change the base?

Add entities alongside resources #19711

Conversation

Trashtalk217 commented Jun 18, 2025

Objective

Solution

Testing

Discussion

Uh oh!

github-actions bot commented Jun 18, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alice-i-cecile left a comment

Choose a reason for hiding this comment

Uh oh!

Trashtalk217 commented Jun 22, 2025

Uh oh!

alice-i-cecile commented Jun 22, 2025

Uh oh!

tbillington commented Jun 30, 2025

Uh oh!

Trashtalk217 commented Jul 10, 2025

Uh oh!

Trashtalk217 commented Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chescock Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

chescock Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

chescock Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

chescock Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

chescock Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

chescock Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

chescock Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Trashtalk217 commented Jul 12, 2025 •

edited

Loading