Vendor dependencies for 0.3.0 release

vendor/bevy/examples/state/computed_states.rs

@@ -0,0 +1,609 @@
+//! 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 it's 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::*, prelude::*};
+
+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;
+
+    // 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;
+
+    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;
+
+    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.run_if(in_state(AppState::Menu)))
+        .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)
+        // And we only want to run the [`clear_game`] function when we leave the [`AppState::InGame`] state, regardless
+        // of whether we're paused.
+        .enable_state_scoped_entities::<InGame>()
+        // 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)
+        .enable_state_scoped_entities::<IsPaused>()
+        .add_systems(OnEnter(TurboMode), setup_turbo_text)
+        .enable_state_scoped_entities::<TurboMode>()
+        .add_systems(
+            OnEnter(Tutorial::MovementInstructions),
+            movement_instructions,
+        )
+        .add_systems(OnEnter(Tutorial::PauseInstructions), pause_instructions)
+        .enable_state_scoped_entities::<Tutorial>()
+        .add_systems(
+            Update,
+            (
+                log_transitions::<AppState>,
+                log_transitions::<TutorialState>,
+            ),
+        )
+        .run();
+}
+
+fn menu(
+    mut next_state: ResMut<NextState<AppState>>,
+    tutorial_state: Res<State<TutorialState>>,
+    mut next_tutorial: ResMut<NextState<TutorialState>>,
+    mut interaction_query: Query<
+        (&Interaction, &mut BackgroundColor, &MenuButton),
+        (Changed<Interaction>, With<Button>),
+    >,
+) {
+    for (interaction, mut color, menu_button) in &mut interaction_query {
+        match *interaction {
+            Interaction::Pressed => {
+                *color = if menu_button == &MenuButton::Tutorial
+                    && tutorial_state.get() == &TutorialState::Active
+                {
+                    PRESSED_ACTIVE_BUTTON.into()
+                } else {
+                    PRESSED_BUTTON.into()
+                };
+
+                match menu_button {
+                    MenuButton::Play => next_state.set(AppState::InGame {
+                        paused: false,
+                        turbo: false,
+                    }),
+                    MenuButton::Tutorial => next_tutorial.set(match tutorial_state.get() {
+                        TutorialState::Active => TutorialState::Inactive,
+                        TutorialState::Inactive => TutorialState::Active,
+                    }),
+                };
+            }
+            Interaction::Hovered => {
+                if menu_button == &MenuButton::Tutorial
+                    && tutorial_state.get() == &TutorialState::Active
+                {
+                    *color = HOVERED_ACTIVE_BUTTON.into();
+                } else {
+                    *color = HOVERED_BUTTON.into();
+                }
+            }
+            Interaction::None => {
+                if menu_button == &MenuButton::Tutorial
+                    && 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) {
+        if let AppState::InGame { paused, turbo } = current_state.get() {
+            next_state.set(AppState::InGame {
+                paused: !*paused,
+                turbo: *turbo,
+            });
+        }
+    }
+}
+
+fn toggle_turbo(
+    input: Res<ButtonInput<KeyCode>>,
+    current_state: Res<State<AppState>>,
+    mut next_state: ResMut<NextState<AppState>>,
+) {
+    if input.just_pressed(KeyCode::KeyT) {
+        if 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: Val::Percent(100.),
+                    height: Val::Percent(100.),
+                    justify_content: JustifyContent::Center,
+                    align_items: AlignItems::Center,
+                    flex_direction: FlexDirection::Column,
+                    row_gap: Val::Px(10.),
+                    ..default()
+                },
+                children![
+                    (
+                        Button,
+                        Node {
+                            width: Val::Px(200.),
+                            height: Val::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: 33.0,
+                                ..default()
+                            },
+                            TextColor(Color::srgb(0.9, 0.9, 0.9)),
+                        )],
+                    ),
+                    (
+                        Button,
+                        Node {
+                            width: Val::Px(200.),
+                            height: Val::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: 33.0,
+                                ..default()
+                            },
+                            TextColor(Color::srgb(0.9, 0.9, 0.9)),
+                        )]
+                    ),
+                ],
+            ))
+            .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((
+            StateScoped(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((
+            StateScoped(IsPaused::Paused),
+            Node {
+                // center button
+                width: Val::Percent(100.),
+                height: Val::Percent(100.),
+                justify_content: JustifyContent::Center,
+                align_items: AlignItems::Center,
+                flex_direction: FlexDirection::Column,
+                row_gap: Val::Px(10.),
+                position_type: PositionType::Absolute,
+                ..default()
+            },
+            children![(
+                Node {
+                    width: Val::Px(400.),
+                    height: Val::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: 33.0,
+                        ..default()
+                    },
+                    TextColor(Color::srgb(0.9, 0.9, 0.9)),
+                )],
+            ),],
+        ));
+    }
+
+    pub fn setup_turbo_text(mut commands: Commands) {
+        commands.spawn((
+            StateScoped(TurboMode),
+            Node {
+                // center button
+                width: Val::Percent(100.),
+                height: Val::Percent(100.),
+                justify_content: JustifyContent::Start,
+                align_items: AlignItems::Center,
+                flex_direction: FlexDirection::Column,
+                row_gap: Val::Px(10.),
+                position_type: PositionType::Absolute,
+                ..default()
+            },
+            children![(
+                Text::new("TURBO MODE"),
+                TextFont {
+                    font_size: 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((
+            StateScoped(Tutorial::MovementInstructions),
+            Node {
+                // center button
+                width: Val::Percent(100.),
+                height: Val::Percent(100.),
+                justify_content: JustifyContent::End,
+                align_items: AlignItems::Center,
+                flex_direction: FlexDirection::Column,
+                row_gap: Val::Px(10.),
+                position_type: PositionType::Absolute,
+                ..default()
+            },
+            children![
+                (
+                    Text::new("Move the bevy logo with the arrow keys"),
+                    TextFont {
+                        font_size: 33.0,
+                        ..default()
+                    },
+                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
+                ),
+                (
+                    Text::new("Press T to enter TURBO MODE"),
+                    TextFont {
+                        font_size: 33.0,
+                        ..default()
+                    },
+                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
+                ),
+                (
+                    Text::new("Press SPACE to pause"),
+                    TextFont {
+                        font_size: 33.0,
+                        ..default()
+                    },
+                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
+                ),
+                (
+                    Text::new("Press ESCAPE to return to the menu"),
+                    TextFont {
+                        font_size: 33.0,
+                        ..default()
+                    },
+                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
+                ),
+            ],
+        ));
+    }
+
+    pub fn pause_instructions(mut commands: Commands) {
+        commands.spawn((
+            StateScoped(Tutorial::PauseInstructions),
+            Node {
+                // center button
+                width: Val::Percent(100.),
+                height: Val::Percent(100.),
+                justify_content: JustifyContent::End,
+                align_items: AlignItems::Center,
+                flex_direction: FlexDirection::Column,
+                row_gap: Val::Px(10.),
+                position_type: PositionType::Absolute,
+                ..default()
+            },
+            children![
+                (
+                    Text::new("Press SPACE to resume"),
+                    TextFont {
+                        font_size: 33.0,
+                        ..default()
+                    },
+                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
+                ),
+                (
+                    Text::new("Press ESCAPE to return to the menu"),
+                    TextFont {
+                        font_size: 33.0,
+                        ..default()
+                    },
+                    TextColor(Color::srgb(0.3, 0.3, 0.7)),
+                ),
+            ],
+        ));
+    }
+}

vendor/bevy/examples/state/custom_transitions.rs

@@ -0,0 +1,279 @@
+//! This example illustrates how to register custom state transition behavior.
+//!
+//! In this case we are trying to add `OnReenter` and `OnReexit`
+//! which will work much like `OnEnter` and `OnExit`,
+//! but additionally trigger if the state changed into itself.
+//!
+//! While identity transitions exist internally in [`StateTransitionEvent`]s,
+//! the default schedules intentionally ignore them, as this behavior is not commonly needed or expected.
+//!
+//! While this example displays identity transitions for a single state,
+//! identity transitions are propagated through the entire state graph,
+//! meaning any change to parent state will be propagated to [`ComputedStates`] and [`SubStates`].
+
+use std::marker::PhantomData;
+
+use bevy::{dev_tools::states::*, ecs::schedule::ScheduleLabel, prelude::*};
+
+use custom_transitions::*;
+
+#[derive(Debug, Clone, Copy, Default, Eq, PartialEq, Hash, States)]
+enum AppState {
+    #[default]
+    Menu,
+    InGame,
+}
+
+fn main() {
+    App::new()
+        // We insert the custom transitions plugin for `AppState`.
+        .add_plugins((
+            DefaultPlugins,
+            IdentityTransitionsPlugin::<AppState>::default(),
+        ))
+        .init_state::<AppState>()
+        .add_systems(Startup, setup)
+        .add_systems(OnEnter(AppState::Menu), setup_menu)
+        .add_systems(Update, menu.run_if(in_state(AppState::Menu)))
+        .add_systems(OnExit(AppState::Menu), cleanup_menu)
+        // We will restart the game progress every time we re-enter into it.
+        .add_systems(OnReenter(AppState::InGame), setup_game)
+        .add_systems(OnReexit(AppState::InGame), teardown_game)
+        // Doing it this way allows us to restart the game without any additional in-between states.
+        .add_systems(
+            Update,
+            ((movement, change_color, trigger_game_restart).run_if(in_state(AppState::InGame)),),
+        )
+        .add_systems(Update, log_transitions::<AppState>)
+        .run();
+}
+
+/// This module provides the custom `OnReenter` and `OnReexit` transitions for easy installation.
+mod custom_transitions {
+    use crate::*;
+
+    /// The plugin registers the transitions for one specific state.
+    /// If you use this for multiple states consider:
+    /// - installing the plugin multiple times,
+    /// - create an [`App`] extension method that inserts
+    ///   those transitions during state installation.
+    #[derive(Default)]
+    pub struct IdentityTransitionsPlugin<S: States>(PhantomData<S>);
+
+    impl<S: States> Plugin for IdentityTransitionsPlugin<S> {
+        fn build(&self, app: &mut App) {
+            app.add_systems(
+                StateTransition,
+                // The internals can generate at most one transition event of specific type per frame.
+                // We take the latest one and clear the queue.
+                last_transition::<S>
+                    // We insert the optional event into our schedule runner.
+                    .pipe(run_reenter::<S>)
+                    // State transitions are handled in three ordered steps, exposed as system sets.
+                    // We can add our systems to them, which will run the corresponding schedules when they're evaluated.
+                    // These are:
+                    // - [`ExitSchedules`] - Ran from leaf-states to root-states,
+                    // - [`TransitionSchedules`] - Ran in arbitrary order,
+                    // - [`EnterSchedules`] - Ran from root-states to leaf-states.
+                    .in_set(EnterSchedules::<S>::default()),
+            )
+            .add_systems(
+                StateTransition,
+                last_transition::<S>
+                    .pipe(run_reexit::<S>)
+                    .in_set(ExitSchedules::<S>::default()),
+            );
+        }
+    }
+
+    /// Custom schedule that will behave like [`OnEnter`], but run on identity transitions.
+    #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
+    pub struct OnReenter<S: States>(pub S);
+
+    /// Schedule runner which checks conditions and if they're right
+    /// runs out custom schedule.
+    fn run_reenter<S: States>(transition: In<Option<StateTransitionEvent<S>>>, world: &mut World) {
+        // We return early if no transition event happened.
+        let Some(transition) = transition.0 else {
+            return;
+        };
+
+        // If we wanted to ignore identity transitions,
+        // we'd compare `exited` and `entered` here,
+        // and return if they were the same.
+
+        // We check if we actually entered a state.
+        // A [`None`] would indicate that the state was removed from the world.
+        // This only happens in the case of [`SubStates`] and [`ComputedStates`].
+        let Some(entered) = transition.entered else {
+            return;
+        };
+
+        // If all conditions are valid, we run our custom schedule.
+        let _ = world.try_run_schedule(OnReenter(entered));
+
+        // If you want to overwrite the default `OnEnter` behavior to act like re-enter,
+        // you can do so by running the `OnEnter` schedule here. Note that you don't want
+        // to run `OnEnter` when the default behavior does so.
+        // ```
+        // if transition.entered != transition.exited {
+        //     return;
+        // }
+        // let _ = world.try_run_schedule(OnReenter(entered));
+        // ```
+    }
+
+    /// Custom schedule that will behave like [`OnExit`], but run on identity transitions.
+    #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
+    pub struct OnReexit<S: States>(pub S);
+
+    fn run_reexit<S: States>(transition: In<Option<StateTransitionEvent<S>>>, world: &mut World) {
+        let Some(transition) = transition.0 else {
+            return;
+        };
+        let Some(exited) = transition.exited else {
+            return;
+        };
+
+        let _ = world.try_run_schedule(OnReexit(exited));
+    }
+}
+
+fn menu(
+    mut next_state: ResMut<NextState<AppState>>,
+    mut interaction_query: Query<
+        (&Interaction, &mut BackgroundColor),
+        (Changed<Interaction>, With<Button>),
+    >,
+) {
+    for (interaction, mut color) in &mut interaction_query {
+        match *interaction {
+            Interaction::Pressed => {
+                *color = PRESSED_BUTTON.into();
+                next_state.set(AppState::InGame);
+            }
+            Interaction::Hovered => {
+                *color = HOVERED_BUTTON.into();
+            }
+            Interaction::None => {
+                *color = NORMAL_BUTTON.into();
+            }
+        }
+    }
+}
+
+fn cleanup_menu(mut commands: Commands, menu_data: Res<MenuData>) {
+    commands.entity(menu_data.button_entity).despawn();
+}
+
+const SPEED: f32 = 100.0;
+fn movement(
+    time: Res<Time>,
+    input: Res<ButtonInput<KeyCode>>,
+    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() * SPEED * time.delta_secs();
+        }
+    }
+}
+
+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();
+    }
+}
+
+// We can restart the game by pressing "R".
+// This will trigger an [`AppState::InGame`] -> [`AppState::InGame`]
+// transition, which will run our custom schedules.
+fn trigger_game_restart(
+    input: Res<ButtonInput<KeyCode>>,
+    mut next_state: ResMut<NextState<AppState>>,
+) {
+    if input.just_pressed(KeyCode::KeyR) {
+        // Although we are already in this state setting it again will generate an identity transition.
+        // While default schedules ignore those kinds of transitions, our custom schedules will react to them.
+        next_state.set(AppState::InGame);
+    }
+}
+
+fn setup(mut commands: Commands) {
+    commands.spawn(Camera2d);
+}
+
+fn setup_game(mut commands: Commands, asset_server: Res<AssetServer>) {
+    commands.spawn(Sprite::from_image(asset_server.load("branding/icon.png")));
+    info!("Setup game");
+}
+
+fn teardown_game(mut commands: Commands, player: Single<Entity, With<Sprite>>) {
+    commands.entity(*player).despawn();
+    info!("Teardown game");
+}
+
+#[derive(Resource)]
+struct MenuData {
+    pub button_entity: Entity,
+}
+
+const NORMAL_BUTTON: Color = Color::srgb(0.15, 0.15, 0.15);
+const HOVERED_BUTTON: Color = Color::srgb(0.25, 0.25, 0.25);
+const PRESSED_BUTTON: Color = Color::srgb(0.35, 0.75, 0.35);
+
+fn setup_menu(mut commands: Commands) {
+    let button_entity = commands
+        .spawn((
+            Node {
+                // center button
+                width: Val::Percent(100.),
+                height: Val::Percent(100.),
+                justify_content: JustifyContent::Center,
+                align_items: AlignItems::Center,
+                ..default()
+            },
+            children![(
+                Button,
+                Node {
+                    width: Val::Px(150.),
+                    height: Val::Px(65.),
+                    // horizontally center child text
+                    justify_content: JustifyContent::Center,
+                    // vertically center child text
+                    align_items: AlignItems::Center,
+                    ..default()
+                },
+                BackgroundColor(NORMAL_BUTTON),
+                children![(
+                    Text::new("Play"),
+                    TextFont {
+                        font_size: 33.0,
+                        ..default()
+                    },
+                    TextColor(Color::srgb(0.9, 0.9, 0.9)),
+                )]
+            )],
+        ))
+        .id();
+    commands.insert_resource(MenuData { button_entity });
+}

