`bevy_gearbox`

A Bevy plugin for managing entity states with support for hierarchical state machines.

Why Use This?

States are components. bevy_gearbox integrates seemlessly with the bevy ecs and query systems.

State changes are handled by observers, meaning you'll never have a character that is both Idle and Dead.

State machines can be hierarchical, meaning one state machine can give control to a child state machine.

Perfect for game entities that need complex state management. I'm using it for my character and ability systems.

Quick Example

use bevy::prelude::*;
use bevy_gearbox::prelude::*;

#[derive(Component)]
struct Player;

#[derive(Component, Clone, Debug, Default)]
struct IdleState;

#[derive(Component, Clone, Debug)]
struct RunningState { speed: f32 }

#[derive(Component, Clone, Debug)]
struct JumpingState;

// Define the state machine. Think of this as defining a set of 
// mutually exclusive components. Exclusivity is maintained with
// observers. 
state_machine!(Player;
    IdleState,     // First state must implement Default
    RunningState,
    JumpingState
);

fn movement_system(
    mut commands: Commands,
    keyboard: Res<ButtonInput<KeyCode>>,
    players: Query<Entity, With<Player>>,
) {
    for player in &players {
        if keyboard.just_pressed(KeyCode::Space) {
            commands.entity(player).transition(JumpingState);
        } else if keyboard.pressed(KeyCode::KeyW) {
            commands.entity(player).transition(RunningState { speed: 10.0 });
        } else {
            commands.entity(player).transition(IdleState);
        }
    }
}

Core Concepts

State Machine Definition (generated by `state_machine!()`)

Owner Component: A Bevy component that identifies the state machine
State Components: Components representing individual states (first state must implement Default)
state_machine! Macro: Connects the owner to its possible states and generates:
- A <OwnerName>StateEnum to track current state
- A <OwnerName>Plugin with necessary systems
- A set of observers that ensure mutual exclusivity between components defined in the body.

State Transitions

Use the StateTransitionCommandsExt trait:

commands.entity(entity).transition(NewState);

The generated systems handle removing old state components and adding new ones automatically.

Hierarchical State Machines

For advanced use cases, bevy_gearbox supports parent-child state machine relationships using special states:

RestingState: Default inactive state for child state machines (supports "blockers")
WorkingState: Active state when controlled by parent
InChildSMState(Entity): Parent state when delegating to child
FinishedChildSMState(Entity): Parent state when child completes
FizzledState: Child state when parent exits prematurely

Setup

Add to your project:

cargo add bevy_gearbox

Add plugins to your app:

use bevy::prelude::*;
use bevy_gearbox::GearboxPlugin;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(GearboxPlugin)
        .add_plugins(PlayerPlugin)  // Your generated plugin
        // ... other setup
        .run();
}

Spawn entities:

// Starts in IdleState automatically
commands.spawn(Player);

Querying States

// Query by state component
fn idle_system(idle_players: Query<Entity, With<IdleState>>) { }

// Query by state enum
fn current_state_system(
    players: Query<&PlayerStateEnum, With<Player>>
) {
    for state in &players {
        match state {
            PlayerStateEnum::IdleState => { /* ... */ }
            PlayerStateEnum::RunningState => { /* ... */ }
            PlayerStateEnum::JumpingState => { /* ... */ }
        }
    }
}

Advanced Features

Hierarchical State Machines: Parent state machines can delegate control to child state machines
State Blocking: Prevent transitions based on conditions (e.g., cooldowns, resource requirements)
Automatic State Management: Handle complex parent-child state transitions automatically

Version Compatibility

bevy_gearbox	bevy
0.2.0	0.16
0.1.2	0.16

TODO

Add comprehensive HSM examples (character abilities, AI behavior trees)
Add state blocking examples (cooldowns, resource management)
Add complex nested state machine example

bevy_gearbox 0.2.0

bevy_gearbox