Double_Dot_State is a usefull crate for maintaining state management in rust

It is primarily used for state-management in Bevy but will soon include a feature to make it work for any rust project, ie. won't implement any Bevy features and just check if state transitions are valid.

What Double_Dot_State accomplishes

Properly managing State can be a cumbersome task. Take this state diagram as an example

In this example there is a mix of linear and arbitrary state transitions.

Managing this state is made easier thanks to the DoubleState macro.

DoubleState will implement States from Bevy automatically.

All you need to do is define linear or arbitrary state transitions for your state enum.

#[derive(Debug, Clone, Default, DoubleState)]
pub enum AppState {
    #[default]
    #[linear(MainMenu)]
    Loading,
    #[linear(Playing)]
    #[arbitrary(Exit)]
    MainMenu,
    #[linear(Paused)]
    Playing,
    #[linear(Playing)]
    #[arbitrary(MainMenu, Exit)]
    Paused,
    Exit
} 

note you'll get a compiler error if no default state is defined via the Default derive macro.

The DoubleState derive macro will take each attribute placed on each state and check if they are valid enum fields. So if OptionMenu (which doesn't exist) is defined as a linear transition from MainMenu you'd get a compiler error telling you "OptionMenu" doesn't exist as a state in "AppState". Knowing this cuts down on runtime errors.

Only 1 linear transition is allowed per state, however you can define an unlimited amount of arbitrary transitions.

Usage

After defining your state enum, add it to Bevy via the add_double_state() method from AppExt which is added onto App from double_dot_state

use bevy::prelude::*;
fn main() {
    App::new()
        // your implementation here
        .add_double_state::<AppState>()
    ;
}

Linear Transitions

After your AppState is in the system you could for example trantition to the MainMenu state after finished loading assets.

fn load_assets(
    mut texture_atlases: ResMut<Assets<TextureAtlas>>,
    mut next_state: EventWriter<DoubleStateEvent<AppState>>
) {
    // load your assets

    // transition into the next linear state defined in the enum type
    next_state.send(DoubleStateEvent(DoubleStateTransition::Linear));
}

DoubleStateTransition::Linear tells double_dot_state the you want to attempt a linear state transition from the current state.

note This will panic with the message No linear transition found for "AppState::Loading" if no linear transition is defined for Loading which is the current AppState in this example. Panicing here is important, as a bug like this will render your program useless anyways. Knowing this can help with debugging your code.

Arbitrary Transitions

If you have a state that can transition to multiple arbitrary ones you can transition to whichever state you want.

So if you want to transition to MainMenu from Paused you can do so like this

fn pause_menu(
    mut state: EventWriter<DoubleStateEvent<AppState>>
) {
    // your pause menu implementation here
    
    // if the user clicks Main Menu transition to MainMenu state
    next_state.send(DoubleStateEvent(DoubleStateTransition::Arbitrary(AppState::MainMenu)));
}

DoubleStateTransition::Arbitrary tells double_dot_state that you want to attempt an arbitrary transition from the current AppState to the new AppState.

note This will panic with the message Arbitrary transition "MainMenu" not found for "AppState::Paused" if the specified new transition doesn't exist for Paused which is the current AppState in this example. Panicing here is important, as a bug like this will render your program useless anyways. Knowing this can help with debugging your code.

License Dual-licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0) MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT) at your option.

Contribution Unless you explicitly state otherwise, any contribution intentionally submitted via GitHub Repo for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.