Add state scoped events

[UkoeHB]

Objective

• Improve robustness of state transitions. Currently events that should be scoped to a specific state can leak between state scopes since events live for two ticks.
• See StateScoped should support OnRemove observers #15072

Solution

• Allow registering state scoped events that will be automatically cleared when exiting a state. This is most of the time not obviously useful, but enables users to write correct code that will avoid/reduce edge conditions (such as systems that aren't state scoped polling for a state scoped event and having unintended side effects outside a specific state instance).

Testing

Did not test.

---

Showcase

Added state scoped events that will be automatically cleared when exiting a state. Useful when you want to guarantee clean state transitions.

Normal way to add an event:

fn setup(app: &mut App) {
    app.add_event::<MyGameEvent>();
}

Add a state-scoped event (NEW):

fn setup(app: &mut App) {
    app.add_state_scoped_event::<MyGameEvent>(GameState::Play);
}

[MiniaczQ]

Nice seeing more people jump on the state boat :)
State scoped events was something I wanted to add, but wasn't quite sure how, I like this approach.
I like the implementation, but we could use an example for discoverability.

For the future, we should consider that events E can be generate outside of state S and figure out how to deal with that:

1. Also cleanup on entry (ever growing queue if we never enter S)
2. Lock the event queue, no-op write attempts
3. Remove the event queue resource and add falliable methods to writers/readers

[alice-i-cecile]

Okay, I'm on board. This is a consistent, simple extension with predictable behavior.

[UkoeHB]

Also cleanup on entry (ever growing queue if we never enter S)

@MiniaczQ there are are a couple things to consider: events that might be sent into a state, and events sent during OnEnter. The later can be solved by only clearing before OnEnter runs, and the former can maybe be solved by making it opt-in (although that would introduce API complexity). In general I expect state-scoped events to be generated and consumed within that state (since that's their scope - i.e. the only region where the events actually make any sense).

[MiniaczQ]

Also cleanup on entry (ever growing queue if we never enter S)

@MiniaczQ there are are a couple things to consider: events that might be sent into a state, and events sent during OnEnter. The later can be solved by only clearing before OnEnter runs, and the former can maybe be solved by making it opt-in (although that would introduce API complexity). In general I expect state-scoped events to be generated and consumed within that state (since that's their scope - i.e. the only region where the events actually make any sense).

Yeah, lots to consider, we can start by merging this :)