Implement WorldQuery for EntityRef #6960

james7132 · 2022-12-15T05:29:29Z

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);

crates/bevy_ecs/src/query/fetch.rs

crates/bevy_ecs/src/system/query.rs

Co-authored-by: Carter Weinberg <[email protected]>

JoJoJet

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.

crates/bevy_ecs/src/system/query.rs

crates/bevy_ecs/src/query/fetch.rs

jakobhellermann · 2023-01-17T10:31:57Z

crates/bevy_ecs/src/query/fetch.rs

+            !access.access().has_any_write(),
+            "EntityRef conflicts with a previous access in this query. Shared access cannot coincide with exclusive access.",
+        );
+        access.read_all();


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

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.

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

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

Leave it until later please.

jakobhellermann · 2023-01-17T10:35:37Z

crates/bevy_ecs/src/query/fetch.rs

+        access: &mut Access<ArchetypeComponentId>,
+    ) {
+        for component_id in archetype.components() {
+            access.add_read(archetype.get_archetype_component_id(component_id).unwrap());


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?

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

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

crates/bevy_ecs/src/world/entity_ref.rs

Co-authored-by: Jakob Hellermann <[email protected]>

…tityRef

alice-i-cecile · 2023-06-19T16:42:12Z

@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)

james7132 added 4 commits December 14, 2022 21:52

Implement WorldQuery for EntityRef

e9fc9d0

Update query docs

13387e3

Ensure invalid use of EntityRef as a WorldQuery panics

c74843c

Add EntityRef to the ECS prelude

d00da4e

james7132 requested review from BoxyUwU and jakobhellermann December 15, 2022 05:29

james7132 added A-ECS Entities, components, systems, and events C-Usability A targeted quality-of-life change that makes Bevy easier to use M-Needs-Migration-Guide A breaking change to Bevy's public API that needs to be noted in a migration guide labels Dec 15, 2022

james7132 added 2 commits December 15, 2022 00:33

Fix safety comment

9cd5baa

Formatting

ddd845f

Carter0 reviewed Dec 15, 2022

View reviewed changes

crates/bevy_ecs/src/query/fetch.rs Show resolved Hide resolved

Carter0 reviewed Dec 15, 2022

View reviewed changes

crates/bevy_ecs/src/system/query.rs Outdated Show resolved Hide resolved

Fix typo.

a94a348

Co-authored-by: Carter Weinberg <[email protected]>

JoJoJet approved these changes Dec 16, 2022

View reviewed changes

crates/bevy_ecs/src/system/query.rs Outdated Show resolved Hide resolved

crates/bevy_ecs/src/system/query.rs Show resolved Hide resolved

alice-i-cecile self-requested a review December 27, 2022 03:47

jakobhellermann reviewed Jan 17, 2023

View reviewed changes

alice-i-cecile mentioned this pull request Jan 17, 2023

Split access model between components and resources #7255

Closed

james7132 and others added 5 commits January 17, 2023 12:06

Provide a safety comment to fetch

fc4a1c6

Co-authored-by: Jakob Hellermann <[email protected]>

Merge branch 'main' into entity-ref-world-query

185310b

Ensure it conflicts

aea7f0b

Make sure doc test panics

a0cbc4b

Add non-panicking doc test that shows how to use With/Without with En…

39cf337

…tityRef

james7132 added this to the 0.11 milestone Feb 27, 2023

alice-i-cecile approved these changes Jun 19, 2023

View reviewed changes

alice-i-cecile added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Jun 19, 2023

Merge remote-tracking branch 'origin/main' into pr/james7132/6960

0c91c16

cart approved these changes Jun 22, 2023

View reviewed changes

cart enabled auto-merge June 22, 2023 21:08

cart added this pull request to the merge queue Jun 22, 2023

Merged via the queue into bevyengine:main with commit 70f91b2 Jun 22, 2023

This was referenced Jun 28, 2023

News: Release 0.11 (wrong branch ... see #657) bevyengine/bevy-website#656

Closed

News: Release 0.11 bevyengine/bevy-website#657

Merged

james7132 mentioned this pull request Aug 12, 2023

EntityRef as WorldQuery is unsound. #9422

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement WorldQuery for EntityRef #6960

Implement WorldQuery for EntityRef #6960

james7132 commented Dec 15, 2022 •

edited

Loading

JoJoJet left a comment

jakobhellermann Jan 17, 2023

james7132 Jan 17, 2023 •

edited

Loading

alice-i-cecile Jan 17, 2023

james7132 Jan 18, 2023

alice-i-cecile Jun 19, 2023

jakobhellermann Jan 17, 2023

james7132 Jan 17, 2023

jakobhellermann Jan 17, 2023

alice-i-cecile commented Jun 19, 2023

cart left a comment

Implement WorldQuery for EntityRef #6960

Implement WorldQuery for EntityRef #6960

Conversation

james7132 commented Dec 15, 2022 • edited Loading

Objective

Solution

Performance

Future work

Changelog

Migration Guide

JoJoJet left a comment

Choose a reason for hiding this comment

jakobhellermann Jan 17, 2023

Choose a reason for hiding this comment

james7132 Jan 17, 2023 • edited Loading

Choose a reason for hiding this comment

alice-i-cecile Jan 17, 2023

Choose a reason for hiding this comment

james7132 Jan 18, 2023

Choose a reason for hiding this comment

alice-i-cecile Jun 19, 2023

Choose a reason for hiding this comment

jakobhellermann Jan 17, 2023

Choose a reason for hiding this comment

james7132 Jan 17, 2023

Choose a reason for hiding this comment

jakobhellermann Jan 17, 2023

Choose a reason for hiding this comment

alice-i-cecile commented Jun 19, 2023

cart left a comment

Choose a reason for hiding this comment

james7132 commented Dec 15, 2022 •

edited

Loading

james7132 Jan 17, 2023 •

edited

Loading