Entity Relations

[BoxyUwU]

RFC

warning: this PR does not implement all of the RFC and some of the RFC is out of date

cc #1527 #1592 #142

[BoxyUwU]

Future work after this PR: think about how relations should work with scenes

[BoxyUwU]

With the last commit this test now passes:

#[test]
fn query() {
    struct ChildOf;

    let mut world = World::new();

    let parent1 = world.spawn().id();
    let child1 = world.spawn().insert_relation(ChildOf, parent1).id();
    let parent2 = world.spawn().id();
    let child2 = world.spawn().insert_relation(ChildOf, parent2).id();

    let mut query = world.query::<(Entity, &Relation<ChildOf>)>();
    let mut iter = query.iter_mut(&mut world);
    assert!(iter.next() == Some((child1, ())));
    assert!(iter.next() == Some((child2, ())));
    assert!(iter.next() == None);

    query.set_relation_filter(
        &world,
        QueryRelationFilter::new().add_target_filter::<ChildOf, _>(parent1),
    );
    let mut iter = query.iter_mut(&mut world);
    assert!(iter.next() == Some((child1, ())));
    assert!(iter.next() == None);

    query.set_relation_filter(
        &world,
        QueryRelationFilter::new().add_target_filter::<ChildOf, _>(parent2),
    );
    let mut iter = query.iter_mut(&mut world);
    assert!(iter.next() == Some((child2, ())));
    assert!(iter.next() == None);
}

Still a lot of work to do but it's nice to see something working :O

[NathanSWard]

Would you have an abstract for the overall approach to your implementation?
E.g. talking about the move from ComponentId -> RelationKindId as well as the additional [ComponentID] -> [(RelationKindId, Option<Entity>)].
Having a high level overview of the implementation would make it a bit easier for some of us (me) to review the code 😄

[alice-i-cecile]

Would you have an abstract for the overall approach to your implementation?

These sort of design details are important to communicate clearly, and Boxy and I are aiming to write up the RFC mentioned in this PR's title Soon:tm: <3

This will be hard to review until then (and is deliberately a draft PR).

[bjorn3]

I think Entity should get a niche by for example making generation a NonZeroU32. This would make Option<Entity> just as big as Entity.

[BoxyUwU]

I actually want to remove all the Option<Entity> everywhere and just have a dedicated entity for the None case as it'll make a lot of the API nicer. It's kind of annoying to have to return or take Option<Entity> in places where 99% of the time it will be Some(..)

[BoxyUwU]

For example when setting the target filters on a Relation query param we currently just take an Entity but really we ought to be taking an Option<Entity>. Problem then is 99% of use cases have to wrap it in Some just because someone might want to query for the Nonecase...

I could take some T: Into<Option<Entity>> for that specific function but there are other places where this kind of pattern doesnt work, like the return type of the RelationAccess<T> iterator that returns the target entity- except the target Entity should actually be Option<Entity> but if I did that you'd either be unwrapping or doing a bunch of boilerplate to handle the None case :S

[bjorn3]

component_info and resource_info now contain an unnecessary bound check. It should never go out of bounds and many callers actually only need the ComponentId and not ComponentInfo.