computed_states/

computed_states.rs

//! This example illustrates the use of [`ComputedStates`] for more complex state handling patterns.
//!
//! In this case, we'll be implementing the following pattern:
//! - The game will start in a `Menu` state, which we can return to with `Esc`
//! - From there, we can enter the game - where our bevy symbol moves around and changes color
//! - While in game, we can pause and unpause the game using `Space`
//! - We can also toggle "Turbo Mode" with the `T` key - where the movement and color changes are all faster. This
//!   is retained between pauses, but not if we exit to the main menu.
//!
//! In addition, we want to enable a "tutorial" mode, which will involve its own state that is toggled in the main menu.
//! This will display instructions about movement and turbo mode when in game and unpaused, and instructions on how to unpause when paused.
//!
//! To implement this, we will create 2 root-level states: `AppState` and `TutorialState`.
//! We will then create some computed states that derive from `AppState`: `InGame` and `TurboMode` are marker states implemented
//! as Zero-Sized Structs (ZSTs), while `IsPaused` is an enum with 2 distinct states.
//! And lastly, we'll add `Tutorial`, a computed state deriving from `TutorialState`, `InGame` and `IsPaused`, with 2 distinct
//! states to display the 2 tutorial texts.

use bevy::{
    dev_tools::states::*,
    input::keyboard::Key,
    picking::hover::Hovered,
    prelude::*,
    ui::{Checked, Pressed},
    ui_widgets::{checkbox_self_update, Activate, ActivateOnPress, Button, Checkbox, ValueChange},
};

use ui::*;

// To begin, we want to define our state objects.
#[derive(Debug, Clone, Copy, Default, Eq, PartialEq, Hash, States)]
enum AppState {
    #[default]
    Menu,
    // Unlike in the `states` example, we're adding more data in this
    // version of our AppState. In this case, we actually have
    // 4 distinct "InGame" states - unpaused and no turbo, paused and no
    // turbo, unpaused and turbo and paused and turbo.
    InGame {
        paused: bool,
        turbo: bool,
    },
}

// The tutorial state object, on the other hand, is a fairly simple enum.
#[derive(Debug, Clone, Copy, Default, Eq, PartialEq, Hash, States)]
enum TutorialState {
    #[default]
    Active,
    Inactive,
}

// Because we have 4 distinct values of `AppState` that mean we're "InGame", we're going to define
// a separate "InGame" type and implement `ComputedStates` for it.
// This allows us to only need to check against one type
// when otherwise we'd need to check against multiple.
#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
struct InGame;

impl ComputedStates for InGame {
    // Our computed state depends on `AppState`, so we need to specify it as the SourceStates type.
    type SourceStates = AppState;

    // This is necessary to prevent `setup_game` from running when the app is already in `AppState::InGame`
    // and only `paused` and `turbo` are changed
    const ALLOW_SAME_STATE_TRANSITIONS: bool = false;
    // The compute function takes in the `SourceStates`
    fn compute(sources: AppState) -> Option<Self> {
        // You might notice that InGame has no values - instead, in this case, the `State<InGame>` resource only exists
        // if the `compute` function would return `Some` - so only when we are in game.
        match sources {
            // No matter what the value of `paused` or `turbo` is, we're still in the game rather than a menu
            AppState::InGame { .. } => Some(Self),
            _ => None,
        }
    }
}

// Similarly, we want to have the TurboMode state - so we'll define that now.
//
// Having it separate from [`InGame`] and [`AppState`] like this allows us to check each of them separately, rather than
// needing to compare against every version of the AppState that could involve them.
//
// In addition, it allows us to still maintain a strict type representation - you can't Turbo
// if you aren't in game, for example - while still having the
// flexibility to check for the states as if they were completely unrelated.

#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
struct TurboMode;

impl ComputedStates for TurboMode {
    type SourceStates = AppState;
    const ALLOW_SAME_STATE_TRANSITIONS: bool = false;

    fn compute(sources: AppState) -> Option<Self> {
        match sources {
            AppState::InGame { turbo: true, .. } => Some(Self),
            _ => None,
        }
    }
}

