Add more tools for traversing hierarchies

[alice-i-cecile]

Objective

• Working with hierarchies in Bevy is far too tedious due to a lack of helper functions.
• This is the first half of Add more tools to conveniently work with hierarchies, especially in the presence of ghost nodes #15609.

Solution

Extend HierarchyQueryExt with the following methods:

• parent
• children
• root_parent
• iter_leaves
• iter_siblings
• iter_descendants_depth_first

I've opted to make both iter_leaves and iter_siblings collect the list of matching Entities for now, rather that operate by reference like the existing iter_descendants. This was simpler, and in the case of iter_siblings especially, the number of matching entities is likely to be much smaller.

I've kept the generics in the type signature however, so we can go back and optimize that freely without a breaking change whenever we want.

Testing

I've added some basic testing, but they're currently failing. If you'd like to help, I'd welcome suggestions or a PR to my PR over the weekend <3

[villor]

Did a PR with fixed siblings iter.

The problem was that the query has to be Query<(Option<&Parent>, Option<&Children>)> since we are using the same query for the parent and children.

Also got rid of the SiblingsIter since it wasn't really necessary. Instead we got a ugly mess of into_iter().flat_map(), but at least it won't allocate anymore 😅

I wonder if it would be a good idea to convert HierarchyQueryExt into system params instead 🤔 what is the reason it is an extension in the first place?

[alice-i-cecile]

I wonder if it would be a good idea to convert HierarchyQueryExt into system params instead 🤔 what is the reason it is an extension in the first place?

I'm pretty sure it predates the SystemParam derive macro, and has grown organically from there. I really like the filtering capabilities, but I agree: I think that the SystemParam approach is a lot simpler as both a user and a maintainer. Adding a filter generic should be totally doable. Follow-up though!

[villor]

@alice-i-cecile

Pushed some more commits, PR here

• Cleaned up my previous flat_map->into_iter chaos. Much more readable now!
• Made sure children() returns a slice like the doc comment says, and cleaned up the implementation.
• Renamed root_parent -> root_ancestor
• Removed LeafIter and instead return the traversal iterator directly (reducing allocations)
• Added a doc comment about the iter_leaves traversal order. (Would it make sense to make this one traverse depth-first instead for the "correct" order?)

Edit: Here's another PR which also adds depth-first and changes iter_leaves to use it.

[alice-i-cecile]

@villor you're the best. I really appreciate your help with this!

[bushrat011899]

Like the options this provides, and helps justify the existence of what is otherwise a pretty small crate! I do think this should be refactored into a SystemParam, but that's a larger change that can easily be built on top of this work in 0.16. I also see a lot of refactoring in the near future anyway with #15635, so no real need to do that here and now.

[villor]

Like the options this provides, and helps justify the existence of what is otherwise a pretty small crate! I do think this should be refactored into a SystemParam, but that's a larger change that can easily be built on top of this work in 0.16. I also see a lot of refactoring in the near future anyway with #15635, so no real need to do that here and now.

SystemParam is going to be the bomb! I imagine we could add other APIs as well like change detection on different parts of the hierarchy. A lot more options open up once we can control the queries more 😁

And when we have #15635 we can make it generic over any one-to-many relation!

[alice-i-cecile]

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1718 if you'd like to help out.