Bevy States: Coordinate Pending Transitions, Entry Work and Cleanup

Install a state and separate its jobs

In the cited Bevy 0.20.0 API, init_state installs current and pending state resources and enables transition schedules. State support requires StatesPlugin, included in the default plugin collection. Use OnEnter for entry work, OnExit for exit work, and an in_state condition for systems that should run while a state is active. These are different execution contracts. [1]

For a menu, construction belongs to entry and interaction belongs to ongoing updates. Putting construction in a continuously running system can recreate objects unless additional project logic prevents it.

Treat a request as pending data

NextState queues the requested destination. Its value can be overwritten by another system before transitions run; it is not an event queue preserving every request. Only the pending value at the transition schedule matters. [2]

By default, StateTransition runs before PreStartup and then after PreUpdate each frame. A request made later in the frame therefore waits for a subsequent transition point unless the project explicitly runs the schedule elsewhere. Code should not assume that requesting a destination immediately changes the current state or runs its entry systems. [3]

Resolve a concrete loading conflict

Imagine the project-defined states Menu, Loading, and Playing. Selecting a level requests loading. The loading state starts the work and waits for readiness; only after readiness should project logic request play.

Now suppose readiness and the player's cancellation arrive during the same update. Choose a documented project rule, such as cancellation taking precedence, and let a single decision system write the final request. Otherwise, several writers can replace one another's pending value without expressing the intended policy. Record both the request and the applied transition when debugging this case. This is an illustrative design, not a measured race reproduction. [2]

Give temporary objects an exit owner

Keep menu objects distinguishable from persistent objects so the menu's exit work can remove only what it owns. A menu designed with 4 buttons should again contain 4 buttons after returning to it. Review the exit path as carefully as the entry path, including cancellation while loading.

State run conditions decide whether selected systems execute; they do not by themselves describe every resource and entity that should survive a transition. Define that lifetime in setup and cleanup logic. Ensure initial entry work can obtain its dependencies at the documented startup transition point. [1][3]

Choose repeat-request semantics deliberately

The referenced NextState::set runs entry and exit schedules even for the same destination as the current state. Use NextState::set_if_different when redundant same-state requests should skip those schedules; the reference notes that an earlier explicit set to that same state in the same frame can still cause them to run. [2]

This distinction matters if entry resets progress or exit deletes temporary objects. Review repeated button activation, a return to the menu, and a same-state request. Match the method names and behavior to the project's Bevy version; these proposed checks have not been executed here.

Sources

1. AppExtStates — Bevy contributors.
2. NextState — Bevy contributors.
3. StateTransition — Bevy contributors.