// For the [`IsPaused`] state, we'll actually use an `enum` - because the difference between `Paused` and `NotPaused`
// involve activating different systems.
//
// To clarify the difference, `InGame` and `TurboMode` both activate systems if they exist, and there is
// no variation within them. So we defined them as Zero-Sized Structs.
//
// In contrast, pausing actually involve 3 distinct potential situations:
// - it doesn't exist - this is when being paused is meaningless, like in the menu.
// - it is `NotPaused` - in which elements like the movement system are active.
// - it is `Paused` - in which those game systems are inactive, and a pause screen is shown.
#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
enum IsPaused {
    NotPaused,
    Paused,
}

impl ComputedStates for IsPaused {
    type SourceStates = AppState;
    const ALLOW_SAME_STATE_TRANSITIONS: bool = false;

    fn compute(sources: AppState) -> Option<Self> {
        // Here we convert from our [`AppState`] to all potential [`IsPaused`] versions.
        match sources {
            AppState::InGame { paused: true, .. } => Some(Self::Paused),
            AppState::InGame { paused: false, .. } => Some(Self::NotPaused),
            // If `AppState` is not `InGame`, pausing is meaningless, and so we set it to `None`.
            _ => None,
        }
    }
}

// Lastly, we have our tutorial, which actually has a more complex derivation.
//
// Like `IsPaused`, the tutorial has a few fully distinct possible states, so we want to represent them
// as an Enum. However - in this case they are all dependent on multiple states: the root [`TutorialState`],
// and both [`InGame`] and [`IsPaused`] - which are in turn derived from [`AppState`].
#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
enum Tutorial {
    MovementInstructions,
    PauseInstructions,
}

impl ComputedStates for Tutorial {
    // We can also use tuples of types that implement [`States`] as our [`SourceStates`].
    // That includes other [`ComputedStates`] - though circular dependencies are not supported
    // and will produce a compile error.
    //
    // We could define this as relying on [`TutorialState`] and [`AppState`] instead, but
    // then we would need to duplicate the derivation logic for [`InGame`] and [`IsPaused`].
    // In this example that is not a significant undertaking, but as a rule it is likely more
    // effective to rely on the already derived states to avoid the logic drifting apart.
    //
    // Notice that you can wrap any of the [`States`] here in [`Option`]s. If you do so,
    // the computation will get called even if the state does not exist.
    type SourceStates = (TutorialState, InGame, Option<IsPaused>);

    // Notice that we aren't using InGame - we're just using it as a source state to
    // prevent the computation from executing if we're not in game. Instead - this
    // ComputedState will just not exist in that situation.
    fn compute(
        (tutorial_state, _in_game, is_paused): (TutorialState, InGame, Option<IsPaused>),
    ) -> Option<Self> {
        // If the tutorial is inactive we don't need to worry about it.
        if !matches!(tutorial_state, TutorialState::Active) {
            return None;
        }

        // If we're paused, we're in the PauseInstructions tutorial
        // Otherwise, we're in the MovementInstructions tutorial
        match is_paused? {
            IsPaused::NotPaused => Some(Tutorial::MovementInstructions),
            IsPaused::Paused => Some(Tutorial::PauseInstructions),
        }
    }
}

fn main() {
    // We start the setup like we did in the states example.
    App::new()
        .add_plugins(DefaultPlugins)
        .init_state::<AppState>()
        .init_state::<TutorialState>()
        // After initializing the normal states, we'll use `.add_computed_state::<CS>()` to initialize our `ComputedStates`
        .add_computed_state::<InGame>()
        .add_computed_state::<IsPaused>()
        .add_computed_state::<TurboMode>()
        .add_computed_state::<Tutorial>()
        // we can then resume adding systems just like we would in any other case,
        // using our states as normal.
        .add_systems(Startup, setup)
        .add_systems(OnEnter(AppState::Menu), setup_menu)
        .add_systems(Update, menu_styling.run_if(in_state(AppState::Menu)))
        .add_observer(menu_activate.run_if(in_state(AppState::Menu)))
        .add_observer(menu_tutorial_checked.run_if(in_state(AppState::Menu)))
        .add_observer(checkbox_self_update)
        .add_systems(OnExit(AppState::Menu), cleanup_menu)
        // We only want to run the [`setup_game`] function when we enter the [`AppState::InGame`] state, regardless
        // of whether the game is paused or not.
        .add_systems(OnEnter(InGame), setup_game)
        // We want the color change, toggle_pause and quit_to_menu systems to ignore the paused condition, so we can use the [`InGame`] derived
        // state here as well.
        .add_systems(
            Update,
            (toggle_pause, change_color, quit_to_menu).run_if(in_state(InGame)),
        )
        // However, we only want to move or toggle turbo mode if we are not in a paused state.
        .add_systems(
            Update,
            (toggle_turbo, movement).run_if(in_state(IsPaused::NotPaused)),
        )
        // We can continue setting things up, following all the same patterns used above and in the `states` example.
        .add_systems(OnEnter(IsPaused::Paused), setup_paused_screen)
        .add_systems(OnEnter(TurboMode), setup_turbo_text)
        .add_systems(
            OnEnter(Tutorial::MovementInstructions),
            movement_instructions,
        )
        .add_systems(OnEnter(Tutorial::PauseInstructions), pause_instructions)
        .add_systems(
            Update,
            (
                log_transitions::<AppState>,
                log_transitions::<TutorialState>,
            ),
        )
        .run();
}

