Entity path methods and bsn entity path resolving

[Freyja-moth]

Objective

Fixes: #16201

Originally based on and closes: #20848

Solution

Add two to methods to world

fn get_entity_from_path<R: Relationship, C: Component + PartialEq + Clone>(
    &self,
    root: Option<Entity>,
    path: &[C],
) -> Option<Entity>;
fn get_path_from_entity<R: Relationship, C: Component + PartialEq + Clone>(
    &self,
    root: Option<Entity>,
    entity: Entity,
) -> Option<Vec<C>>;

Original methods were taken from #20848, but changed to focus on bottom up search instead of a top down search, which should hopefully be more efficient and made them generic over the relationship.

Also added an EntityPath variant to EntityTemplate.

Testing

Tests included and working.

Showcase

#[derive(Component)]
#[relationship(relationship_target = WieldedBy)]
pub struct Weapon(pub Entity);

#[derive(Component)]
#[relationship_target(relationship = Weapon)]
pub struct WieldedBy(Entity):

fn player() -> impl Scene {
    bsn! {
        Player
        Weapon("Items/Weapons/Sword")
    }
}

[Freyja-moth]

Small note, should I change the methods to have more descriptive errors?

[Freyja-moth]

Currently using an immutable borrow of world.

This does cause it to return None if the relationship component or compared component aren't registered, but that should be fine since if either weren't registered they don't exist in the world and therefore the path was invalid anyways.

[alice-i-cecile]

I quite like this idea in practice: this seems extremely useful for both animation and UI. However, I think there are two important cleanups to do:

1. Make the error handling better.
2. Extract out a pair of common case methods, and give those the nice names.

[github-actions]

It looks like your PR has been selected for a highlight in the next release blog post, but you didn't provide a release note.

Please review the instructions for writing release notes, then expand or revise the content in the release notes directory to showcase your changes.

[Freyja-moth]

Moved the previous methods to get_entity_from_relationship_path and get_relationship_path_from_entity, then made the methods specialize on ChildOf.

Not fully happy with the names so welcoming bikeshedding.

[Freyja-moth]

Will fix whatever issues come up tomorrow, I've spent way too much time on this tonight.

[alice-i-cecile]

I'm happy with this now, but it still needs a test for the BSN usage.

The release note is super exciting: what an incredibly useful thing to do on cold paths. I've left a few suggestions to improve it.

Good luck with CI 🫡

[Freyja-moth]

With any luck this should be the last of the changes.

[Freyja-moth]

Ci passed, I'm free!

[beicause]

The implementation differs from the PR description; the path is &str instead of &[C]. What's the reason?

I feel the performance may not be fast, as it involves String and Vec allocations and string comparisons in the loop.

[Freyja-moth]

The implementation was changed in response to feedback and I forgot to change the pr description.

As for performance implications, the loop is only ran on all entities that match the top element of the path which shouldn't be too many, and since most usecases will be for initializing scenes, which only happens once and usually with other elements it's probably fine.

If you can find a more optimal way of searching feel free to open a pr after this one.