Newbie confused about state changes

[caelia]

Hi! I am brand new to Bevy, and fairly new to Rust (I mean, I've been trying to learn the language on and off for several years, but still consider myself a beginner). Anyway, I've been working through Qongzi's Minesweeper tutorial (https://dev.to/qongzi/bevy-minesweeper-part-8-4apn), and I've hit a roadblock at the end of Chapter 9, where there are a couple of exercises in working with states.

So, I have a BoardPlugin containing code that looks like this:

app.add_system_set(
    SystemSet::on_enter(self.running_state.clone())
        .with_system(Self::create_board),
    )

 ....

.add_system_set(
    SystemSet::on_exit(self.running_state.clone())
        .with_system(Self::cleanup_board),
    )

That's pretty standard stuff, I guess. I have done a fair amount of GUI programming, so I'm familiar with event handlers and callbacks, and this appears to me like registering callbacks for some predefined event handlers (feel free to correct me if I'm thinking about this in the wrong way). So, assuming that is the case, I gather that there are internal events called enter and exit (and others, but these two are the relevant ones here). So far, it all makes sense ...

But in the main module for the app I have this:

pub enum AppState {
    InGame,
    Out,
}

....

fn state_handler(mut state: ResMut<State<AppState>>, keys: Res<Input<KeyCode>>) {
    if keys.just_pressed(KeyCode::C) {
        if state.current() == &AppState::InGame {
            state.set(AppState::Out).unwrap();
        }
    }
    if keys.just_pressed(KeyCode::G) {
        if state.current() == &AppState::Out {
            state.set(AppState::InGame).unwrap();
        }
    }
}

So, this is also clear: pressing the C or G key triggers a state change.

But what has me utterly baffled is this: how does the Bevy engine know that changing the state from AppState::InGame to AppState::Out should trigger an exit event? Or that the opposite change should trigger an enter event? Based on the behavior when I run the app, that is clearly what happens, but I have not written any code that interprets these specific state changes, nor can I find any such code in the Bevy codebase (though perhaps I've missed something). And how can I discover what other values I might be able to use in my AppState enum?

UPDATE:
As an experiment, I changed the AppState enum to:

pub enum AppState {
    InPain,
    Ouch,
}

... and the app still runs just fine. So it would appear that the specific values of the enum are completely arbitrary. So I'm ... not any less confused. What is it, exactly, that connects the state changes to the code that invokes the systems in the BoardPlugin?

[NiklasEi]

By calling add_state on your Bevy App you are doing two things:

1. Tell Bevy a type (in your case called AppState) that is supposed to function as a State
2. Pass the initial value of the State

This state will now be saved in a resource State<your type> which you can request in systems (what you called callbacks) to read/change.

You can call your State whatever you want and can have any number of values for it. You can even have multiple States with different types.

You tell the engine (in your case via state.set) to which value of a certain state you want to switch. This means that Bevy knows the next state and the previous one.

When changing a State: the engine will run all on_exit systems of the current state once. Then it will run all the on_enter systems of the next state (the one you passed in state.set). In every frame without a state change, only the on_update systems run.

The Bevy cheatbook also has a page on States

[caelia]

Thanks for the reply. I'm still not entirely clear on how this works.

This state will now be saved in a resource State<your type> which you can request in systems (what you called callbacks) to read/change.

OK, yes ... I know they're called systems (I think that's poor naming, but OK). I just referenced callbacks to check whether Bevy's systems are analogous to the thing I'm familiar with. So ... yes?

When changing a State: the engine will run all on_exit systems of the current state once. Then it will run all the on_enter systems of the next state (the one you passed in state.set). In every frame without a state change, only the on_update systems run.

OK, so I'm still a bit confused about this. Because I have this code:

if keys.just_pressed(KeyCode::C) {
    if state.current() == &AppState::InGame {
        state.set(AppState::Out).unwrap();
    }
}

So, according to what you're saying, I would think that when the C key is pressed, the on_exit system should run for AppState::InGame, then the on_enter system should run for AppState::Out. Is that not right? But as far as I can tell, only the on_exit system runs. And similarly, when the G key is pressed and the state changes from AppState::Out to AppState::InGame, only the on_enter system seems to run. And that's the desired behavior for this particular case, I just don't understand why it works the way it does.

The Bevy cheatbook also has a page on States

Yes, thanks, I've glanced at that ... it doesn't appear to address my current question, but I'm sure it will be helpful in other ways.

UPDATE:
I tried another experiment. Following the tutorial, I originally set the initial AppState as follows:

.add_state(AppState::InGame)

... and the app starts with a populated board, ready to play the game. But if I change the above code to:

.add_state(AppState::Out)

... then the app starts with an empty window. Which is what we want ... so evidently, there must be code somewhere that implements the semantics of this AppState enum - in other words, code that associates AppState::InGame with certain behavior, and AppState::Out with different behavior. But I have not written any such code - these values are only referenced in the top-level main.rs of the tutorial app, and I've posted every instance of these values in this thread. And of course this AppState enum doesn't exist in the bevy crate. So ... I guess there must be some sophisticated, indirect logic that makes this work?

[caelia]

D'ohh! I failed to notice this:

    .add_plugin(BoardPlugin {
        running_state: AppState::InGame,
    })

I initially took running_state to mean 'current state', but now I realize that it is an immutable reference to AppState::InGame, and thus all the systems in the BoardPlugin are associated with AppState::InGame. Now it all makes sense.