/// Updates the app state when the play button is activated.
fn menu_activate(_event: On<Activate>, mut next_state: ResMut<NextState<AppState>>) {
    // The play button is the only button on the menu that would send the `Activate` event.
    next_state.set(AppState::InGame {
        paused: false,
        turbo: false,
    });
}

/// Updates the app state when the tutorial button is checked/unchecked.
/// The `checkbox_self_update` observer added to the app handles
/// updating the `Checked` component on the `Checkbox` itself.
fn menu_tutorial_checked(
    event: On<ValueChange<bool>>,
    mut next_tutorial: ResMut<NextState<TutorialState>>,
) {
    next_tutorial.set(if event.value {
        TutorialState::Active
    } else {
        TutorialState::Inactive
    });
}

/// Updates button and checkbox styling based on hovered and pressed states.
fn menu_styling(
    mut widget_query: Query<
        (
            &Hovered,
            Option<&Pressed>,
            &mut BackgroundColor,
            Has<Checkbox>,
        ),
        Or<(With<Button>, With<Checkbox>)>,
    >,
    tutorial_state: Res<State<TutorialState>>,
) {
    for (hovered, pressed, mut color, is_tutorial_checkbox) in &mut widget_query {
        if pressed.is_some() {
            *color = if is_tutorial_checkbox && tutorial_state.get() == &TutorialState::Active {
                PRESSED_ACTIVE_BUTTON.into()
            } else {
                PRESSED_BUTTON.into()
            };
        } else if hovered.get() {
            if is_tutorial_checkbox && tutorial_state.get() == &TutorialState::Active {
                *color = HOVERED_ACTIVE_BUTTON.into();
            } else {
                *color = HOVERED_BUTTON.into();
            }
        } else {
            if is_tutorial_checkbox && tutorial_state.get() == &TutorialState::Active {
                *color = ACTIVE_BUTTON.into();
            } else {
                *color = NORMAL_BUTTON.into();
            }
        }
    }
}

fn toggle_pause(
    input: Res<ButtonInput<KeyCode>>,
    current_state: Res<State<AppState>>,
    mut next_state: ResMut<NextState<AppState>>,
) {
    if input.just_pressed(KeyCode::Space)
        && let AppState::InGame { paused, turbo } = current_state.get()
    {
        next_state.set(AppState::InGame {
            paused: !*paused,
            turbo: *turbo,
        });
    }
}

fn toggle_turbo(
    input: Res<ButtonInput<Key>>,
    current_state: Res<State<AppState>>,
    mut next_state: ResMut<NextState<AppState>>,
) {
    if input.just_pressed(Key::Character("t".into()))
        && let AppState::InGame { paused, turbo } = current_state.get()
    {
        next_state.set(AppState::InGame {
            paused: *paused,
            turbo: !*turbo,
        });
    }
}

fn quit_to_menu(input: Res<ButtonInput<KeyCode>>, mut next_state: ResMut<NextState<AppState>>) {
    if input.just_pressed(KeyCode::Escape) {
        next_state.set(AppState::Menu);
    }
}

mod ui {
    use crate::*;

    #[derive(Resource)]
    pub struct MenuData {
        pub root_entity: Entity,
    }

