bevyengine/bevy

bevy_state

Typed state machines for an App. The standard pattern for "is the game in the menu, in gameplay, or paused?" — schedules attached to specific states run only when that state is active.

Purpose

bevy_state provides:

States trait + #[derive(States)] — declare a typed state enum.
State<S> resource — the current state.
NextState<S> resource — set this to queue a transition.
OnEnter / OnExit / OnTransition schedules — run systems on state changes.
in_state<S>() run condition — gate systems on a state.
SubStates and ComputedStates — derived state machines.

Directory layout

crates/bevy_state/src/
├── lib.rs
├── state/                  # State trait + State<S> + NextState<S>
├── condition.rs            # in_state, state_changed
├── reflect.rs              # Reflection bridge
└── prelude.rs

Key abstractions

Type	File	Description
`States` (trait)	`crates/bevy_state/src/state/states.rs`	Marker trait for state enums.
`State<S>`	`crates/bevy_state/src/state/resources.rs`	Resource: current state.
`NextState<S>`	`crates/bevy_state/src/state/resources.rs`	Resource: pending state.
`OnEnter<S>`, `OnExit<S>`, `OnTransition<S, S>`	`crates/bevy_state/src/state/transitions.rs`	Schedule labels for transitions.
`SubStates`	`crates/bevy_state/src/state/sub_states.rs`	Sub-state of another state.
`ComputedStates`	`crates/bevy_state/src/state/computed_states.rs`	Derived state machines.

How it works

graph LR
    Update --> StateTransition
    StateTransition -->|queued?| OnExit[OnExit<S>]
    OnExit --> OnTransition[OnTransition<from, to>]
    OnTransition --> OnEnter[OnEnter<S>]
    OnEnter --> Update2[Update next frame]

The StateTransition schedule runs between PreUpdate and Update. If NextState<S>::Pending(_) is set, it runs OnExit<from>, OnTransition<from, to>, OnEnter<to> in order, then updates State<S>.

Systems registered against Update with .run_if(in_state(GameState::Playing)) only run when the current state matches.

Integration points

Depends on: bevy_app, bevy_ecs, bevy_reflect.
Depended on by: DefaultPlugins, lots of user code.

Entry points for modification

New transition mechanism: state/transitions.rs.
Computed states: state/computed_states.rs. The trait derives a state from one or more inputs; useful when "paused" is computed from other state plus a flag.
Run-condition helpers: condition.rs.