Allow same-state transitions and add ChangeState system param

[benfrankel]

Objective

Fixes #9130.

Solution

Add a system param ChangeState<S> to set the next state depending on the current state. Remove the same-state check from apply_state_transition.

See #11158 for an alternative approach.

---

Changelog

• Added a system param ChangeState<S> to set the next state depending on the current state.
• Removed the check preventing state transitions from the current state to itself.

Migration Guide

NextState can now trigger state transitions from current_state to itself.

To preserve the old behavior, replace instances of next_state: ResMut<NextState<S>> with state: ChangeState<S>, and replace next_state.set(Foo) with state.change(Foo).

[benfrankel]

It might be worth updating examples to use ChangeState instead of ResMut<NextState>, but I'm not sure, so I haven't done that for now.

[MiniaczQ]

It might be worth updating examples to use ChangeState instead of ResMut<NextState>, but I'm not sure, so I haven't done that for now.

Looking for obscure wrappers is difficult without examples, good idea

[benfrankel]

I could also remove ChangeState::set_forced, since the name might be confusing, and you can get the same result with ChangeState::next.set or just NextState::set.

[benfrankel]

Renamed ChangeState::set to ChangeState::change, removed ChangeState::set_forced, and added ChangeState::reload to explicitly transition from the current state to itself.

Updated examples to use ChangeState instead of ResMut<NextState>, and added a restart on R press feature to the alien_cake_addict example.

[benfrankel]

I had an idea that might make the names more coherent. I won't include it in this PR, but figured I'd mention it anyways:

Rename State -> CurrentState, and ChangeState -> State. Then the relationship between the three types would be more obvious, and the most commonly used / most flexible type would have the shortest name. The downside is that it may obscure the fact that multiple systems taking state: State<S> can't run in parallel (because state.next: ResMut<NextState<S>>).

[MiniaczQ]

ChangeState -> State will be misleading. I think a more honest name would be NextState, but it's not worth the breaking change.

[benfrankel]

Closing as outdated after #11426.

The issue in #9130 persists, mentioned in the Future Work section of the computed states PR:

NextState::ReEnter - this would allow you to trigger exit & entry systems for the current state type. We can potentially also add a NextState::ReEnterRecursive to also re-trigger any states that depend on the current one.

Alternatively, a similar approach as in this PR may still be possible -- I haven't read through the computed states PR.