    #[derive(Component, PartialEq, Eq)]
    pub enum MenuButton {
        Play,
        Tutorial,
    }

    pub const NORMAL_BUTTON: Color = Color::srgb(0.15, 0.15, 0.15);
    pub const HOVERED_BUTTON: Color = Color::srgb(0.25, 0.25, 0.25);
    pub const PRESSED_BUTTON: Color = Color::srgb(0.35, 0.75, 0.35);

    pub const ACTIVE_BUTTON: Color = Color::srgb(0.15, 0.85, 0.15);
    pub const HOVERED_ACTIVE_BUTTON: Color = Color::srgb(0.25, 0.55, 0.25);
    pub const PRESSED_ACTIVE_BUTTON: Color = Color::srgb(0.35, 0.95, 0.35);

    pub fn setup(mut commands: Commands) {
        commands.spawn(Camera2d);
    }

    pub fn setup_menu(mut commands: Commands, tutorial_state: Res<State<TutorialState>>) {
        let button_entity = commands
            .spawn((
                Node {
                    // center button
                    width: percent(100),
                    height: percent(100),
                    justify_content: JustifyContent::Center,
                    align_items: AlignItems::Center,
                    flex_direction: FlexDirection::Column,
                    row_gap: px(10),
                    ..default()
                },
                children![(
                    Button,
                    Hovered::default(),
                    ActivateOnPress,
                    Node {
                        width: px(200),
                        height: px(65),
                        // horizontally center child text
                        justify_content: JustifyContent::Center,
                        // vertically center child text
                        align_items: AlignItems::Center,
                        ..default()
                    },
                    BackgroundColor(NORMAL_BUTTON),
                    MenuButton::Play,
                    children![(
                        Text::new("Play"),
                        TextFont {
                            font_size: FontSize::Px(33.0),
                            ..default()
                        },
                        TextColor(Color::srgb(0.9, 0.9, 0.9)),
                    )],
                ),],
            ))
            .id();

        let mut tutorial_checkbox = commands.spawn((
            Checkbox,
            Hovered::default(),
            ActivateOnPress,
            Node {
                width: px(200),
                height: px(65),
                // horizontally center child text
                justify_content: JustifyContent::Center,
                // vertically center child text
                align_items: AlignItems::Center,
                ..default()
            },
            BackgroundColor(match tutorial_state.get() {
                TutorialState::Active => ACTIVE_BUTTON,
                TutorialState::Inactive => NORMAL_BUTTON,
            }),
            MenuButton::Tutorial,
            children![(
                Text::new("Tutorial"),
                TextFont {
                    font_size: FontSize::Px(33.0),
                    ..default()
                },
                TextColor(Color::srgb(0.9, 0.9, 0.9)),
            )],
        ));
        match tutorial_state.get() {
            TutorialState::Active => {
                tutorial_checkbox.insert(Checked);
            }
            TutorialState::Inactive => {}
        };
        let tutorial_checkbox_id = tutorial_checkbox.id();
        commands
            .entity(button_entity)
            .add_child(tutorial_checkbox_id);

        commands.insert_resource(MenuData {
            root_entity: button_entity,
        });
    }

    pub fn cleanup_menu(mut commands: Commands, menu_data: Res<MenuData>) {
        commands.entity(menu_data.root_entity).despawn();
    }

    pub fn setup_game(mut commands: Commands, asset_server: Res<AssetServer>) {
        commands.spawn((
            DespawnOnExit(InGame),
            Sprite::from_image(asset_server.load("branding/icon.png")),
        ));
    }

    const SPEED: f32 = 100.0;
    const TURBO_SPEED: f32 = 300.0;

    pub fn movement(
        time: Res<Time>,
        input: Res<ButtonInput<KeyCode>>,
        turbo: Option<Res<State<TurboMode>>>,
        mut query: Query<&mut Transform, With<Sprite>>,
    ) {
        for mut transform in &mut query {
            let mut direction = Vec3::ZERO;
            if input.pressed(KeyCode::ArrowLeft) {
                direction.x -= 1.0;
            }
            if input.pressed(KeyCode::ArrowRight) {
                direction.x += 1.0;
            }
            if input.pressed(KeyCode::ArrowUp) {
                direction.y += 1.0;
            }
            if input.pressed(KeyCode::ArrowDown) {
                direction.y -= 1.0;
            }

            if direction != Vec3::ZERO {
                transform.translation += direction.normalize()
                    * if turbo.is_some() { TURBO_SPEED } else { SPEED }
                    * time.delta_secs();
            }
        }
    }

