Change SceneInstanceReady to trigger an observer.

[komadori]

Objective

The SceneInstanceReady event would be more ergonomic (and potentially efficient) if it could be delivered to listeners attached to the scene entities becoming ready rather than into a World-global queue.

This is an evolution of @Shatur's work in #9313.

Solution

The scene spawner is changed to trigger observers on the scene entity when it is ready rather than enqueue an event with EventWriter.

This addresses the two outstanding feature requests mentioned on #2218, that i) the events should be "scoped" in some way and ii) that the InstanceId should be included in the event.

Testing

Modified the scene_spawner::tests::event test to use the new mechanism.

---

Changelog

• Changed SceneInstanceReady to trigger an entity observer rather than be written to an event queue.
• Changed SceneInstanceReady to carry the InstanceId of the scene.

Migration Guide

If you have a system which read SceneInstanceReady events:

fn ready_system(ready_events: EventReader<'_, '_, SceneInstanceReady>) {

It must be rewritten as an observer:

commands.observe(|trigger: Trigger<SceneInstanceReady>| {

Or, if you were expecting the event in relation to a specific entity or entities, as an entity observer:

commands.entity(entity).observe(|trigger: Trigger<SceneInstanceReady>| {

[janhohenheim]

This makes a lot of sense. Could you add some documentation to SceneInstanceReady describing how to interact with it now?

[komadori]

This makes a lot of sense. Could you add some documentation to SceneInstanceReady describing how to interact with it now?

@janhohenheim Good idea. I feel that "triggered" is the right verb for observers instead of "emitted". I added bevy_ecs::observer::Trigger to the see also section.

/// Triggered on a scene's parent entity when [`crate::SceneInstance`] becomes ready to use.

Alternatively, this just occurred to me, I could rewrite it as follows and work the word "observer" in there but I think it's a bit more cumbersome:

/// A [`Trigger`] for observers on a scene's parent entity when [`crate::SceneInstance`] becomes ready to use.

[janhohenheim]

@alice-i-cecile do we have some guideline for how to document something triggering observers?

[alice-i-cecile]

Not yet!

[alice-i-cecile]

I agree: observers are a much nicer pattern here.

[alice-i-cecile]

@komadori merge conflicts are non-trivial. Can you please resolve them and then ping me? <3 I'd like to merge this in.

[komadori]

@alice-i-cecile I've merged in main. The conflicts were caused by #11741 adding more situations in which the SceneInstanceReady event was sent. I've converted events from parent-less scene spawns into non-targeted observer triggers. Added more tests for dynamic scenes.

[alice-i-cecile]

Fantastic work: I'm quite pleased with the end result.