Add `AssetChanged` query filter #16810

tychedelia · 2024-12-13T20:20:48Z

Objective

Implement a new AssetChanged query filter that allows users to query for entities whose related assets may have changed.

Closes A query filter for Asset updates #5069
Unblocks Cold specialization #16420. Currently, cold-specialization, a key rendering optimization for unlocking ancillary benefits of the retained render world, is blocked on being unable detect all scenarios in which an entity's mesh/material changes using events and observers. An AssetChanged filter will drastically simplify our implementation and be more robust to future changes.

Originally implemented by @nicopap in #5080.

Solution

Adds a new AssetChanged query filter that initializes a AssetChanges<A> resource that tracks changed assets and ticks in asset_events.
~~Reverts constrain WorldQuery::get_state to only use &Components #13343 and changes the api of get_state to accept impl Into<UnsafeWorldCell<'w>> to allow accessing the AssetChanges<A> resource.~~
Adds a AsAssetId trait used for newtype handle wrappers (e.g. Mesh3d) that allows associating a component with the underlying Asset it represents.

Testing

Tests are added for AssetChanged.
TBD on performance. We are going to add this Mesh3d and MeshMaterial3d (etc) in the renderer. Long term wins in render performance this unblocks should swamp tracking overhead for any realistic workload.

Migration Guide

The asset_events system is no longer public. Users should order their systems relative to the AssetEvents system set.

Victoronz · 2024-12-13T20:39:59Z

Why does this revert the get_state PR? In the get_state impl of this PR, I only see a call to resource_id on world, which is already available on &Components.

tychedelia · 2024-12-13T20:48:49Z

Why does this revert the get_state PR? In the get_state impl of this PR, I only see a call to resource_id on world, which is already available on &Components.

Because I didn't know that. Will change it back!

Victoronz · 2024-12-13T20:59:35Z

Separately, how should the resource access in init_fetch be reasoned about?
A type being private means it cannot be mentioned in user code, however you do not have to mention a type to obtain it via public API! In this case, this is possible via id-based resource fetching.
UnsafeWorldCell::get_resource gives its caller the responsibility to ensure it has access to that resource, however this safety contract cannot be passed on to users of the filter.
For both users, libraries and other in-engine areas, how should we communicate about this?

crates/bevy_asset/src/lib.rs

pcwalton · 2024-12-13T21:00:01Z

crates/bevy_asset/src/asset_changed.rs

+
+/// Filter that selects entities with a `A` for an asset that changed
+/// after the system last ran, where `A` is a component that implements
+/// [`AsAssetId`].


What about components that store handles to multiple assets of the same type? We don't need to do that right now, but we might have to revisit it later. In my app I have components with handles to dozens of AnimationClips for example. I think you could maybe just have AsAssetId's method return -> impl Iterator<Item = AssetId>.

This isn't blocking, just a suggestion.

The bigger issue is how to handle the associated type. We might have to use some kind of indirection via UntypedAssetId instead to be able to handle multiple kinds of assets.

Sorry, I also misunderstood you. Multiple assets of the same type should be much easier to handle. I'd been hung up on if, for example we decided to merge mesh and material as has been discussed before.

crates/bevy_asset/src/asset_changed.rs

crates/bevy_asset/src/lib.rs

crates/bevy_ecs/src/query/fetch.rs

tychedelia · 2024-12-13T21:08:16Z

In this case, this is possible via id-based resource fetching.

How would the user forge an id if they do not have access to the underlying type? UnsafeWorldCell::get_resource already documents the aliasing requirements as an unsafe API. If users are iterating or creating random opaque ComponentIds and getting mutable access they trivially violate that contract by not knowing what resource they are touching.

Co-authored-by: Patrick Walton <pcwalton@mimiga.net>

pcwalton · 2024-12-13T21:08:56Z

Overall this looks fine to me, but as I mentioned we should have an ECS expert look over the get_state signature change.

crates/bevy_asset/src/asset_changed.rs

alice-i-cecile · 2024-12-14T05:41:26Z

crates/bevy_ecs/src/query/state.rs