    pub fn setup_paused_screen(mut commands: Commands) {
        info!("Printing Pause");
        commands.spawn((
            DespawnOnExit(IsPaused::Paused),
            Node {
                // center button
                width: percent(100),
                height: percent(100),
                justify_content: JustifyContent::Center,
                align_items: AlignItems::Center,
                flex_direction: FlexDirection::Column,
                row_gap: px(10),
                position_type: PositionType::Absolute,
                ..default()
            },
            children![(
                Node {
                    width: px(400),
                    height: px(400),
                    // horizontally center child text
                    justify_content: JustifyContent::Center,
                    // vertically center child text
                    align_items: AlignItems::Center,
                    ..default()
                },
                BackgroundColor(NORMAL_BUTTON),
                MenuButton::Play,
                children![(
                    Text::new("Paused"),
                    TextFont {
                        font_size: FontSize::Px(33.0),
                        ..default()
                    },
                    TextColor(Color::srgb(0.9, 0.9, 0.9)),
                )],
            ),],
        ));
    }

    pub fn setup_turbo_text(mut commands: Commands) {
        commands.spawn((
            DespawnOnExit(TurboMode),
            Node {
                // center button
                width: percent(100),
                height: percent(100),
                justify_content: JustifyContent::Start,
                align_items: AlignItems::Center,
                flex_direction: FlexDirection::Column,
                row_gap: px(10),
                position_type: PositionType::Absolute,
                ..default()
            },
            children![(
                Text::new("TURBO MODE"),
                TextFont {
                    font_size: FontSize::Px(33.0),
                    ..default()
                },
                TextColor(Color::srgb(0.9, 0.3, 0.1)),
            )],
        ));
    }

    pub fn change_color(time: Res<Time>, mut query: Query<&mut Sprite>) {
        for mut sprite in &mut query {
            let new_color = LinearRgba {
                blue: ops::sin(time.elapsed_secs() * 0.5) + 2.0,
                ..LinearRgba::from(sprite.color)
            };

            sprite.color = new_color.into();
        }
    }

    pub fn movement_instructions(mut commands: Commands) {
        commands.spawn((
            DespawnOnExit(Tutorial::MovementInstructions),
            Node {
                // center button
                width: percent(100),
                height: percent(100),
                justify_content: JustifyContent::End,
                align_items: AlignItems::Center,
                flex_direction: FlexDirection::Column,
                row_gap: px(10),
                position_type: PositionType::Absolute,
                ..default()
            },
            children![
                (
                    Text::new("Move the bevy logo with the arrow keys"),
                    TextFont {
                        font_size: FontSize::Px(33.0),
                        ..default()
                    },
                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
                ),
                (
                    Text::new("Press T to enter TURBO MODE"),
                    TextFont {
                        font_size: FontSize::Px(33.0),
                        ..default()
                    },
                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
                ),
                (
                    Text::new("Press SPACE to pause"),
                    TextFont {
                        font_size: FontSize::Px(33.0),
                        ..default()
                    },
                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
                ),
                (
                    Text::new("Press ESCAPE to return to the menu"),
                    TextFont {
                        font_size: FontSize::Px(33.0),
                        ..default()
                    },
                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
                ),
            ],
        ));
    }

    pub fn pause_instructions(mut commands: Commands) {
        commands.spawn((
            DespawnOnExit(Tutorial::PauseInstructions),
            Node {
                // center button
                width: percent(100),
                height: percent(100),
                justify_content: JustifyContent::End,
                align_items: AlignItems::Center,
                flex_direction: FlexDirection::Column,
                row_gap: px(10),
                position_type: PositionType::Absolute,
                ..default()
            },
            children![
                (
                    Text::new("Press SPACE to resume"),
                    TextFont {
                        font_size: FontSize::Px(33.0),
                        ..default()
                    },
                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
                ),
                (
                    Text::new("Press ESCAPE to return to the menu"),
                    TextFont {
                        font_size: FontSize::Px(33.0),
                        ..default()
                    },
                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
                ),
            ],
        ));
    }
}