States v3 proposal

[MiniaczQ]

Hey everyone, I've recently been contributing to the states machinery of Bevy.
We still had some refactors & features planned and in the meantime observers and required components landed.
This opened up a lot of possibilities, but also lots of breaking changes, hence I'm opening a discussion for bevy_states replacement.
This crate will be developed separately and swapped into Bevy at some point in the future to do all the breaking changes at once.

Check out the prototype

States v3

States v3 proposal focuses on the following:

• unification of state traits (freely mutable, computed, sub),
• making commands the standard way of updating state,
• migration of state resources to entities,
• enabling per entity state machines while retaining a global state machine,
• cleaning up edge cases.

Something this proposal does not consider is keeping compatibility with the existing crate.

Internal Design

Storage Model

A single state machine is stored in a single entity.
Each state entity consists of one or more StateData<S> components with different S: State.
Dependencies between states are enforced through required components.
The only difference between global and local state is the addition of GlobalStateMarker component.
Multiple entites with GlobalStateMarker cannot exist.

/// State data component.
struct StateData<S: State> {
    /// Whether this state was reentered.
    /// Use in tandem with [`previous`].
    is_reentrant: bool,
    /// Last different state value.
    /// This is not overwritten during reentries.
    previous: Option<S>,
    /// Current value of the state.
    current: Option<S>,
    /// Proposed state value to be considered during next [`StateTransition`].
    /// How this value actually impacts the state depends on the [`State::update`] function.
    /// Most often this will be [`StateUpdate`].
    target: S::Target,
    /// Whether this state was updated in the last [`StateTransition`] schedule.
    /// For a standard use case, this happens once per frame.
    updated: bool,
}

// Not derived as to register required components.
impl<S: State> Component for StateData<S> { ... }

Top Level Reactivity

How states update each other.

State machines update through a similar system to existing bevy_state.
The StateTransition schedule runs 3 system sets:

• AllUpdates - Updates based on target and dependency changes from root states to leaf states, sets the updated flag.
• AllExits - Triggers StateExit<S> observers from leaf states to root states, targeted for local state, untargeted for global state.
• AllEnters - Triggers StateEnter<S> observers from root states to leaf states, targeted for local state, untargeted for global state.
  Smaller sets are used to specify order in the grap.
  Order is derived when specifying state dependencies, smaller value meaning closer to root.

trait State {
    /// Dependencies of this state.
    type DependencySet: StateSet;

    /// Order of this state.
    const ORDER: u32 = Self::DependencySet::HIGHEST_ORDER + 1;
}

#[derive(SystemSet)]
enum StateSystemSet {
    /// All [`Update`]s.
    AllUpdates,
    /// Lower values before higher ones.
    Update(u32),
    /// All [`Exit`]s.
    AllExits,
    /// Higher values then lower ones.
    Exit(u32),
    /// All [`Enter`]s.
    AllEnters,
    /// Same as [`Update`], lower values before higher ones.
    Enter(u32),
}

/// Emitted in from leaf to root order.
/// Untargeted for global state.
#[derive(Event)]
pub struct StateExit<S: State>(PhantomData<S>);

/// Emitted in from root to leaf order.
/// Untargeted for global state.
#[derive(Event)]
pub struct StateEnter<S: State>(PhantomData<S>);

Note that the Exit and Enter events are called after the entire state machine was updated.
Calling them while state machine is updating can lead to invalid arrangements, which we don't want to expose.
The previous and current values are available in StateData<S>.
Based on those events, more user oriented events can be made such as OnExit { previous, current } and OnEnter { previous, current }.

There is no longer a Transition stage inbetween Exit and Enter.
It wasn't that helpful, the order of calls was undefined and if it was, it could rely on Exit or Enter instead.

Bottom level reactivity

How states update themselves.

State change can be triggered from two sources:

• one of the state dependencies changed,
• state target has changed.
  When any condition is met, the State::update function is called.
  The return value of this function decides whether and how we update this state.

trait State {
    type Target: StateTarget = StateUpdate<Self>;

    /// How next value of state is decided.
    fn update(
        // Current state.
        state: &mut StateData<Self>,
        // Dependencies.
        dependencies: (StateUpdateDependency<D1>, StateUpdateDependency<D2>, ...),
    ) -> StateUpdate<Self>;
}

pub trait StateTarget: Default + Send + Sync + 'static {
    /// Returns whether the state should be updated.
    fn should_update(&self) -> bool;

    /// Resets the target to reset change detection.
    fn reset(&mut self);
}

pub enum StateUpdate<S> {
    Nothing,
    Disable,
    Enable(S),
}

User Interface

Adding and modifying state

First, the StatesPlugin has to be added to the application.
This plugin only adds the StateTransition schedule to both, startup and main schedules.

pub trait StatesExt {
    /// Registers machinery for this state as well as all dependencies.
    fn register_state<S: State>(&mut self);
    