vendor/bevy/examples/state/states.rs

@@ -0,0 +1,156 @@
+//! This example illustrates how to use [`States`] for high-level app control flow.
+//! States are a powerful but intuitive tool for controlling which logic runs when.
+//! You can have multiple independent states, and the [`OnEnter`] and [`OnExit`] schedules
+//! can be used to great effect to ensure that you handle setup and teardown appropriately.
+//!
+//! In this case, we're transitioning from a `Menu` state to an `InGame` state.
+
+use bevy::{dev_tools::states::*, prelude::*};
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .init_state::<AppState>() // Alternatively we could use .insert_state(AppState::Menu)
+        .add_systems(Startup, setup)
+        // This system runs when we enter `AppState::Menu`, during the `StateTransition` schedule.
+        // All systems from the exit schedule of the state we're leaving are run first,
+        // and then all systems from the enter schedule of the state we're entering are run second.
+        .add_systems(OnEnter(AppState::Menu), setup_menu)
+        // By contrast, update systems are stored in the `Update` schedule. They simply
+        // check the value of the `State<T>` resource to see if they should run each frame.
+        .add_systems(Update, menu.run_if(in_state(AppState::Menu)))
+        .add_systems(OnExit(AppState::Menu), cleanup_menu)
+        .add_systems(OnEnter(AppState::InGame), setup_game)
+        .add_systems(
+            Update,
+            (movement, change_color).run_if(in_state(AppState::InGame)),
+        )
+        .add_systems(Update, log_transitions::<AppState>)
+        .run();
+}
+
+#[derive(Debug, Clone, Copy, Default, Eq, PartialEq, Hash, States)]
+enum AppState {
+    #[default]
+    Menu,
+    InGame,
+}
+
+#[derive(Resource)]
+struct MenuData {
+    button_entity: Entity,
+}
+
+const NORMAL_BUTTON: Color = Color::srgb(0.15, 0.15, 0.15);
+const HOVERED_BUTTON: Color = Color::srgb(0.25, 0.25, 0.25);
+const PRESSED_BUTTON: Color = Color::srgb(0.35, 0.75, 0.35);
+
+fn setup(mut commands: Commands) {
+    commands.spawn(Camera2d);
+}
+
+fn setup_menu(mut commands: Commands) {
+    let button_entity = commands
+        .spawn((
+            Node {
+                // center button
+                width: Val::Percent(100.),
+                height: Val::Percent(100.),
+                justify_content: JustifyContent::Center,
+                align_items: AlignItems::Center,
+                ..default()
+            },
+            children![(
+                Button,
+                Node {
+                    width: Val::Px(150.),
+                    height: Val::Px(65.),
+                    // horizontally center child text
+                    justify_content: JustifyContent::Center,
+                    // vertically center child text
+                    align_items: AlignItems::Center,
+                    ..default()
+                },
+                BackgroundColor(NORMAL_BUTTON),
+                children![(
+                    Text::new("Play"),
+                    TextFont {
+                        font_size: 33.0,
+                        ..default()
+                    },
+                    TextColor(Color::srgb(0.9, 0.9, 0.9)),
+                )],
+            )],
+        ))
+        .id();
+    commands.insert_resource(MenuData { button_entity });
+}
+
+fn menu(
+    mut next_state: ResMut<NextState<AppState>>,
+    mut interaction_query: Query<
+        (&Interaction, &mut BackgroundColor),
+        (Changed<Interaction>, With<Button>),
+    >,
+) {
+    for (interaction, mut color) in &mut interaction_query {
+        match *interaction {
+            Interaction::Pressed => {
+                *color = PRESSED_BUTTON.into();
+                next_state.set(AppState::InGame);
+            }
+            Interaction::Hovered => {
+                *color = HOVERED_BUTTON.into();
+            }
+            Interaction::None => {
+                *color = NORMAL_BUTTON.into();
+            }
+        }
+    }
+}
+
+fn cleanup_menu(mut commands: Commands, menu_data: Res<MenuData>) {
+    commands.entity(menu_data.button_entity).despawn();
+}
+
+fn setup_game(mut commands: Commands, asset_server: Res<AssetServer>) {
+    commands.spawn(Sprite::from_image(asset_server.load("branding/icon.png")));
+}
+
+const SPEED: f32 = 100.0;
+fn movement(
+    time: Res<Time>,
+    input: Res<ButtonInput<KeyCode>>,
+    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() * SPEED * time.delta_secs();
+        }
+    }
+}
+
+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();
+    }
+}

