Component Bundle Queries

[aevyrie]

What problem does this solve or what need does it fill?

Reduce the verbosity of queries by using bundles, which are already used for this purpose during entity archetype construction.

What solution would you like?

The ability to add a struct that derives Bundle to a query, and have it return with its fields accessible as components. E.g.:

#[derive(Bundle)]
struct Transform {
    translation: Translation,
    rotation: Rotation,
    scale: Scale,
}

// can still use this common case
Query<&Transform>

// but also, able to query fields granularly with change detection
Query<&Transform, Changed<Rotation>>
//...

// Can use this to group other sets of components as query-able bundles
#[derive(Bundle)]
struct Dog {
    legs: Legs
    fluffy_tail: Tail
    wet_nose: Nose
}
// These two queries are functionally equivalent, but the `Dog` query returns a list of `Dog` structs
Query<&Dog>
Query<(&Legs, &Tail, &Nose)>

What alternative(s) have you considered?

Most of this can already be achieved with some verbosity, as shown in the dog example above. However, it would also allow us to split apart common components like Transform into their parts with field level change detection, without losing the ergonomics of the Transform type.

Additional context

Similar to #786

[alice-i-cecile]

It seems clear that when operating in this way, With and Without should use AND logic.

However for Added / Changed / Removed (see #2148), the intuitive behavior is actually different.

For Added, it should trigger if and only if the entity now satisfies the With criteria, and did not before. Removed is then the opposite.

For Changed, it should trigger if any of the components are changed, which is a both intuitive and a nice ergonomic win for Or-logic query filtering in the most common cases.

[alice-i-cecile]

This is almost certainly blocked on #1843, as otherwise we have no way to differentiate whether you want to query for a bundle as a bundle or a component. This may result in overlapping impl errors for attempts to have types as both a bundle and a component, but in my book that's a serious win for clarity (even if bevy_rapier uses this pattern right now).

Note that the granular fields (and ability to split components apart) actually allow this to enable nontrivial functionality and performance enhancements. We can get more granular change detection, which is very useful for some expensive algorithms, and also reduce the data that must be accessed when only handling one part of a larger component.

This would also be very useful for things along the lines of the massive Style component, particularly with archetype invariants (#1481) to guard against misconfiguration.

To break down the desired behavior a bit, I think it should work like so when iterated over.

let query = Query<&Transform>

for (translation, rotation, scale) in query.iter(){

}

let query = Query<(&Life, &Transform)>

for (life, transform) in query.iter(){
  transform.rotation += 0.2;
}

And maybe even:

let query = Query<(&Life, &Transform)>

for (life, (translation, rotation, scale)) in query.iter(){
  rotation += 0.2;
}

Note that this syntax is actually likely to result in extremely minimal code breakage for existing users of Transform. Combining this with #1843 would result in serious ergonomic gains, as querying for a bundle would result in an actual effect (if sometimes wasteful), and users could use rust-analyzer's type inference to guide them on what is likely to actually result when the query is unpacked.

[aevyrie]

To break down the desired behavior a bit, I think it should work like so when iterated over.

let query = Query<&Transform>

for (translation, rotation, scale) in query.iter(){

}

I think I'd actually prefer it if the query returned the struct, though I'm not sure which is easier to implement. One reason to return the struct is because you can then implement methods for the bundle, it would also mean this isn't (as much of) a breaking change, because querying a Transform would still return a Transform.

[alice-i-cecile]

Ah, there was a fourth case I forget to mention:

let query = Query<&Transform>

for transform in query.iter(){

}

As I'm trying to hint at by example, the idea is that the compiler either keeps the struct intact or automatically unpacks it based on the number of arguments it has to match against.

[alice-i-cecile]

As part of this change, we could remove WithBundle, cleaning up our API in a more consistent way.

[alice-i-cecile]

Currently the bundle filter will match anything that has all components in a bundle, but imo the filter would be more useful / aligned with user intent if it only matched things that actually added the Bundle.

• @cart in Condense insert / insert_bundle and related methods #2255

I really dislike this behavior: it's incredibly magical, special-cases bundles and forces us to store Bundle identity on the entity. Instead, I would prefer to promote the use of "defining" marker components as the first item of each bundle.

This is a natural and useful pattern in end-user code, and you can get the effect you're looking for because no other entities should have that unique marker unless they include the bundle (especially if you don't export the marker's type).

The other benefit of that design is that it dovetails really nicely with the entity inspection patterns discussed in #1467, particularly for a visual editor, where you want to quickly learn the "types" of an entity (in which case you look at the "defining" components of the bundle).

[aevyrie]

I responded in #2255 here, but I will reiterate my perspective here.

In short, my desired behavior for bundle queries is:

Match anything with all components in the bundle (a bundle filter), but return the result from the query as the bundle struct. This retains the current composability of entities, adds the ergonomics of allowing traits/methods over bundles, without the magic of bundles being semantically "special".

I also agree with @alice-i-cecile in that I don't like bundles being "special-cases" or "magical". I mostly don't like that it directly interferes with the composability that we get with only defining archetypes from components.

[mockersf]

let query = Query<&Transform>

for (translation, rotation, scale) in query.iter(){

}

Rust as while let loop that would do this destructuring nicely.

This works today:

let query = Query<&Transform>

while let Some(Transform {translation, rotation, scale}) = query.iter().next() {

}

It gets a little uglier for a mut query though (because we can't destructure Mut):

let mut query = Query<&mut Transform>

while let Some(Transform {
    _translation,
    rotation,
    _scale,
}) = query
    .iter_mut()
    .next()
    .map(|mut_wrapper| Mut::into_inner(mut_wrapper))
{
    *rotation = Quat::from_rotation_z(time.seconds_since_startup().cos() as f32);
}

I think that doing the destructuring ourselves as in @alice-i-cecile example would be very hard (not possible?), as you lose the type relation between the query type and what it returns