Add more query join types (left, right, outer join)

[alice-i-cecile]

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

The query join added in #11535 is useful, but only covers one of four common types of queries.

As discussed in #1658, these are:

1. Inner join: matches all entities that are found in both queries.
2. Outer join: matches all entities that are found in either query.
3. Left join: matches all entities that are found in the first query.
4. Right join: matches all entity

The join added in the PR above is an "inner join", which is useful and straightforward to implement.
However, this isn't always the desired behavior.

We should learn from the extensive history of database and implement this foundational functionality.

What solution would you like?

Add the other join type methods, being clear that the base join is an inner join.

Data that is missing should be filled with None, and the fields that could be missing should be converted to their Option equivalents.

What alternative(s) have you considered?

Maybe these join types aren't useful in practice in game dev and can just be omitted.

I had hoped that Query::join could take an extra parameter, the JoinType enum. However, I don't think that this is feasible, as the type returned varies based on the value based in. Perhaps a const generic would work, but that's blocked on rust-lang/rust#95174 for now.

[Adamkob12]

I like the idea of joining queries on component values, e.g:
join (&Enemy, &Transform) and (&Player, &Transform) on distance(enemy.transform, player.transform) < 30.0
which would in turn yield ((&Enemy, &Transform), (&Player, &Transform)).

But I'm not sure on how useful joining queries on entities is. Correct me if I'm wrong, but it seems like even the example given for Query::join is longer, slower and more complicated than what it would be if Query::join wasn't used at all.

Is there an example where joining queries on entities provides some utility that can't be or is much harder to achieve right now?

[alice-i-cecile]

Much like query transmutes, the value comes in much more complex use cases. Scripting APIs and helper methods are relatively common applications, but it's really hard to show the value in out of context snippets.

[alice-i-cecile]

For outer joins, @ChristopherBiscardi had a nice example where a user can recombine mutually exclusive queries without a ParamSet:

fn burn(
    all_burned: Query<&Burned>,
    all_grass_type: Query<Entity, With<&GrassType>>
    all_non_grass_type: Query<Entity, Without<&GrassType>>
) {
    let critical_burn_effect: QueryLens<&Burned, Entity> = all_burned.join(all_grass_type);
    for (burn, entity) in &critical_burn_effect {
        // dmg = 2.
    }

    let burn_effect: QueryLens<&Burned, Entity> = all_burned.join(all_non_grass_type);
    for (burn, entity) in &burn_effect {
        // dmg = 1
    }
}

[alice-i-cecile]

We could consider using query.union, query.intersection and so on for the naming, and base it off of set operations.

[alice-i-cecile]

Public prior art for this: https://github.com/NicoZweifel/bevy_spliff

@NicoZweifel, let us know if you're interested in upstreaming this yourself (or opposed to us doing so).

[NicoZweifel]

Public prior art for this: https://github.com/NicoZweifel/bevy_spliff

@NicoZweifel, let us know if you're interested in upstreaming this yourself (or opposed to us doing so).

I would love to. Im not sure I would wanna do it in the current state though.

I want to update it to use the dev branch and nested queries and I'm not completely happy with the api/filtering yet. Mutability is also something I didn't really tackle (I want to after doing nested queries).

Afterwards I'd wanna add benchmarks and review the unsafe ecs access again at some point.

Feel free to use it in any way you want. Its basically the result of a 2 day hyperfocus experiment lmao so its def sitting at < 80% completed and needs some more work imo.

I'd be happy to contribute to an upstream implementation but Im totallly fine with someone else leading the efforts as well.

[alice-i-cecile]

Sounds good! I was pointed towards it, was impressed, and wanted to record it somewhere useful.

Let us know when you think it's "ready" :)

[NicoZweifel]

Sounds good! I was pointed towards it, was impressed, and wanted to record it somewhere useful.

Let us know when you think it's "ready" :)

I have updated it to use the dev branch and NestedQuery, although I had to point it to my fork to use the fields of NestedQueryFetch.

I could create a PR to make the fields public, so that implementing custom variants is possible in general or start work on a plan to upstream a version of this.

Currently I need the field access in the QueryData impl of Join to make this work, although I am not opposed to doing it another way if the fields have to be private or if there is a better way:

    #[inline(always)]
    unsafe fn fetch<'w, 's>(
        (_, state): &'s Self::State,
        fetch: &mut Self::Fetch<'w>,
        entity: Entity,
        _table_row: TableRow,
    ) -> Option<Self::Item<'w, 's>> {
        let r = unsafe { fetch.world.get_entity(entity).ok()?.get::<Ref>()? };
        let Self::Fetch {
            world,
            last_run,
            this_run,
            ..
        } = fetch;

        let res = r.targets().filter_map(move |target| unsafe {
            state
                .query_unchecked_manual_with_ticks(*world, *last_run, *this_run)
                .get_inner(target)
                .ok()
        });

        Some(Ref::Mapper::map_results(res.collect()))
    }