vendor/bevy/examples/state/sub_states.rs

@@ -0,0 +1,233 @@
+//! This example illustrates the use of [`SubStates`] for more complex state handling patterns.
+//!
+//! [`SubStates`] are [`States`] that only exist while the App is in another [`State`]. They can
+//! be used to create more complex patterns while relying on simple enums, or to de-couple certain
+//! elements of complex state objects.
+//!
+//! In this case, we're transitioning from a `Menu` state to an `InGame` state, at which point we create
+//! a substate called `IsPaused` to track whether the game is paused or not.
+
+use bevy::{dev_tools::states::*, prelude::*};
+
+use ui::*;
+
+#[derive(Debug, Clone, Copy, Default, Eq, PartialEq, Hash, States)]
+enum AppState {
+    #[default]
+    Menu,
+    InGame,
+}
+
+// In this case, instead of deriving `States`, we derive `SubStates`
+#[derive(Debug, Clone, Copy, Default, Eq, PartialEq, Hash, SubStates)]
+// And we need to add an attribute to let us know what the source state is
+// and what value it needs to have. This will ensure that unless we're
+// in [`AppState::InGame`], the [`IsPaused`] state resource
+// will not exist.
+#[source(AppState = AppState::InGame)]
+#[states(scoped_entities)]
+enum IsPaused {
+    #[default]
+    Running,
+    Paused,
+}
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .init_state::<AppState>()
+        .add_sub_state::<IsPaused>() // We set the substate up here.
+        // Most of these remain the same
+        .add_systems(Startup, setup)
+        .add_systems(OnEnter(AppState::Menu), setup_menu)
+        .add_systems(Update, menu.run_if(in_state(AppState::Menu)))
+        .add_systems(OnExit(AppState::Menu), cleanup_menu)
+        .add_systems(OnEnter(AppState::InGame), setup_game)
+        .add_systems(OnEnter(IsPaused::Paused), setup_paused_screen)
+        .add_systems(
+            Update,
+            (
+                // Instead of relying on [`AppState::InGame`] here, we're relying on
+                // [`IsPaused::Running`], since we don't want movement or color changes
+                // if we're paused
+                (movement, change_color).run_if(in_state(IsPaused::Running)),
+                // The pause toggle, on the other hand, needs to work whether we're
+                // paused or not, so it uses [`AppState::InGame`] instead.
+                toggle_pause.run_if(in_state(AppState::InGame)),
+            ),
+        )
+        .add_systems(Update, log_transitions::<AppState>)
+        .run();
+}
+
+fn menu(
+    mut next_state: ResMut<NextState<AppState>>,
+    mut interaction_query: Query<
+        (&Interaction, &mut BackgroundColor),
+        (Changed<Interaction>, With<Button>),
+    >,
+) {
+    for (interaction, mut color) in &mut interaction_query {
+        match *interaction {
+            Interaction::Pressed => {
+                *color = PRESSED_BUTTON.into();
+                next_state.set(AppState::InGame);
+            }
+            Interaction::Hovered => {
+                *color = HOVERED_BUTTON.into();
+            }
+            Interaction::None => {
+                *color = NORMAL_BUTTON.into();
+            }
+        }
+    }
+}
+
+fn cleanup_menu(mut commands: Commands, menu_data: Res<MenuData>) {
+    commands.entity(menu_data.button_entity).despawn();
+}
+
+const SPEED: f32 = 100.0;
+fn movement(
+    time: Res<Time>,
+    input: Res<ButtonInput<KeyCode>>,
+    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() * SPEED * time.delta_secs();
+        }
+    }
+}
+
+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();
+    }
+}
+
+fn toggle_pause(
+    input: Res<ButtonInput<KeyCode>>,
+    current_state: Res<State<IsPaused>>,
+    mut next_state: ResMut<NextState<IsPaused>>,
+) {
+    if input.just_pressed(KeyCode::Space) {
+        next_state.set(match current_state.get() {
+            IsPaused::Running => IsPaused::Paused,
+            IsPaused::Paused => IsPaused::Running,
+        });
+    }
+}
+
+mod ui {
+    use crate::*;
+
+    #[derive(Resource)]
+    pub struct MenuData {
+        pub button_entity: Entity,
+    }
+
+    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 fn setup(mut commands: Commands) {
+        commands.spawn(Camera2d);
+    }
+
+    pub fn setup_menu(mut commands: Commands) {
+        let button_entity = commands
+            .spawn((
+                Node {
+                    // center button
+                    width: Val::Percent(100.),
+                    height: Val::Percent(100.),
+                    justify_content: JustifyContent::Center,
+                    align_items: AlignItems::Center,
+                    ..default()
+                },
+                children![(
+                    Button,
+                    Node {
+                        width: Val::Px(150.),
+                        height: Val::Px(65.),
+                        // horizontally center child text
+                        justify_content: JustifyContent::Center,
+                        // vertically center child text
+                        align_items: AlignItems::Center,
+                        ..default()
+                    },
+                    BackgroundColor(NORMAL_BUTTON),
+                    children![(
+                        Text::new("Play"),
+                        TextFont {
+                            font_size: 33.0,
+                            ..default()
+                        },
+                        TextColor(Color::srgb(0.9, 0.9, 0.9)),
+                    )]
+                )],
+            ))
+            .id();
+        commands.insert_resource(MenuData { button_entity });
+    }
+
+    pub fn setup_game(mut commands: Commands, asset_server: Res<AssetServer>) {
+        commands.spawn(Sprite::from_image(asset_server.load("branding/icon.png")));
+    }
+
+    pub fn setup_paused_screen(mut commands: Commands) {
+        commands.spawn((
+            StateScoped(IsPaused::Paused),
+            Node {
+                // center button
+                width: Val::Percent(100.),
+                height: Val::Percent(100.),
+                justify_content: JustifyContent::Center,
+                align_items: AlignItems::Center,
+                flex_direction: FlexDirection::Column,
+                row_gap: Val::Px(10.),
+                ..default()
+            },
+            children![(
+                Node {
+                    width: Val::Px(400.),
+                    height: Val::Px(400.),
+                    // horizontally center child text
+                    justify_content: JustifyContent::Center,
+                    // vertically center child text
+                    align_items: AlignItems::Center,
+                    ..default()
+                },
+                BackgroundColor(NORMAL_BUTTON),
+                children![(
+                    Text::new("Paused"),
+                    TextFont {
+                        font_size: 33.0,
+                        ..default()
+                    },
+                    TextColor(Color::srgb(0.9, 0.9, 0.9)),
+                )]
+            )],
+        ));
+    }
+}