🎚️ Moonshine Behavior

Minimalistic state machine for Bevy entities.

Overview

This crates is designed to provide a simple, stack-based implementation of state machines for Bevy entities.

Features

• Simple: Minimal overhead for defining and setting up behaviors.
• Behaviors can be started, paused, resumed, and stopped.
• Event driven API which allows systems to react to behavior state change per entity.
• Multiple behaviors with different types may exist on the same entity to define complex state machines.

Usage

A behavior, typically implemented as an enum, is a Component which represents some state of its entity. Each behavior is associated with a Stack.

When a new behavior starts, the current state is removed from the entity and pushed onto the stack (if resumable) and paused.

When a behavior stops, the previous state is removed from the stack and inserted back into the entity.

Setup

1. Define your behavior data as a Component

Behaviors are often implemented as an enum since they are ideal for representing finite state machines. However, this is not a strict requirement. Any struct may also be used to represent behavior states.

use bevy::prelude::*;

#[derive(Component, Debug, Reflect)]
#[reflect(Component)]
enum Bird {
    /* ... */
}

2. Implement the Behavior trait:

use bevy::prelude::*;
use moonshine_behavior::prelude::*;

#[derive(Component, Debug, Reflect)]
#[reflect(Component)]
enum Bird {
    Idle,
    Fly,
    Sleep,
    Chirp,
}

impl Behavior for Bird {
    fn filter_next(&self, next: &Self) -> bool {
        use Bird::*;
        match_next! {
            self => next,
            Idle => Sleep | Fly | Chirp,
            Fly => Chirp,
        }
    }
}

This trait defines the possible transitions for your behavior.

In this example:

• a bird may sleep, fly, or chirp when idle
• a bird may chirp when flying
• a bird may not do anything else when sleeping or chirping

This trait has additional methods for more advanced usage. See Behavior trait documentation for full details.

3. Register the Behavior and its transition:

Add a BehaviorPlugin and the transition system to your App to trigger behavior transitions whenever you want.

use bevy::prelude::*;
use moonshine_behavior::prelude::*;

#[derive(Component, Debug, Reflect)]
#[reflect(Component)]
enum Bird {
    /* ... */
}

impl Behavior for Bird {
    /* ... */
}

let mut app = App::new();
app.add_plugins(BehaviorPlugin::<Bird>::default())
    .add_systems(Update, transition::<Bird>);

You may define your systems before or after the transition system.

Usually, systems that cause behavior change should run before transition while systems that handle behavior logic should run after transition. However, this is not a strict requirement. Just be mindful of frame delays!

4. Spawn

The first instance of T which is inserted into the entity is defined as the Initial Behavior:

fn spawn_bird(mut commands: Commands) {
    commands.spawn(Bird::Idle); // <--- Bird starts in Idle state
}

You may also spawn a bird with a Transition:

fn spawn_bird(mut commands: Commands) {
    commands.spawn((Bird::Idle, Next(Bird::Chirp))); // <--- Bird starts in Idle state and then Chirps!
}

Or maybe even a TransitionSequence:

fn spawn_bird(mut commands: Commands) {
    commands.spawn((
        Bird::Idle,
        TransitionSequence::wait_for(Bird::Chirp).then(Bird::Fly)
    ));
}

5. Query

To manage the behavior of an entity, you may use the BehaviorRef<T> and BehaviorMut<T> Query terms:

fn update_bird(mut query: Query<BehaviorMut<Bird>>) {
    for mut behavior in query.iter_mut() {
        match behavior.current() {
            Bird::Idle => {
                // Do something when the bird is idle
            }
            Bird::Chirp => {
                // TODO: Play Chirp sound!
                behavior.stop(); // <-- Go back to the previous state
            }
            _ => { /* ... */ }
        }
    }
}

BehaviorRef<T> is a read-only reference to the current behavior and the entire stack.

BehaviorMut<T> extends BehaviorRef<T> and allows you to modify the behavior as well.

Note that you may also access your behavior as &T or &mut T directly (it is just a component after all!).

Transition<T> is also directly accessible as a component, however it is more ergonomic to use BehaviorMut<T> for transitions.

Transitions

When a transition is requested, it is not invoked immediately. Instead, it is invoked whenever the registered transition system is run. You may register your systems before or after transition::<T> to perform any logic as required.

⚠️ WARNING
In most cases, only one transition is allowed per entity, per cycle.

This is by design to allow each state to get at least one active frame.

The exception to this is during an interruption or a reset, where multiple behaviors may be stopped at once.

To invoke a transition, you may use the BehaviorMut<T>. There are several methods for invoking transitions:

• start Pauses the current behavior and starts a new one.
• interrupt_start Stops all behaviors which yield to the new behavior, and then starts the new behavior.
• interrupt_resume Stops all behaviors above a given index in the stack and resumes it.
• interrupt_stop Stops all behaviors above and including given index in the stack, resuming the previous one.
• stop Stops the current behavior and resumes the previous one.
• reset Stops all behaviors and resets the entity to its initial state.

Regardless of the method used, all transition may fail if:

• The new behavior does not allow the new behavior to start at the exact time of transition. See filter_next.
• The current behavior is the initial behavior and a stop is requested. The initial behavior may never be stopped.

To completely stop the behavior, including the initial, you must remove the entire behavior from the entity. To do this, use remove_with_require::<T>() to remove the initial behavior and the entire behavior stack.

Events

When a transition is invoked, several behavior events are triggered. You may use the following triggers to react to these events:

• OnStart<T> - Triggered when a new behavior starts.
• OnPause<T> - Triggered when a behavior is paused as the next one starts.
• OnResume<T> - Triggered when a behavior is resumed as the previous one stops.
• OnActivate<T> - Triggered when a behavior is activated (started OR resumed).
• OnStop<T> - Triggered when a behavior stops.

See events documentation for more details.

Hooks

In addition to events, you may also use hooks to perform immediate actions during a transition. Hooks are methods on the Behavior trait which may optionally be implemented by you:

impl Behavior for Bird {
    fn on_start(&self, _previous: Option<&Self>, mut commands: InstanceCommands<Self>) {
        match self {
            Bird::Chirp => {
                commands.insert(PlayAudio { /* ... */});
            }
            _ => { /* ... */ }
        }
    }
}

These hook commands would be executed immediately after transition is invoked. They are mainly useful when trying to minimize frame delays between state changes.

Examples

See signal.rs for a complete example.

Support

Please post an issue for any bugs, questions, or suggestions.

You may also contact me on the official Bevy Discord server as @Zeenobit.