Use hooks + immutable components pattern for state transitions

[alice-i-cecile]

What problem does this solve or what need does it fill?

The current schedule-based approach to state transitions is messy.
It allows for system ordering ambiguities (#13947), and forces users to reason about a once-per-frame StateTransition schedule (which other crates may add more copies of).

State transitions hold important global invariants: we should use our new tools to make it easier (and more consistent) to reason about them.

What solution would you like?

1. Remove the StateTransition schedule.
2. Make State<T> immutable (blocked on Store resources as components on singleton entities #17485).
3. Remove NextState, and make users change states via commands.
4. Use hooks to call the OnEnter/OnExit/OnTransition schedules when the state changes.
5. Remove .init_state in favor of simply calling .init_resource on states. (Use a deprecation notice to make this easier).

What alternative(s) have you considered?

#18562 discusses the possibility of adding another schedule before the initial state transition to allow for startup systems to run before states are entered.

I feel strongly that we shouldn't do this: it should be impossible to be in a state without its on-enter systems to be called (and similarly for on-exit). Instead, we should enforce this invariant as strongly as possible, and ensure that users have the tools needed to delay entering into states until any requisite setup is complete.

Additional context

Note that this conflicts with the desire to run something before states are entered stated in #18562. However, users could simply initialize their starting states in a system during Startup, rather than calling .init_state.

[benfrankel]

Does using hooks here imply that the transition schedules would run in the next sync point immediately after a user changes the state? If so, I believe that would create more issues than it solves, with states changing potentially several times mid-frame.

[alice-i-cecile]

By default yes, but not necessarily. We can change that behavior by emitting a custom command, or retaining NextState.

I believe that would create more issues than it solves, with states changing potentially several times mid-frame.

Can you explain more about why this is a problem?

[benfrankel]

Can you explain more about why this is a problem?

States are often used for determining what logic should run in a given frame via run conditions. Having the app pass through multiple states in the same frame would make this harder to reason about. Also, some state transitions can be costly, like loading assets or spawning / despawning many entities, and you wouldn't want to do this multiple times per frame.

I think it could be reasonable to provide users the option to trigger a state transition mid-frame, as long as the default behavior is the current frame-deferred behavior, but on the other hand I'm not yet aware of a compelling use case for this feature.

[alice-i-cecile]

I think it could be reasonable to provide users the option to trigger a state transition mid-frame, as long as the default behavior is the current frame-deferred behavior, but on the other hand I'm not yet aware of a compelling use case for this feature.

Note that users can currently do this pretty easily, either by adding another StateTransition schedule copy or simply running schedules manually.

In any case, I think that's easy enough behavior to split out, and we should probably start with preserving that behavior to reduce controversy.

[inact1v1ty]

This seems like a good design to me! I think I am lacking the expertise in different use-cases to speak confidently about multiple transitions per-frame vs deferred once between frames.

My concern that if bevy has an API like world.register_required_components that relies on running strictly before anything touched the component - we should provide a clear and obvious way for user to run such systems with guarantees of fulfillment of this invariant.

This in my opinion includes the case where a library uses these init-dependent APIs so it can't enforce the user to initialize their State come specific ways. What do you think?

I am sure that it is certainly possible with this proposal - it is just that we should not overlook this while implementing.

[alice-i-cecile]

we should provide a clear and obvious way for user to run such systems with guarantees of fulfillment of this invariant.

Moving these methods to App might work, or we could have a standard way to check for those invariants. I think that's mostly tangential here though.

[ElliottjPierce]

I'm generally a fan of this, but IDK about using hooks for this. What if a stake kicks off a schedule, where that schedule changes a different state, which kicks of a schedule that changes the first state. There's potential for an infinite loop of cyclic state dependencies. In a hook, this could be a permanent freeze! Worse, the Sub-State system might make some of these transitions hard to catch from a user perspective. At the very least, we need something to yield or keep a recursion stack.

My general take here is that doing the existing state structure via iImmutable components as resources is a really great design. But I think states should continue to be once-per frame. I don't think states should be used to enforce invariants, so I'm hesitant to put them in hooks. I think hooks are more tailored to light weight stuff rather than running a schedule.

---

As a relevant tangent, states as resources has always bugged me. We have a really, really nice state system, but it only works globally. We can't use it for a UI. (What if there are multiple UIs?) We can't use it for enemy AI. (What if there are multiple enemies?) We can't use it for players in multiplayer. We can't even use it for broad scene transitions if we want to support permissive multiplayer (Ex: one player in a game, the other in a lobby).

I would prefer states to be relationships. We have a state entity, and other entities subscribe to that state to watch for changes. For example, a player motion state (Running, Walking, Jumping, etc) may exist and be watched by the player's physics body, stat tracker, etc. Or a menu state might we watched by some portion of the UI. There can be multiple of each state type! I really don't think the relationship will be burdensome either. Like, if you're transitioning a massive scene, you don't need every entity in the scene to watch the resource, just the scene's root parent.

When we transition, we just trigger an observer or something. The observer system could even be on the state entity. Anyway, that observer would have the state as its target, so it could see all it's "listening" entities. Most transition schedules are tiny, so rolling into an observer (or something) would probably be even more ergonomic than a schedule. I'd much rather despawn one scene, and spawn another in an observer system and a whole schedule. (Same goes for enabling and disabling UI, etc). But for the few other cases, it can just run a schedule from the observer instead.

[alice-i-cecile]

I'm generally a fan of this, but IDK about using hooks for this. What if a stake kicks off a schedule, where that schedule changes a different state, which kicks of a schedule that changes the first state. There's potential for an infinite loop of cyclic state dependencies. In a hook, this could be a permanent freeze! Worse, the Sub-State system might make some of these transitions hard to catch from a user perspective. At the very least, we need something to yield or keep a recursion stack.

This problem exists currently: your schedules will run forever and freeze your game :) We run state transitions until the stack is empty, and I don't think we should change that.

As a relevant tangent, states as resources has always bugged me. We have a really, really nice state system, but it only works globally

IMO we can rework states to be components (and thus optionally resources) as part of this work pretty easily.

[ElliottjPierce]

This problem exists currently: your schedules will run forever and freeze your game :) We run state transitions until the stack is empty, and I don't think we should change that.

That's reasonable. Though, popping a stack is different than infinite recursion. (But I'm probably missing some context here.)

IMO we can rework states to be components (and thus optionally resources) as part of this work pretty easily.

That would be awesome! Yeah, this can be totally along side this work. Having multiple sets of states was one of my big motivators for multi-world. This + relations fix a lot of those problems (but not all).