    /// Adds the state to the provided `local` entity or otherwise the global state.
    /// If initial update is suppresed, no initial transitions will be generated.
    /// The state added this way is always disabled and has to be enabled through [`next_state`] method.
    /// This also adds all dependencies through required components.
    fn init_state<S: State>(&mut self, local: Option<Entity>, suppress_initial_update: bool);

    /// Sets the [`target`] value in [`StateData`],
    /// which will result in an [`update`] call during [`StateTransition`] schedule.
    /// Much like [`init_state`] you need to provide a local entity or nothing, for global state.
    ///
    /// This only works with the [`StateUpdate`] target.
    fn state_target<S: State<Target = StateUpdate<S>>>(&mut self, local: Option<Entity>, target: Option<S>);
}

All of the operations can happen immediatelly (with World, SubApp, App) or in a deferred manner (with Commands).
For global state, the entity gets created if it doesn't exist.
For immediate state transitions, running StateTransition is recommended.
No helper method is provided due to the complications this can bring.

Future extensions

There are few harder and easier additions:

• cross-entity states - state machines spread between many entities,
• custom target types - different backends, stacks, directly mutable, etc.,
• state unregistering - entirely removing the state machinery when it's no longer needed.

[benfrankel]

I've already done a bottom-up rewrite of bevy_state with pyri_state (which achieves goals 1, 3, and 4 among other things), and there is a hackmd doc with proposals for bevy_state. How does this discussion relate to those two things?

As for goal 2, I don't think commands being the primary way to interact with states is the right direction. Being able to mutate state values directly is convenient and would be a better direction IMO. For example: level.0 += 1.

[MiniaczQ]

Also, if observers had run conditions (there is an issue for this: #14195), I believe they would be compatible with pyri_state without sacrificing any of its existing features.

If this is about replacing bevy_state with pyri_state then this discussion isn't the place for this talk.

[benfrankel]

I'm a bit confused how state as entity is supported considering State is a resource.

State is a trait. A given state type must be a Resource but it may also be a Component.

State pattern matching and state-scoped are top level components, they can exist on any backend, so that's not my focus here. It can be ported from current crate or pyri_state if desired.

State-scoped yes, pattern-matching no because it requires your flush hooks to support run conditions, and for both the current and next state values to be accessible when the run conditions run.

Derive macro is a given, I didn't even consider mentioning it, but it should support both root and sub states. Compute is possible when implementing by hand. Looking at pyri_states macro example, don't take this as an offense, but it looks way overengineered and opinionated.

You don't have to use any of the options you don't need, they're mostly enabled by default. Currently bevy_state pushes those configs to separate calls on app, like app.enable_state_scoped_entities::<S>(), or doesn't provide an option at all.

This is also an example of a feature that can be built on top of any states implementation though, so this feature can be ignored in the comparison.

If this is about replacing bevy_state with pyri_state then this discussion isn't the place for this talk.

Nope, I'm not proposing that here. I would just prefer that a second bottom-up rewrite not be made in the dark when it's already been done once.

[MiniaczQ]

I'm curious if the motivation to use observers is related to performance, ergonomics, or mostly to experiment with a new feature and see what happens?

This is anything but an experiment, it's meant to be a replacement for the current crate.

From the coding I did so far, internals of this are way simpler and more manageable than bevy_state and certainly pyri_state (seeing at it aims for a much larger scope of features).
All while still being very flexible and easy to extend.

Performance is hard to discuss, this proposal could be slower, but assuming states change relatively rare, it's not something I care much about, unless it's like, very, very bad (which it shouldn't be).

[MiniaczQ]

State is a trait. A given state type must be a Resource but it may also be a Component.

In that case it isn't supported right now :p

State-scoped yes, pattern-matching no because it requires your flush hooks to support run conditions.

I'd like to hear more about that, isn't all you need just the current state?

Nope, I'm not proposing that here. I would just prefer that a second bottom-up rewrite not be made in the dark when it's already been done once.

I don't plan to hide implementation so all experienced contributors are welcome :p
That said, its's hard to not rewrite when the basis of the crate pivots.

[benfrankel]

I'd like to hear more about that, isn't all you need just the current state?

Having the state that will be entered available does give you enough information to pattern-match for OnEnter, but you also need the state that will be exited in order to pattern-match for OnExit. And then having both of them lets you pattern-match for OnTransition as well :)

I don't plan to hide implementation so all experienced contributors are welcome :p That said, its's hard to not rewrite when the basis of the crate pivots.

For sure. It's not that I think a second bottom-up rewrite shouldn't be done at all, just that it should be informed by the previous one. So yeah I'll make sure to help review etc.

[Guvante]

Minor nitpick, I would use a custom enum for next as I don't believe stacked Option is generally a good API choice. Note I am fine with Option<S> as None meaning disabled or something similar with prev/current is perfectly logical. In contrast with next having None mean "no change" but then Some(None) means "disabled" is going to be harder to keep lined up. Whether you do a two enum (Stay/Change) or a three part enum (Stay/Disable/Change) feels like an implementation detail though.

[MiniaczQ]

I added that in the prototype, I'll add it to proposal text next time i update it :)