Implements merge_scene variant function.

[l-monninger]

Objective

• Allow the user to control relationship updates by giving the option to merge children (extend relationships generally).
  • As referenced in Documents and regression tests apply scene replace and orphan behavior. #24909, the current behavior of apply_scene is to replace and orphan children.
  • Compare with stacked PR Implements priority pattern "scene then entity then default" for RelationshipBehavior on apply_scene ramate-io/bevy#2 for further control of relationship behavior.

Solution

Critically:

    fn patch_scene<S: Scene>(
        &mut self,
        scene: S,
        relationship_behavior: RelationshipBehavior,
    ) -> Result<(), SpawnSceneError>;

    fn apply_scene<S: Scene>(&mut self, scene: S) -> Result<(), SpawnSceneError> {
        self.patch_scene(scene, RelationshipBehavior::Overwrite)
    }

    fn merge_scene<S: Scene>(&mut self, scene: S) -> Result<(), SpawnSceneError> {
        self.patch_scene(scene, RelationshipBehavior::Merge)
    }

• I used default implementations on the trait to extend marker behavior to a variant function merge_scene.

Testing

• See unit tests at the bottom of spawn.rs.

Draft Notes

As we start to consider this feature, I would like to note there are, in fact, several potentially configurable behaviors:

1. Do we want to overwrite or extend the relationships? (This is the RelationshipBehavior provided here.)
2. If we are overwriting relationships, do we want to orphan exiting relationships or despawn them? (RelationshipGc)
   • Do we want to despawn certain types of relationships? Entities matching certain bundles?
   • At what point does controlling this sort of thing become better as some kind of bespoke system?
3. Is the RelationshipBehavior used material? (MaterializeRelationshipBehavior)
4. If RelationshipBehaviors are material, does the pre-existing RelationshipBehavior or the behavior entering with the scene take precedence?