Add a RelatedTo filter for querying relations

[alice-i-cecile]

Objective

Looking for entities that have a parent (or other relationship) where the parent meets some filter is a common task.

Part of #17647.

Solution

Make it easier by adding a RelatedTo type which implements QueryFilter.

Tasks:

• create the basic type
• successfully implement WorldQuery and QueryFilter
• add comprehensive tests
• extend documentation
• ensure tests pass and implementation is correct

Testing

I've added a number of unit tests (and a simple doc test) checking this implementation against various forms of query filters.

[alice-i-cecile]

Currently, WorldQuery::shrink is complaining about:

lifetime may not live long enough
consider adding the following bound: 'wshort: 'wlong

And WorldQuery::fetch is complaining about:

lifetime may not live long enough
consider adding the following bound: 'wshort: 'wlong
requirement occurs because of the type RelatedToFetch<'_, R, F>, which makes the generic argument '_ invariant
the struct RelatedToFetch<'w, R, F> is invariant over the parameter 'w
see https://doc.rust-lang.org/nomicon/subtyping.html for more information about variance

Obviously, neither of those suggestions are good ('short must be less than 'long!), but I'm not immediately sure how to fix it.

[chescock]

Currently, WorldQuery::shrink is complaining about:

lifetime may not live long enough
consider adding the following bound: 'wshort: 'wlong

And WorldQuery::fetch is complaining about:

I think you need to call F::shrink(item) and do something like

RelatedToFetch { 
  relation_fetch: <&R>::shrink_fetch(fetch.relation_fetch),
  filter_fetch: F::shrink_fetch(fetch.filter_fetch),
}

The implementations that have concrete types can just return item and fetch because the compiler knows the concrete types are covariant. Here we have associated types on generic parameters, so the compiler assumes they might be invariant and we have to call the shrink methods explicitly.

[alice-i-cecile]

Given the test pattern, I suspect that this method is wrong, but I can't figure out why.

[alice-i-cecile]

Alright, I think I've figured out the core of what's going wrong here and why some tests pass but others fail. Take this with a grain of salt and correct me: I'm not particularly familiar with manual implementations of WorldQuery.

The key pair of tests to look at is related_to_with (fails) and related_to_with_same_archetype (passes?!).

In order for WorldQuery::fetch to work correctly, we must first set the table / archetype correctly, via WorldQuery::set_table. Unfortunately, the right table is different based on whether we're looking at the base entity (e.g. child) or the target entity (e.g. parent). This means that the case demonstrated in the related_to_with component fails to match the right archetype, and QueryFilter::filter_fetch / WorldQuery::fetch is never called at all. I tested this by sticking a panic in the fetch method: it's not hit for the failing tests.

However, when we share components between the base and target entities, we can accidentally look at the right archetypes, and then WorldQuery::fetch functions as intended.

As for the fix, I'm really not sure. WorldQuery is really designed to operate on only a single entity at once, hence the set_archetype / set_table design. We could relax that, but I worry that the performance characteristics would be untenable. We can find out though!

We could instead swap this over to a SystemParam type, but that's really not much better than the existing query helpers: the WorldQuery impl here / in the linked issue are key to the power and ergonomics.

P.S. I don't think that the API as designed here would work with archetypal relations either 🤔 The core problem is that we need to look at a different table halfway through WorldQuery::fetch, and that method doesn't have access to the parameters required to call set_archetype and/or set_table.