Implement WorldQuery for EntityRef

[james7132]

Objective

Partially address #5504. Fix #4278. Provide "whole entity" access in queries. This can be useful when you don't know at compile time what you're accessing (i.e. reflection via ReflectComponent).

Solution

Implement WorldQuery for EntityRef.

• This provides read-only access to the entire entity, and supports anything that EntityRef can normally do.
• It matches all archetypes and tables and will densely iterate when possible.
• It marks all of the ArchetypeComponentIds of a matched archetype as read.
• Adding it to a query will cause it to panic if used in conjunction with any other mutable access.
• Expanded the docs on Query to advertise this feature.
• Added tests to ensure the panics were working as intended.
• Added EntityRef to the ECS prelude.

To make this safe, EntityRef::world was removed as it gave potential UnsafeCell-like access to other parts of the World including aliased mutable access to the components it would otherwise read safely.

Performance

Not great beyond the additional parallelization opportunity over exclusive systems. The EntityRef is fetched from Entities like any other call to World::entity, which can be very random access heavy. This could be simplified if ArchetypeRow is available in WorldQuery::fetch's arguments, but that's likely not something we should optimize for.

Future work

An equivalent API where it gives mutable access to all components on a entity can be done with a scoped version of EntityMut where it does not provide &mut World access nor allow for structural changes to the entity is feasible as well. This could be done as a safe alternative to exclusive system when structural mutation isn't required or the target set of entities is scoped.

---

Changelog

Added: Access::has_any_write
Added: EntityRef now implements WorldQuery. Allows read-only access to the entire entity, incompatible with any other mutable access, can be mixed with With/Without filters for more targeted use.
Added: EntityRef to bevy::ecs::prelude.
Removed: EntityRef::world

Migration Guide

EntityRef::world has been removed to make EntityRef sound to use as a query result. If you were retrieving EntityRef via World::entity or World::get_entity. Save a copy of the reference to the World before calling World::entity.

// In 0.10
let entity_ref = world.entity(id);
let world_2 = entity_ref.world();

// In 0.11
let world_2 = &world;
let entity_ref = world.entity(id);

[joseph-gio]

The WorldQuery impl looks right to me, and I don't see any real issues. Just a few things that could be added.

I imagine this will be very useful in niche situations.

[jakobhellermann]

Does a Query<EntityRef> conflict with Res<Foo> with a read_all?

[james7132]

No, but a ResMut<T> would conflict under this access model. We could split this between "read all components" and "reads all resources" but I'm not sure how that would interact with the bitsets. Happy to try to do this in this PR, or defer it until later.

[alice-i-cecile]

I'd prefer to split that out (and I do think that should be done): that sort of work needs careful review.

[james7132]

Should I address this as a part of this PR or should I leave this for later?

[alice-i-cecile]

Leave it until later please.

[jakobhellermann]

This means that you can have a system with Query<(EntityRef, &A)> that is fine, until you do commands.entity(entity).insert(A), right? Can we have a test for that?

[james7132]

That's probably still fine since it only mutates the command queue and not the entity directly.

[jakobhellermann]

Yeah I didn't expect it to be unsound, just something to keep in mind where a system may panic depending on the entities and components in the world.

Like how (a: Query<(&mut A, &C)>, b: Query<(&mut A, &B)>) used to only conflict as soon as a (A, B, C) entity is spawned. https://bevyengine.org/news/bevy-0-5/#query-conflicts-use-componentid-instead-of-archetypecomponentid

[alice-i-cecile]

@james7132 I'm happy with this work and glad to see more steps towards runtime component access coming together! Once you've resolved conflicts feel free to merge <3

[cart]

This looks good to me!
I've resolved conflicts (and adjusted to the UnsafeWorldCell changes)