Upstream reflect_query

[nicopap]

Read the cuicui_reflect_query README for motivation.

https://crates.io/crates/cuicui_reflect_query

Objective

Bevy's ReflectComponent allows extracting a value from a EntityRef or
EntityMut, this can be useful, but generally not enough.

ReflectComponent is missing ways to query for the reflected thing.
Without this ability, you would be stuck iterating over all EntityRef and
checking if it contains the component in question. This is O(n) (where n is
the total count of entities) while querying just for a single entity is O(1).

Solution

1. Split the reflect.rs module in bevy_ecs into smaller parts.

2. Add the following methods to ReflectComponent:

• reflect_ref: This is similar to ReflectComponent::reflect, but also includes
  change tick data. This allows reading change ticks on the reflected component
  in an immutable way.
  
  Furthermore, the reflect_mut method has lifetime limitations, this might be a good
  way to work around them.
• query{,_entities,_ref,_mut}: Iterate over all entities with the reflected component.
  Like with world.query, you need to call .query(world) on the return value
  to iterate over the query results.
• get_single{,_entity,_ref,_mut}: similar to world.get_single, it will return
  a value only if there is exactly one entity containing the reflected component.

A bit of precision:

• The _entity variants return an Entity or an iterator of entities instead
  of the dyn Reflect version of the component.
• The _ref variants return a Ref<_> over _, this let you read change information
  in an immutable maner.

// In ReflectComponentFns
    pub reflect_ref: fn(EntityRef) -> Option<Ref<dyn Reflect>>,

    pub get_single: fn(&mut World) -> SingleResult<&dyn Reflect>,
    pub get_single_entity: fn(&mut World) -> SingleResult<Entity>,
    pub get_single_ref: fn(&mut World) -> SingleResult<Ref<dyn Reflect>>,
    pub get_single_mut: fn(&mut World) -> SingleResult<Mut<dyn Reflect>>,

    pub query: fn(&mut World) -> Querydyn,
    pub query_entities: fn(&mut World) -> EntityQuerydyn,
    pub query_ref: fn(&mut World) -> RefQuerydyn,
    pub query_mut: fn(&mut World) -> MutQuerydyn,
}

Similar work

• Allow configuration of WorldQuery with runtime values #6390

---

Changelog

• Added methods on ReflectComponent to allow querying from a World the components in question:
  • reflect_ref: fn(EntityRef) -> Option<Ref<dyn Reflect>>,
  • get_single: fn(&mut World) -> SingleResult<&dyn Reflect>,
  • get_single_entity: fn(&mut World) -> SingleResult<Entity>,
  • get_single_ref: fn(&mut World) -> SingleResult<Ref<dyn Reflect>>,
  • get_single_mut: fn(&mut World) -> SingleResult<Mut<dyn Reflect>>,
  • query: fn(&mut World) -> Querydyn,
  • query_entities: fn(&mut World) -> EntityQuerydyn,
  • query_ref: fn(&mut World) -> RefQuerydyn,
  • query_mut: fn(&mut World) -> MutQuerydyn,
• Added EntityRef::get_ref to get a value + change tick.
• Updated Ref::map method to accept unsized Us

[alice-i-cecile]

It sounds like there could be a map_absent_entities method built in to abstract over this pattern.

[alice-i-cecile]

Doc links please.

[alice-i-cecile]

I like the split, docs are excellent. I think this makes more sense upstream in Bevy than as a third-party crate. This is effectively the last missing piece to making dynamic components work properly.

Macro-generated docs are a bit controversial, but I'm fine with them here.

I'd like to see:

• tests
• an end user example that demonstrates a semi-realistic use of this for teaching and API evaluation purposes
• expanded module level docs to explain what reflection is and why users might actually care

[nicopap]

yeah FYI I'm not sure this deserves being merged. I won't spend much time on this unless there is a clear interest from various people.

I think a solution similar to #6390 is closer to what we want. There is no reasons we can't have a QueryState with dynamic values.

I'll probably open a PR to split the reflection.rs file though, it's kind of a nice code cleanup.

[alice-i-cecile]

I'll probably open a PR to split the reflection.rs file though, it's kind of a nice code cleanup.

I agree, this should be done regardless and is best suited to a quick merge.

[nicopap]

Superseded by #9774