Bevy State Machines Agent Skill

Bevy state machines

When to use

Load this when the app needs a large-scale mode (paused, in a menu, loading) or when one entity needs a small mode flag. Use bevy::state for the first. Use a component for the second. Keep those two owners separate.

ECS shape

• App states. bevy::state: states are app-wide finite state machines. Three types implement States.
• Standard states change only by setting the NextState<S> resource.
• SubStates also use NextState<S>, and are removed from the World when source states are not in the required state.
• ComputedStates derive from other states through a compute method.
• Transition schedules. OnEnter<S>, OnExit<S>, and OnTransition<S> run systems on matching transitions. StateTransitionEvent<S> fires when state S changes. Run conditions: in_state<S> and state_changed<S>.
• Entity lifetime. DespawnOnEnter<S> and DespawnOnExit<S> despawn entities on those transitions (state_scoped).
• Feature. bevy_state ships in the default bevy app plugins. Install a state with init_state.
• Per-entity mode. Store an enum in a Component and branch in a system. That enum is not a States type.

[dependencies]
bevy = "0.20"

App modes are States. Gameplay systems use in_state. Pause writes NextState.

#[derive(States, Debug, Clone, Copy, Eq, PartialEq, Hash, Default)]
enum AppMode {
    #[default]
    Menu,
    Play,
}

fn show_menu(mut commands: Commands) {
    commands.spawn((Name::new("menu"), DespawnOnExit(AppMode::Menu)));
}

fn spawn_player(mut commands: Commands) {
    commands.spawn((Name::new("player"), Transform::default()));
}

fn request_play(keys: Res<ButtonInput<KeyCode>>, mut next: ResMut<NextState<AppMode>>) {
    if keys.just_pressed(KeyCode::Enter) {
        next.set(AppMode::Play);
    }
}

pub struct ModePlugin;

impl Plugin for ModePlugin {
    fn build(&self, app: &mut App) {
        app.init_state::<AppMode>()
            .add_systems(OnEnter(AppMode::Menu), show_menu)
            .add_systems(OnEnter(AppMode::Play), spawn_player)
            .add_systems(Update, request_play.run_if(in_state(AppMode::Menu)));
    }
}

A pause flag exists only while AppMode::Play is active. SubStates removes it otherwise.

#[derive(States, Debug, Clone, Copy, Eq, PartialEq, Hash, Default)]
enum AppMode {
    #[default]
    Menu,
    Play,
}

#[derive(SubStates, Debug, Clone, Copy, Eq, PartialEq, Hash, Default)]
#[source(AppMode = AppMode::Play)]
enum Session {
    #[default]
    Running,
    Paused,
}

fn toggle_pause(
    keys: Res<ButtonInput<KeyCode>>,
    session: Res<State<Session>>,
    mut next: ResMut<NextState<Session>>,
) {
    if keys.just_pressed(KeyCode::Escape) {
        let flipped = match session.get() {
            Session::Running => Session::Paused,
            Session::Paused => Session::Running,
        };
        next.set(flipped);
    }
}

fn install_pause(app: &mut App) {
    app.add_sub_state::<Session>()
        .add_systems(Update, toggle_pause.run_if(in_state(Session::Running)));
}

One actor's stance is a component. It does not change the app state.

#[derive(Component, Clone, Copy, PartialEq, Eq)]
enum Stance {
    Idle,
    Attack,
}

fn begin_attack(keys: Res<ButtonInput<KeyCode>>, mut actors: Query<&mut Stance>) {
    if keys.just_pressed(KeyCode::KeyF) {
        for mut stance in &mut actors {
            *stance = Stance::Attack;
        }
    }
}

Choose the owner

| Need | Owner |

| --- | --- |

| App mode (menu, pause, play) | A States type and NextState<S> |

| Run logic only in one mode | in_state or an OnEnter / OnExit / OnTransition schedule |

| Child mode that exists only inside a parent mode | SubStates |

| Mode derived from other modes | ComputedStates |

| One actor's stance | An enum Component plus a system. Not States unless it is truly app-wide |

Scope

• Install app modes with init_state. Install a child mode with add_sub_state.
• OnEnter, OnExit, and in_state cover the schedules shown above.
• A per-entity stance is the Stance component. Animation graphs belong on bevy-animation-graph.

Expert Knowledge Delta

Target: Bevy 0.20+.

Core ECS types: Component, Resource, Query, Commands, Startup, Update, Fixed / FixedMain (bevy::time), .chain(), Plugin, DefaultPlugins, MinimalPlugins. Messages and observers are an ownership slot. See bevy-events-messaging for their APIs. Systems run in parallel unless .chain() orders the ones that conflict.

Who owns state

| Piece | Owner | Who may mutate | Schedule |

| --- | --- | --- | --- |

| Data on one entity | Component | One system via Query | Update or FixedMain |

| One value for the whole app | Resource | One system | Startup to insert, then the schedule that reads it |

| Spawn | Commands | The spawning system | Startup for the initial world; later schedules for runtime spawn |

| Order that must not race | .chain() | The chained systems only | Same schedule |

| Plugin boundary | Plugin | build registers systems and resources | Before the app runs |

Borrow rule: two systems that both mutably query the same component must be ordered (.chain()) or split so only one writes. Unrelated systems stay parallel. That is the ECS page rule, not a guess at a system-set API.

Decision

| If you need | Do this | Do not |

| --- | --- | --- |

| Per-entity data | Component + Query | A value that is not a component |

| App-wide config or clock | Resource | Copy the value onto every entity |

| Stable simulation step | FixedMain and the Fixed clock | Tie simulation to raw frame Update |

| Startup spawn | Commands in Startup | Spawn from a render system |

| Cross-system notice that is not shared state | Message or observer slot in bevy-events-messaging | A new event type invented in this file |

| An API outside the documented set | Check the official docs first | A made-up crate or API |

Load references/ecs-ownership.md for the ownership table.

NEVER

• Do not pin /0.20.0/ in docs URLs. WHY: links stay on latest; the 0.20 target is stated once in prose.
• Do not mutably query the same component from two unordered systems. WHY: the schedule runs systems in parallel unless .chain() orders them.
• Do not invent a physics, navigation, networking, or XR crate here. WHY: this skill only names documented Bevy crates and modules.

• No Godot animation-tree or node state-machine types. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.
• No invented App state-setup methods. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.
• No third-party crates. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.

Reference

The library pin on bevy-master stays 0.20.0.

Official Documentation

• Quick Start: ECS - Component and Query for a per-entity mode flag.
• Examples - Example tree on the latest branch. State examples live in that tree.

Related Skills

Prerequisites

• bevy-master - Schedules versus a scene tree.
• bevy-data-resources - NextState<S> is a resource. Per-entity modes are components.

Complements

• bevy-events-messaging - Messages and observers that are not state transitions.
• godot-state-machine-advanced - Equivalent Godot skill. Do not import Godot types.

Downstream / consumers

• bevy-character-movement - Actor motion. A jump or ground mode stays a component unless a mode needs States.

Master

• bevy-master - Bevy router.