Lifecycle API

[zmerp]

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

Android and XR apps often needs to keep track of the app lifecycle state and react differently to each of them. State-aware behavior is also often needed by backends an plugins implementations.

What solution would you like?

Some alternatives are:

• .add_*_system(), where * is the name of a lifecycle state (or event). This follows the current .add_startup_system().
• .add_system(my_system.when::<LifecycleState>())
• .add_system_to_schedule(my_system, LifecycleState). .add_system() will be an alias for the running/steady state systems.

Possible names for the states:

• Startup/OnCreate/Enter
• Resume/OnResume/Resuming
• Update/Running
• Pause/OnPause/Pausing
• OnDestroy/Exit

User resources are available in all states, but engine provided resources might not be available in every state.

[AlphaModder]

I wonder if this same mechanism could be leveraged in the editor for something like Unity's pause/play.

[zmerp]

@AlphaModder No, in-game pause is another thing. The app lifecycle is dictated by platform dependent events. Also when working with an editor, the code that runs the 3D view and other tools will be very different than the final game.

[zmerp]

I don't have much time for working on this, but if we decide the general shape of the API I can start writing the implementation and RFC. Personally I like more the .add_system_to_schedule() version (from @TheRawMeatball). This allows plugins with runners to define new lifecycle states (for example OpenXR has a particular state before or after a XR session is created, where the user can choose the parameters for creating a new session or bail out and close the app).

[AlphaModder]

@zarik5 In-game pause isn't really what I meant. As I understand it, the current state/run-condition mechanisms already support a pause mechanism intended for the player's use. I'm talking about something like the way the Unity editor can unilaterally pause execution of the game, possibly replace assets/code (though of course the latter is difficult with Rust), and then resume execution. Is that sort of event not similar to the platform requirements on Android or similar? It's an external, uncancelable request for the app to stop, persist its state, and reload it later.

[zmerp]

@AlphaModder The editor probably will own the runner (and replace or run the child game runner), so could do basically what it wants, even without this API. The app can react to the lifecycle event I'm describing here, but the type of pause you describe should not be detectable by the game.

[zmerp]

Here I propose to model the lifecycle API as stack-based, with states joined by an "enter" and "exit" transitions. It is important to distinguish between states and transitions, even just semantically. State systems could be run multiple times on a loop, while transition systems should be run only once between states. While states could be skipped, transitions should never be skipped, so for example Pause and Exit could run one after the other without hitting the Idle state. This should be true also for user-requested exiting of the app. These rules allow the user to organize the code so that key resources creation and destruction happen only during transitions, while state systems merely make use of these resources.

The OpenXR lifecycle is a bit of a mashup to accommodate both wired and standalone headsets. While having both Idle and WaitForDevice seems redundant (and SessionCreated and SessionEnd transitions are actually not that useful), they cannot be merged because Idle will provide the Session resource while WaitForDevice cannot. The OpenXR specification defines Hidden(Synchronized), Visible and Focused as separate states, but in practice the app should behave (mostly) in the same way in all three states. It is even discouraged to treat these three states differently, as it could throw off the runtime synchronization mechanism. The actual state will be provided as a resource to the Running state.

About the implementation, it was discussed to use the State API to implement this API, but ultimately it was decided it is not a good fit. Another possibility is that each state and transition is a separate schedule. While it could be nice to have a well defined API to construct lifecycles of different shapes, I think this is overkill, since we will have only a few engine-provided runners (winit + OpenXR + WebXR). I think the simplest solution is to let the runners manage the order of states and transitions runs.

After the lifecycle API is implemented, the Schedule can be simplified, removing the concept of "run only once" or "run multiple times". This will all be managed by the runners.

[Ratysz]

I see two dichotomies that need to be decided upon before we can start designing this proper.

Implementation:

• lifecycle states are modeled by separate schedules
• all systems live in the same schedule

API:

• lifecycle states are equivalent to logic states
• lifecycle states and logic states are on different levels

Unfortunately, implementation choice matters here: systems that live in separate schedules cannot interact with each other beyond sharing the world, i.e. they can't have explicit execution ordering, and they can't share run criteria, logic states, or systems.

If we don't split the schedule, we can still make lifecycle separate from logic in the API, but users won't have to duplicate (and then somehow commutate!) anything they want to share between lifecycle states.

This leaves us with three options:

1. Split the schedule into lifecycle-specific subschedules.
2. Keep everything in one schedule, and build lifecycle states using run criteria and/or logic states.
3. Keep everything in one schedule, and make a separate, specialized API for lifecycle states.

I'm partial to option 3:

• doesn't introduce new restrictions
• exhibits the correct metaphor of distinct lifecycle states as the app overstructure
• lets running the same copy of a system on different lifecycle events
• lets sensibly sharing a logic state machine between different lifecycle states

[zmerp]

Unfortunately, implementation choice matters here: systems that live in separate schedules cannot interact with each other beyond sharing the world, i.e. they can't have explicit execution ordering, and they can't share run criteria, logic states, or systems.

I don't think this really matters. Every state and transition beside "Running" will be "utility" schedules. In every state and transition the user would want to do completely different things, I think the World will be enough to glue everything together. The only useful thing that is impossible by keeping separate schedules is sharing logic states, but this seems more of a limitation of the States API. But even then, the States API is a very high level abstraction, while the app lifecycle isn't, so there shouldn't be many useful cases where logic states are needed cross-lifecycle-states. Keep in mind that until now all bevy apps have been built on top of the "Running" state/schedule.

[Ratysz]

We had split schedules before, with the previous logic states implementation; we moved away from that for a reason. We arguably still have split schedules, in the form of stages, and it's pretty much unanimous that we want to get rid of them too ("stageless" thing that keeps coming up is all about that).

I don't think this really matters. [...] I think the World will be enough to glue everything together. The only useful thing that is impossible by keeping separate schedules is sharing logic states, [...]

It does. Logic states, run criteria, events, system labels, ambiguity sets - these aren't part of the world, and they all matter for expressing the systems graph and its behaviors; there will be more in the future, too (soft and hard sync points, as a definite example).

Splitting schedules will require duplicating this housekeeping in every subschedule by default, or make the user do that as needed - which will expose them to a lot of the guts that are neatly folded away in such a way that they don't have to think about it, ever (well, not entirely yet, but that's what we're working towards).

The only useful thing that is impossible by keeping separate schedules is sharing logic states, but this seems more of a limitation of the States API.

I would argue that inability to interoperate with logic states (and everything else, for that matter) is a limitation of the proposed lifecycle implementation, not the other way around.

In every state and transition the user would want to do completely different things, [...]

I would definitely want to be able to continue doing some of the things I do while running when the app goes idle. Keep a network connection alive, play music, react to system events...

[...] so there shouldn't be many useful cases where logic states are needed cross-lifecycle-states.

I want my game to automatically go into "Paused" logic state when the lifecycle switches to "Idle". While continuing to play music and react to system events and whatnot.

Regardless of all of this... Compared to my suggested option 3, what would the option 1 you argue for actually win us?

[zmerp]

My argument was we don't need to share logic states, run criteria, events, system etc, not that we have to avoid it, but yeah, you showed me some use cases.

What I don't want to do is making the lifecycle a special case of a schedule. I don't like that the top schedule wants to execute one stage after the other if I don't explicitly pick and execute each one in the right lifecycle order. But from the user perspective, this behavior of "running one stage after the other" is preferred. For this reason I think schedules should be child objects of the lifecycle object. Then in practice I'm ok with moving much of the Schedule intercommunication logic into the lifecycle object.