`WorldQuery` types for working with relationships

[alice-i-cecile]

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

Working with relationships in Bevy is cumbersome, requiring multiple queries, manual iteration and repeated calls to Query::get to correlate the information about the relationship graph with the data you actually want to fetch.

This is particularly annoying in the context of exclusive world access, as keeping multiple queries alive at once requires the use of SystemState.

Many of these systems follow very common patterns: surely we can write simple abstractions over them.

What solution would you like?

Add 4 query filter types:

• RelatedTo<R: Relationship, F: QueryFilter>: is this entity related to an entity that matches the query filter?
• Scan<RT: RelationshipTarget, F: QueryFilter>: do any of the entities which are related to this entity match the query filter?
• WithAncestor<R: Relationship, F: QueryFilter>: is this entity transitively related to any entities (searching up recursively) that match the given query filter?
• WithDescendant<RT: RelationshipTarget, F: QueryFilter>: do any of the entities which are transitively related to this entity (searching down recursively) match the query filter?

Implementation note: both WithAncestor and WithDescendant are naively O(N^2). We can cache the decisions made and check the cache to reduce that to O(N). That doesn't have to be in the first PR.

Add an initial query data type:

• Related<R: Relationship, D: QueryData>: fetch the data of type D from the entity that this entity is related to via R.

Note that Option<Related<R, D>> is extremely useful for looking up data if and only if it exists.

Finally, add a type alias

• type Parent<D: QueryData> = Related<R: ChildOf, D: QueryData>

What alternative(s) have you considered?

Users who need these helpers can continue to work with multiple queries per system. This is not very pleasant, and often obscures meaning.

Alternatively, these helpers should generally be implementable outside of bevy_ecs. Doing so is a non-trivial amount of work, and requires fairly complex unsafe code.

Additional context

These query helper types build on the work in #17398; while they are intended to be ergonomic, pleasant to work with and forward-compatible, performance is a secondary concern. Archetypal relations (as seen in flecs, or proposed as part of #17564) would likely improve the speed of many of these operations.

These types were first designed in https://hackmd.io/UCyLaF4YStC0cTSE8Fm7cw, and discussed on Discord.

[alice-i-cecile]

After exploring this in #17649, I quickly discovered that WorldQuery and friends really only want to look up data from a single entity at once. This applies to both the current non-fragmenting relations, as well as any future archetypal relations APIs to do the same sort of thing.

In order to unblock this flavor of API (which I still think is very elegant and intuitive and would make Bevy code easier to read and write!), we need to modify how WorldQuery::fetch works, to allow changing the table / archetype we're looking at halfway through. This will both a) be fairly slow and b) pose serious soundness risks. If you're keen on tackling this, pull together a working group please so we can carefully design and get multiple sets of eyes on any implementation.

[Mantissa-23]

Just wanted to chip in that I think this is really important to ergonomically defining behavior for any nontrivial game concept, i.e. i.e. a player's camera, a player's weapon, UI that gets synchronized with world state, etc.

In my Godot projects, I use similar functions such as FindInParent<T>, FindInOwners<T>, as well as Godot's built-in "Unique Name" to get specific nodes within a scene.

In my mind these query filter types satisfy the same needs in Bevy's ECS. Feels like this is the missing link to make Relationships really feel like a first-class implementation.