@@ -583,6 +583,16 @@ impl<D: QueryData, F: QueryFilter> QueryState<D, F> {
            {
                access.add_component_write(archetype_component_id);
            }
+            if self.component_access.access.has_resource_read(component_id) {


Oh right, this is an existing soundness bug. Re-adding the tag.

These changes have been removed in favor of @chescock's.

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

crates/bevy_asset/src/asset_changed.rs

# Objective Allow resources to be accessed soundly by `QueryData` and `QueryFilter` implementations. This mostly works today, and is used in `bevy-trait-query` and will be used by #16810. The problem is that the access is not made visible to the executor, so it would be possible for a system with resource access in a query to run concurrently with a system that accesses the resource with `ResMut`, resulting in Undefined Behavior. ## Solution Define calling `add_resource_read` or `add_resource_write` in `WorldQuery::update_component_access` to be a supported way to declare resource access in a query. Modify `QueryState::new_with_access` to check for resource access and report it in `archetype_component_acccess`. Modify `FilteredAccess::is_compatible` to consider resource access conflicting even on queries with disjoint filters.

Co-authored-by: Chris Russell <8494645+chescock@users.noreply.github.com>

pcwalton

Seems fine, with the caveat that as usual I'm not an expert on the ECS guts.

pcwalton · 2024-12-17T17:29:28Z

crates/bevy_asset/src/asset_changed.rs

+/// This resource is automatically managed by the [`AssetEvents`](crate::AssetEvents) schedule and
+/// should not be exposed to the user in order to maintain safety guarantees. Any additional uses of
+/// this resource should be carefully audited to ensure that they do not introduce any safety
+/// issues.


When you mean "should not be exposed", what do you mean? Changing the fields?

I ask because usually safety invariants are scoped to be module-private, not crate-private.

This mostly is meant to mean don't make this pub because some asks. It's crate scoped mostly due to code organization, having the filter live in its own file is I think preferable to including all of this code in the root lib file where the asset event system lives simply for the sake of keeping it module private.

# Objective Allow resources to be accessed soundly by `QueryData` and `QueryFilter` implementations. This mostly works today, and is used in `bevy-trait-query` and will be used by bevyengine#16810. The problem is that the access is not made visible to the executor, so it would be possible for a system with resource access in a query to run concurrently with a system that accesses the resource with `ResMut`, resulting in Undefined Behavior. ## Solution Define calling `add_resource_read` or `add_resource_write` in `WorldQuery::update_component_access` to be a supported way to declare resource access in a query. Modify `QueryState::new_with_access` to check for resource access and report it in `archetype_component_acccess`. Modify `FilteredAccess::is_compatible` to consider resource access conflicting even on queries with disjoint filters.

@nicopap

# Objective Implement a new `AssetChanged` query filter that allows users to query for entities whose related assets may have changed. - Closes bevyengine#5069 - Unblocks bevyengine#16420. Currently, `cold-specialization`, a key rendering optimization for unlocking ancillary benefits of the retained render world, is blocked on being unable detect all scenarios in which an entity's mesh/material changes using events and observers. An `AssetChanged` filter will drastically simplify our implementation and be more robust to future changes. Originally implemented by @nicopap in bevyengine#5080. ## Solution - Adds a new `AssetChanged` query filter that initializes a `AssetChanges<A>` resource that tracks changed assets and ticks in `asset_events`. - ~Reverts bevyengine#13343 and changes the api of `get_state` to accept `impl Into<UnsafeWorldCell<'w>>` to allow accessing the `AssetChanges<A>` resource.~ - Adds a `AsAssetId` trait used for newtype handle wrappers (e.g. `Mesh3d`) that allows associating a component with the underlying `Asset` it represents. ## Testing - Tests are added for `AssetChanged`. - TBD on performance. We are going to add this `Mesh3d` and `MeshMaterial3d` (etc) in the renderer. Long term wins in render performance this unblocks should swamp tracking overhead for any realistic workload. ## Migration Guide - The `asset_events` system is no longer public. Users should order their systems relative to the `AssetEvents` system set. --------- Co-authored-by: Nicola Papale <nico@nicopap.ch> Co-authored-by: Patrick Walton <pcwalton@mimiga.net> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Chris Russell <8494645+chescock@users.noreply.github.com>

nicopap and others added 6 commits December 13, 2024 11:53

Add the AssetChanged query filter

da3a1fc

Implement djeedai feedbacks

ce19c2f

Fix clippy lints

5dbfea9

Rename handle_id

03d4848

Update to main.

5e9bd4a

Implement updates for AssetChanges.

2092eb1

tychedelia added A-ECS Entities, components, systems, and events X-Contentious There are nontrivial implications that should be thought through S-Needs-Review Needs reviewer attention (from anyone!) to move forward S-Needs-SME Decision or review from an SME is required labels Dec 13, 2024

tychedelia changed the title ~~Changed handle~~ Add AssetChanged query filter Dec 13, 2024

tychedelia added 2 commits December 13, 2024 12:23

Ci.

2f95290

Fmt.

eae75cf

ItsDoot added the C-Usability A targeted quality-of-life change that makes Bevy easier to use label Dec 13, 2024

tychedelia added 2 commits December 13, 2024 12:51

Switch back to using &Components.

4278615

Ci.

1001e27

Victoronz added the P-Unsound A bug that results in undefined compiler behavior label Dec 13, 2024

pcwalton reviewed Dec 13, 2024

View reviewed changes

Update crates/bevy_asset/src/lib.rs

b6ac681

Co-authored-by: Patrick Walton <pcwalton@mimiga.net>

tychedelia added 4 commits December 13, 2024 13:29

Respond to feedback.

ec0803c

Ci.

b1640b5

Ci.

3015581

Ci.

d70303d

chescock reviewed Dec 13, 2024

View reviewed changes

crates/bevy_asset/src/asset_changed.rs Show resolved Hide resolved

alice-i-cecile added this to the 0.16 milestone Dec 13, 2024

tychedelia added 2 commits December 13, 2024 19:35

Ci.

08a81ca

component_id -> register_component.

13ddde4

alice-i-cecile added the M-Needs-Release-Note Work that should be called out in the blog due to impact label Dec 14, 2024

alice-i-cecile reviewed Dec 14, 2024

View reviewed changes

crates/bevy_asset/src/asset_changed.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Dec 14, 2024

View reviewed changes

crates/bevy_asset/src/asset_changed.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Dec 14, 2024

View reviewed changes

crates/bevy_asset/src/asset_changed.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Dec 14, 2024

View reviewed changes

crates/bevy_asset/src/asset_changed.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Dec 14, 2024

View reviewed changes

alice-i-cecile added the P-Unsound A bug that results in undefined compiler behavior label Dec 14, 2024

tychedelia and others added 4 commits December 13, 2024 22:33

Apply suggestions from code review

1aee413

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Move to local allows.

46dfc2c

Ci.

53a8c67

Ci.

5a37dca

chescock mentioned this pull request Dec 16, 2024

Support declaring resource access in Queries. #16843

Merged

chescock reviewed Dec 16, 2024

View reviewed changes

crates/bevy_asset/src/asset_changed.rs Outdated Show resolved Hide resolved

tychedelia and others added 4 commits December 16, 2024 21:28

Update crates/bevy_asset/src/asset_changed.rs

04ae336

Co-authored-by: Chris Russell <8494645+chescock@users.noreply.github.com>

Remove changed from QueryState.

04561c6

Merge branch 'main' into changed-handle

cb15ff4

Add assert.

3ddbd18

tychedelia requested review from chescock, pcwalton and alice-i-cecile December 17, 2024 05:36

alice-i-cecile approved these changes Dec 17, 2024

View reviewed changes

pcwalton approved these changes Dec 17, 2024

View reviewed changes

alice-i-cecile added this pull request to the merge queue Dec 17, 2024

Merged via the queue into bevyengine:main with commit df14443 Dec 17, 2024
28 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `AssetChanged` query filter #16810

Add `AssetChanged` query filter #16810

tychedelia commented Dec 13, 2024 •

edited

Loading

Victoronz commented Dec 13, 2024 •

edited

Loading

tychedelia commented Dec 13, 2024

Victoronz commented Dec 13, 2024 •

edited

Loading

pcwalton Dec 13, 2024

tychedelia Dec 13, 2024

tychedelia Dec 14, 2024

tychedelia commented Dec 13, 2024

pcwalton commented Dec 13, 2024

alice-i-cecile Dec 14, 2024

tychedelia Dec 17, 2024

pcwalton left a comment

pcwalton Dec 17, 2024

tychedelia Dec 17, 2024

Add AssetChanged query filter #16810

Add AssetChanged query filter #16810

Conversation

tychedelia commented Dec 13, 2024 • edited Loading

Objective

Solution

Testing

Migration Guide

Victoronz commented Dec 13, 2024 • edited Loading

tychedelia commented Dec 13, 2024

Victoronz commented Dec 13, 2024 • edited Loading

pcwalton Dec 13, 2024

Choose a reason for hiding this comment

tychedelia Dec 13, 2024

Choose a reason for hiding this comment

tychedelia Dec 14, 2024

Choose a reason for hiding this comment

tychedelia commented Dec 13, 2024

pcwalton commented Dec 13, 2024

alice-i-cecile Dec 14, 2024

Choose a reason for hiding this comment

tychedelia Dec 17, 2024

Choose a reason for hiding this comment

pcwalton left a comment

Choose a reason for hiding this comment

pcwalton Dec 17, 2024

Choose a reason for hiding this comment

tychedelia Dec 17, 2024

Choose a reason for hiding this comment

Add `AssetChanged` query filter #16810

Add `AssetChanged` query filter #16810

tychedelia commented Dec 13, 2024 •

edited

Loading

Victoronz commented Dec 13, 2024 •

edited

Loading

Victoronz commented Dec 13, 2024 •

edited

Loading