Components as entities (v2)

[Trashtalk217]

See #23988.

Objective

There are two primary problems we currently have with resources-as-components (#19731) .

Performance regression #23039

In order to get access to a resource entity, you usually need to go through two lookups: TypeId -> ComponentId -> Entity. The ComponentId -> Entity lookup can potentially be removed, speeding up resource lookup.

World Asset Serialization (previously in bevy_scene) #22968

Currently, one big downside of resources-as-components is that any components on resource entities aren't serialized. This forms a barrier for implementing required components for resources. Implementing this correctly is tricky. One of the problems we run into is that IsResource(ComponentId) cannot be directly copied over because ComponentIds are not consistent between worlds.

Solution

We change ComponentId(usize) into ComponentId(Entity) and use the EntityAllocator to create ComponentIds. Next, we store all resources on the ComponentId entity. This makes the ComponentId -> Entity lookup a no-op. And we can also use the MapEntities machinery to serialize and deserialize worlds.

Future Work

In the future, we can look at adding parts of ComponentInfo as a component to the component entities. That sounds confusing, because it is. This would improve the introspection ability of the ECS (being able to query for metadata about the components). This, however, requires quite a bit of weird bootstrapping, which I don't know how to do and is not necessary for this PR.

Testing

This is principally a performance PR, and while I will be doing some benchmarking myself, I don't have the hardware. So I'll be asking someone to give it a once-over when it's ready.

Change

The primary difference between this and #23988, is that this is not reliant on Entity Ranges (#24102). Because of this, there is a possibility for a performance regression with regards to Components.components going from a SparseArray to HashMap. There is an additional hash operation. Additionally, the fields on Access have changed from a FixedBitSet to a HashSet, so the set operations are likely slower.

[Trashtalk217]

Performance Testing

I did some reasonably extensive performance testing. I ran both the entire ecs benchmark and several of our stress test examples. I've got the following data:

• cargo bench -p benches --bench ecs -> benchmarks.txt

And the three examples I ran through were

• cargo run --release --example bevymark -- --waves 60 --per-wave 500 --benchmark --mode mesh2d
• cargo run --release --example many_components 100000 1000 1000
• running bevy_city with mangohud.

name	frametime before (main)	frametime after (pr)
bevymark	37.5 ms	37.8 ms
many_components	6.6 ms	6.5 ms
bevy_city	90.5 ms	90.5 ms

Conclusion

From the measurements I took I've come to the conclusion that this PR mostly keeps performance the same. At worst it degrades slightly (mostly based on the microbenchmarks). The best solution to fix the resource performance issue is likely still going to be #24058 or something like it.

However!

I still think this PR is worth merging, because

1. It's a step to storing a meta-component on the component entity, allowing for more introspection in the ecs.
2. Users can tag component entities with their own data ComponentInfo extensions #24338.
3. It removes an indirection in the code via ResourceEntities and with it some unsafe code.
4. The (in my opinion minor) loss of performance can in the future be offset by introducing entity ranges (Entity ranges #24102) and hybrid datastructures. For more information checkout the entity ranges PR (or ask!).
5. It makes working with resources more consistent. Before, world.spawn((Res1, Res2)) would store Res2 on the resource entity of Res1, so Res2 would be stored on the wrong location. In this PR, this would throw a warning and remove both Res1 and Res2 because neither are on the appropriate entity.

Important Note

When review and discussing this PR, I prefer if you mostly kept it anchored to some line of code (even if only vaguely related). This makes it easier to follow particular threads of argument.

[Victoronz]

Looks good! I don't believe the #24102 is necessary for this, and can be left for later.

With this change, it becomes possible to express uniqueness regarding ComponentId collections/iterators as well. There are now likely several sections of code where it would make sense to convert the previous ComponentId collection/iterator types to their EntitySet version. That would make for a good follow-up PR!

One place for which this is especially relevant is DynamicComponentFetch, the current dynamic way to access the Components of an entity disjointly.
This functionality should fall under similar design considerations as #18234, though that PR has gotten stalled.

[chescock]

Oh, nice! Reserving the Entity early and then using spawn_at is a really nice approach. I was worried this would be really complex, but it's very readable and even net negative lines!

I'm surprised that using HashMap for access didn't affect the benchmarks! It might be because all of the access checks are done at startup, while we mostly benchmark steady-state performance.

Most of my comments are just style nits, but I do think we should have a clear story for how users should spawn resource entities that have additional components, and we should try to ensure that ResMut<R> and Query<&mut R, Without<IsResource>> are sound.

[chescock]

Since these are the operator traits in core::ops, would it be more clear to use the actual operators? (Here and elsewhere.)

Suggested change

	(true, true) => self_set.bitand_assign(other_set),
	(true, false) => self_set.sub_assign(other_set),
	(false, true) => {
	*self_inverted = true;
	self_set.difference_from(other_set);
	*self_set = other_set.clone().sub(self_set);
	}
	(false, false) => self_set.union_with(other_set),
	(false, false) => self_set.bitor_assign(other_set),
	(true, true) => *self_set &= other_set,
	(true, false) => *self_set -= other_set,
	(false, true) => {
	*self_inverted = true;
	*self_set = other_set - self_set;
	}
	(false, false) => *self_set |= other_set,

(Oh, neat, GitHub finally lets me add a suggestion that crosses deleted lines! ... It does not render it very helpfully, though.)

[Trashtalk217]

I personally prefer union_with, difference_with and intersect_with, as they more clearly communicate the idea of sets compared to bit operations. I did have to resort to using them for the non-in-place methods as the .difference method simply doesn't return the right type, but it should still be an improvement in readabillity.

[chescock]

If someone despawns a resource, these spawn_at(...).unwrap() calls will panic, right? Ah, but that's what we do today in the IsResource hook, so that's no worse.

Do we want a "Resource entity {} of {} has been despawned, when it's not supposed to be." message in the panic, like we have in the IsResource hooks?

[Trashtalk217]

In this specific case, it's impossible for the unwrap to panic, because at the top of the function it calls register_component, which allocates the entity. I've switched to spawn_at_unchecked and added an explanation in a comment.

I'll do the same for the other spawn_at(entity).unwrap() or, if they really could fail, throw an appropriate error.

[chescock]

This would be for a follow-up and not this PR, but: Do we still need IsResource?

At the very least, we must not need it to store ComponentId, since that's always going to be equal to the Entity, right?

[Trashtalk217]

This is a good question and depends quite a bit on where we want to have the logic that handles uniqueness. Right now, we need some hooks to ensure that a resource isn't spawned where it isn't supposed to be spawned.

If we put this logic on a component hook on every Resource (which I think makes sense), this is trivial. You just check if context.component_id matches context.entity.

But you only get one hook, and a user might want to use that hook for their own stuff. Using IsResource like this offloads this logic to another component and leaves room for user hooks on resources. However, the link between them is much weaker (what if you remove IsResource, but keep the resource? and other questions), and it would still need to keep a hold of ComponentId.

I think the former is a better solution, but we currently offer the latter, so changing this would be a regression. This is not major, since lifetime observers exist and you get an unlimited amount of them, but observers aren't quite as good as hooks in some cases.

[chescock]

I think spawn_empty_at duplicates some of the checks from contains_spawned. This is also the code that got simplified a bit in the closed #24594 with get_or_spawn_resource_entity. I wonder if we want a method on World like

    #[track_caller]
    pub fn get_or_spawn_at(
        &mut self,
        entity: Entity,
    ) -> Result<EntityWorldMut<'_>, InvalidEntityError> {
        match self.entities.get_spawned(entity) {
            Ok(location) => Ok(unsafe { EntityWorldMut::new(self, entity, Some(location)) }),
            Err(EntityNotSpawnedError::ValidButNotSpawned { .. }) => {
                Ok(self.spawn_empty_at_unchecked(entity, MaybeLocation::caller()))
            }
            Err(EntityNotSpawnedError::Invalid(err)) => Err(err),
        }
    }

[Trashtalk217]

I think using spawn_empty_at_unchecked instead of spawn_empty_at is fine for now.

[chescock]

Is clear_entities() completely unusable now? Any resource that had been spawned can never be created again, right? Should we just remove it completely?

And, should this bench still despawn the entities that are spawned by add_archetypes? We could presumably add a marker component to identify them.

[chescock]

How important is the perf from using insert_unique_unchecked here instead of an ordinary insert? I'd be inclined to use the safer version if we can.

[Victoronz]

There is a genuine performance difference, and I think it'd be best to keep using it.
However, "never having been registered before" meaning "does not exist in this collection" should be more extensively documented somewhere.

[chescock]

There is a genuine performance difference, and I think it'd be best to keep using it.

Does that difference matter for our case? The linked issue says it makes the insert 30% faster, but that's only a part of component registration, and I'm not sure we're even all that perf-sensitive for something that only runs once per component.

---

And thinking about it more, I'm not sure we can guarantee that the id is unique. A user can call world.entity_allocator_mut().free(entity) from safe code with the same Entity in a loop, and then register_component could allocate that same Entity for multiple components! It's fine to panic for something that bizarre, but I don't think it should allow UB.

Which also means we need to panic rather than silently overwrite if the key exists, so something like try_insert(id, info).expect(...).

[chescock]

Does this mean world.spawn((R, OtherComponents)) no longer works for adding a resource that also has other components? It needs to be something like

let entity = world.register_component::<R>().entity();
world.spawn_at(entity, (R, OtherComponents));

?

That should go in the migration guide, but maybe we also need a convenience method like world.insert_resource_with(R, OtherComponents) or world.get_or_spawn_resource_entity::<R>().insert((R, OtherComponents)).

[Trashtalk217]

Correct.

I'm hesitant to add methods like world.insert_resource_with, because currently bevy_world_serialize drops any extra components you add to a resource entity during serialization. I'd much prefer fixing that bug before adding convenience methods.

[Trashtalk217]

This is the same reason why I didn't add required components in 0.19.

UPDATE: nevermind someone else did #24322, let's just hope no one notices before 0.20.

[chescock]

How are we ensuring soundness for things like ResMut<R> and Query<&mut R, Without<IsResource>>?

Previously that was handled by IsResource being the source of truth for the resource_entities map, so if the IsResource component got removed then ResMut would no longer see the resource. But now we're going directly to the Entity, so I think it will be found by ResMut even if IsResource is missing and it will also match the Query.

[Trashtalk217]

We are ensuring soundness just like we had before, since IsResource is still the source of truth, which is the only thing (together with the entity) queries care about.

[chescock]

This functionality should fall under similar design considerations as #18234, though that PR has gotten stalled.

Oh, wow, that's been stalled for more than a year. And I still don't feel motivated to pick it back up, so I'm just going to go mark it S-Adopt-Me.