Insert children

[bjoernp116]

Objective

This PR implements the requested, previously deprecated feature from #17478. Which is concerning the insert_children of EntityWorldMut. This method inserts children into the tree, at a specific index.

Solution

I mostly copied the code from the deprecated crate bevy_hierarchy though this is no longer a trait method.
This code also used SmallVec which has later been switched by Vec. This was easily interchangeable with working code.

Testing

I wrote a unit test covering both EntityWorldMut::add_entities and EntityWorldMut::insert_entities, simply called hierarchy::tests::insert_children. I was unsure what error handling architecture i should be using, but i think the simplest to debug in this case would just be a panic in the case of an index out of bounds.

Showcase

I find this feature pretty self exoplanetary, but the unit test can also bee informing about what this feature implements:

Click to view showcase

let mut world = World::new();
let child1 = world.spawn_empty().id();
let child2 = world.spawn_empty().id();
let child3 = world.spawn_empty().id();
let child4 = world.spawn_empty().id();

let mut entity_world_mut = world.spawn_empty();

let first_children = entity_world_mut.add_children(&[child1, child2]);

let root = first_children.insert_children(1, &[child3, child4]).id();

let hierarchy = get_hierarchy(&world, root);
assert_eq!(
     hierarchy,
     Node::new_with(root, vec![Node::new(child1), Node::new(child3), Node::new(child4), Node::new(child2)])
);

[github-actions]

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

[BenjaminBrienen]

Fixes #17478

[BenjaminBrienen]

What happens if the entity is already a child? As a user, I'd like to know whether that is okay ok or not. For example, does doing so reorder it?

[cart]

This does not update the other side of the relationship (ChildOf), invalidating the assumptions of the system as a whole.

[alice-i-cecile]

@bjoernp116 this is a blocker to 0.16; are you interested in finishing this up in the next week or two? Totally fine if not; we can always get someone else to finish this.

[marko-lazic]

Is it possible to change the return to Bevy Result and then return Err() here?

[alice-i-cecile]

Closing as adopted <3 Thanks for getting started on this!