State Pattern Matching - Alternative #10088

lee-orr · 2023-10-11T21:18:32Z

This is an alternative solution to the one in #9957 - it builds on the same basis, but provides a different API. I provide a fuller explanation on the rational for the change in the [Reasons for the Change] section.

Objective

The main purpose of this PR is to enable versatile state matching. The current implementation of States relies solely on equality when determining whether a given system or schedule should run:

enum AppState {
  Menu,
  Options,
  Credits,
  InGame(GameState)
}

enum GameState {
  Running,
  Paused
}

app.add_systems(OnExit(AppState::Menu), clear_ui);
app.add_systems(OnExit(AppState::Options), clear_ui);
app.add_systems(OnExit(AppState::Credits), clear_ui);

app.add_systems(Update, animate_idle_character.run_if((in_state(AppState::InGame(GameState::Running)),in_state(AppState::InGame(GameState::Paused)));
``

or, for an example based on structs:

```rust
struct AppState {
  menu: Option<Menu>
  in_game: Option<GameState>
}

enum Menu {
  Main,
  Options,
  Credits,
}

enum GameState {
  Running,
  Paused
}


app.add_systems(OnExit(AppState { menu: Some(Menu::Main), in_game: None}), clear_ui);
app.add_systems(OnExit(AppState { menu: Some(Menu::Options), in_game: None}), clear_ui);
app.add_systems(OnExit(AppState { menu: Some(Menu::Credits), in_game: None}), clear_ui);

app.add_systems(Update, animate_idle_character.run_if((in_state(AppState { menu: None, in_game: GameState::Running }),in_state(AppState { menu: None, in_game: GameState::Paused}));

This can lead to a variety of issues when the structure of the state object changes during development, or if you don't accurately foresee the way the states could change.

In addition, it is much harder to handle state changes that should only occur when entering/leaving a collection of states, but not when moving between them - like so:

// Enum
app.add_systems(OnEnter(AppState::Menu), setup_menu_backdrop);
app.add_systems(OnEnter(AppState::Options), setup_menu_backdrop);
app.add_systems(OnEnter(AppState::Credits), setup_menu_backdrop);

// State
app.add_systems(OnEnter(AppState { menu: Some(Menu::Main), in_game: None}), setup_menu_backdrop);
app.add_systems(OnEnter(AppState { menu: Some(Menu::Options), in_game: None}), setup_menu_backdrop);
app.add_systems(OnEnter(AppState { menu: Some(Menu::Credits), in_game: None}), setup_menu_backdrop);

fn setup_menu_backdrop(is_set_up_query: Query<Entity, With<Backdrop>>, ...) {
  if !is_set_up_query.is_empty() {
    return;
  }
  ...
}

This PR provides a set of tools for matching states in a more robust, reliable, and ergonomic way.

Solution

There are a few layers to the solution, and originally I went from "lowest level" to "highest level" - but I feel that added to some confusion on the reasoning/purpose behind each layer of the solution. So here, I will be going from the "highest level" stuff, which is most likely to be used directly by end users, to the "lowest level" stuff that serves as infrastructure for the higher level elements.

State Matching Macro

This solution adds the state_matches! macro for states and state transitions - allowing you to use pattern matching syntax with some small adjustments.

So - for the example above, we would be able to use:

// Enum Example
.add_systems(Entering, setup_menu_backdrop.run_if(state_matches!((AppState, Menu | Options | Credits)))
.add_systems(Exiting, clear_ui.run_if(state_matches!(AppState, every Menu | Options | Credits)))
.add_sytstems(Update, animate_idle_character.run_if(state_matches!(AppState, InGame(_))));

// State Example
.add_systems(Entering, setup_menu_backdrop.run_if(state_matches!(AppState, AppState { menu: Some(_), .. })))
.add_systems(Exiting, clear_ui.run_if(state_matches!(AppState, every AppState { menu: Some(_), .. })))
.add_sytstems(Update, animate_idle_character.run_if(state_matches!(AppState, AppState { in_game: Some(_), .. }))));

More details about the macro syntax exist below.

Note that the macro generates a StateMatcher, so it can be used anywhere those are used.

State Matchers

Speaking of StateMatchers - these form the core of the solution, providing a separation between the state storage/data (implementers of States) and the mechanism for determining whether a system should run in a given state (implementers of StateMatcher<S: States>).

There are a limited number of auto-implementations of StateMatcher<S>, as well as a couple of utility structs that implement it, but otherwise it is behind a sealed interface and inaccessible to the outside world.

In addition, StateMatchers implement IntoSystem<(), bool>, making them a valid run condition! That's why we don't need to add any in_state(), entering() or state_matches() calls.

Any given StateMatcher can be used for two things:

to check if a single state matches it (using the S::match(&self, matcher) -> bool method)
to check if a transition between states matches it (using the S::match_Transition(matcher, main: Option<&S>, secondary: Option<&S>) -> MatchesStateTransition trait function)

The MatchesStateTransition Enum represents the different options for handling transitions:
TransitionMatches - when the whole transition matches, MainMatches - when the main matches, but the transition as a whole is invalid, NoMatch - when neither the main nor the transition match. This is used to enable every and normal options in the macros, as well as to allow for custom logic if you so choose.

The main parameter is always the primary state instance we care about:

when Entering - it is the incoming state, and the secondary parameter is the outgoing state
when Exiting - it is the outgoing state, and the secondary parameter is the incoming state
Otherwise, it is the current state, and the secondary parameter is None.

This allows you to re-use the same matcher for exits, entrances, and while in the state for example:

// defining our matcher
// we want to be in game, and not moving into or out of "Super Mode"
fn in_game(main: Option<&AppState>, secondary: Option<&AppState>) -> bool {
  if matches!(main, AppState::InGame(_)) {
      secondary != Some(AppState::SuperMode)
  } else {
    false
  }
}

// And then we can use it:
.add_systems(Entering, setup_game.run_if(in_game))
.add_systems(Exiting, cleanup_game.run_if(in_game))

// We can also use it for Update, which in this case will only run if we're in `AppState::InGame(_)`,
// and ignores the secondary
.add_system(Update, move_character.run_if(in_game))

In normal use, you would probably use either the state_matches! macro, the States itself (which is also a StateMatcher using Eq), Fn(&S) -> bool or Fn(&S, Option<&S>) -> bool.

The full list of auto implementations is:

S itself
Fn(&Self) -> bool
Fn(Option<&Self>) -> bool
Fn(&Self, &Self) -> bool
Fn(&Self, Option<&Self>) -> bool
Fn(Option<&Self>, Option<&Self>) -> bool
Fn(&Self, &Self) -> MatchesStateTransition
Fn(&Self, Option<&Self>) -> MatchesStateTransition
Fn(Option<&Self>, Option<&Self>) -> MatchesStateTransition

StateMatcher's also expose 3 utility functions:

.every() - this sets it up to only use check if the main state matches, and fully ignores the secondary state in a transition. This is particularly useful since by default, if both the main and secondary match the transition will be treated as false (returning MatchesStateTransition::MainMatches).
.invert_transition() - this swaps the main and secondary states. This is useful for setting up transitions where you care about both the incoming and outgoing state, but want to use pre-defined or simple matchers for each rather than writing a dedicated function.
.chain(other: impl StateMatcher<S>) - if the current state matcher returns false (when testing a single state) or NoMatch (when testing a transition), it will execute other and return it's result.

Underlying Changes to State

Making all the systems relying on Res<State<S>> and Res<NextState<S>> within bevy_ecs rely on optional versions of the resources if possible
NextState<S> is no longer a struct, but rather an enum with 3 options: Keep, Value(S), Setter(Box<dyn Fn(S) -> S>). This is the only breaking change. The reasoning is: the previous use of NextState(Option<S>) created a confusion with None, where if one was not aware that states couldn't be removed they might assume setting the value to None removes the state. In addition, given that with this change states can be removed, that confusion would only get worse. In addition, with more complex States that aren't just a single, flat enum you might want to be able to "patch" a state rather than fully replace it. The Setter option allows you to provide a callback for patching the state, as it is at the time when apply_state_transition is called. By replacing the Option<S>, we opened up to a few additional use cases.
Adding schedules for Entering and Exiting - which will run systems whenever a state is changed. Exiting runs before State<S> is set to the new value, while Entering<S> runs after.

Notes on the macro syntax

You'll notice that the macro syntax is similar, but not identical, to the matches! syntax. This originates from the need to be able to determine the state type S for our matchers & schedule labels (see below). As work on the PR continued, this also evolved into the marco supporting a more robust syntax to resolve issues that came up.

I wanted to provide a full accounting of the macro syntax, and the reasoning behind it - but didn't want to place that within the earlier segments since I didn't want the more significant concepts to be lost to the details here.

The macro has the following structure: state_matches!(StateTypeIdent, MatchPattern, ...). The sections are detailed below:

StateTypeIdent

This is the name/path to the state type. This is required since we can't count on type inference when using patterns...

MatchPattern

A MatchPattern starts with an optional every keyword - which ensure the match will be true whenever the main state matches, regardless of the secondary state(see the StateMatcher explanation for more on main and secondary states in a state matcher).

After that, you can either provide a Pattern, a Closure, or an Expression:

The Pattern works like a normal pattern match, but you can exclude the root type name if you want (for example, InGame(_) instead of AppState::InGame(_)).
The Closure should follow one of the default implementations of StateMatcher - Fn(&S) -> bool, Fn(&S, Option<&S>) -> bool, Fn(Option<&S>, Option<&S>) -> bool, Fn(&S, Option<&S>) -> MatchesStateTransition or Fn(Option<&S>, Option<&S>) -> MatchesStateTransition.
The Expression should be a valid, existing, StateMatcher, preceded by an = symbol, like so: =AppState::MainMenu" or =in_game.The=` is used to differentiate expressions from patterns, which can't always be determined by syntax alone.

Note that you can have more than one MatchPattern in a macro, in a comma-separated list. If you do, they will be evaluated in order, and for transitions MatchesStateTransition::MainMatches will return immediately, only MatchesStateTransition::NoMatch will continue to evaluate the next pattern. This is needed because, at times, a simple every may not be enough. This is the same as the .chain() method on a state matcher.

For example, I might have a system for clearing the UI, and I want it to run whenever I move between distinct UI's. However, while I'm in game the UI remains consistent, even if the in game state changes - so what I want is:

add_systems(Exiting, clear_ui.run_if(state_matches!(AppState, InGame(_), every _)));

This will first check if I'm leaving InGame(_), and if so if I'm also moving to InGame(_) it will return false. However, otherwise - it will see that it should match every _ - meaning transitioning to and from any other state should return true and run the clear_ui system.

Reasons for the Change

Issues with the original

The previous PR had a lot of repetition both in the required syntax:

.add_systems(Entering, system.run_if(entering!(AppState, AppState::InGame(_)))

Here we need to set the schedule to Entering and use the entering! macro (or, in some cases, the entering function). The same was true for Exiting and Transitioning.

The same repetition also existed under the hood - with 3 run conditions that were virtually identical (entering, exiting, state_matches), and one that was more complex but only added a small amount of syntactic sugar (transitioning). And again, the same was the case with the macros.

We also had a robust set of tools for using closures & state values to match things (a variety of auto implementations of StateMatcher), but had to always use them through one of a variety of tools you'd have to learn and keep track of (the 4 macros and 4 run conditions).

Another issue is that we had some capabilities that were simple via macro, but had no non-macro equivalent - like every or the sequencing of multiple patterns/closures for handling a transition.

Lastly, it was hard to justify the existance of transitioning, since both entering and exiting had situations where they would look at both sides of a transition...

Changes

Remove all the macros except state_matches! - and use it for all pattern matching:

// From:
.add_systems(Entering, system.run_if(entering!(AppState, AppState::InGame(_)))
// To:
.add_systems(Entering, system.run_if(state_matches!(AppState, AppState::InGame(_)))

add a StateMatcherSystem (that wraps a function system), and implement IntoSystem<(), bool> for StateMatcher. This means we can use States values and StateMatcher closures directly as run conditions, and chain them:

// From:
.add_systems(Entering, system.run_if(entering!(AppState, |state: &AppState| state.is_paused))
// To:
.add_systems(Entering, system.run_if(|state: &AppState| state.is_paused)

Add EveryTransition(StateMatcher) - allowing access to the every feature outside of the macro. In addition, added a method .every() to StateMatcher that wraps it in the struct for you.

// Before the only option would have been:
.add_systems(Exiting, cleanup.run_if(exiting!(AppState, every _))

// Now you can do:
.add_systems(Exiting, cleanup.run_if((|_: &AppState| true).every())

Add CombineStateMatchers(StateMatcher1, StateMatcher2) - this allows you to chain state matchers like you do in the macro. Added .chain(other: StateMatcher<S>) as well.

// Before the only option would have been:
.add_systems(Exiting, cleanup.run_if(exiting!(AppState, InGame(_), every _))

// Now you can do:
.add_systems(Exiting, cleanup.run_if(state_matches!(AppState, AppState::InGame(_)).chain((|_: &AppState| true).every())))

// That is more useful if you have some pre-defined match functions you want to use:
.add_systems(Existing, cleanup.run_if(in_game.chain(always.every()))

// These all do the same thing - if it'll run the cleanup if you're moving from being in game to not being in game, or on any other transition, but NOT moving from one in game state to another

Add InvertTransition(StateMatcher) - allowing the ability to invert the focus of a matcher when matching a transition. This means that, when we are Entering - we can swap to make the primary focus of the matcher the outgoing state rather than the incoming one (and vice versa for Exiting). Added a .invert_transition() method as well. These allow you to mimic the transition(from, to) functionality without needing it there, given it's limited use.

.add_systems(Entering, resume_game.run_if(in_game.and_then(paused.invert_transition()))

// That would be equivalent to:
.add_systems(Entering, resume_game.run_if(transitioning(paused, in_game))

Remove the Transitioning schedule label (OnTransition still exists, just like OnEnter and OnExit - which rely on strict equality to work). Note that this, as well as the transitioning run condition specifically, might still be worth including for ergonomics. They just aren't functionally necessary.
Remove all the run conditions (except in_state for compatibility - it is functionally equivalent to just passing in the state value, but has a more limited set of SystemParams)
Macro syntax adjustments - removed the macro!(Expression) variety, since it is not redundant since any valid expression would also be a StateMatcher already. On the other hand, added the ability to use expressions withing the MatcherPattern like so macro!(StateType, =existing_state_matcher). The = is used to differentiate expressions from patterns, which can't always be determined by syntax alone. The addition allows you to chain existing state matchers, patterns, and closures together for a single state_matches! statement.