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>| {

[mnmaita]

Just a minor observation (no pun intended 😅) unrelated to the PR changes:

I see that Trigger is defined like this: pub struct Trigger<'w, E, B: Bundle = ()>

Yet E is not required to be an Event. Wondering if this an oversight or was it on purpose? Would Trigger<SceneInstanceReady> still work if SceneInstanceReady doesn't derive Event?

World method signatures are taking generic params or function params like this:

pub fn observe<E: Event, B: Bundle, M>
pub fn trigger(&mut self, event: impl Event)

So maybe adding this constraint would be correct? I'll create a PR with said change but still wanted to write it down somewhere so I don't forget.

[komadori]

On a related note: Event is just a marker trait. So, assuming that the EventReader<> functionality will continue to coexist with Trigger<>, I would have thought that "classic" events and observer events should use separate marker traits. I'm not sure what you'd name them though.

[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!