Tracking issue for feature parity with bevy_butler

[StrikeForceZero]

Since there have been a couple of issues people encountered when migrating from bevy_butler to bevy_auto_plugin, I figured I'd create a tracking issue so other people can have a bird's-eye view of any open issues that may affect their migration.

I apologize for any inconvenience. I'll set aside some time to work on a migration guide as a way to help me identify any other holes that might exist.

• Support for OnEnter schedule in auto_add_system #29
• System configs don't let you call functions #32
• Let system configs be declared multiple times? #33
• (no issue yet) PluginGroups

---

Shout out to @TGRCdev for their original code in bevy_butler, which inspired the more intuitive global mode implementation here (using linkme/inventory). Even though the code was already open-source, they still gave me their blessings to integrate a similar approach. They even suggested using darling, which cut down on a lot of boilerplate for macro parsing logic.

[StrikeForceZero]

bevy_butler → bevy_auto_plugin: Migration Guide

This guide helps you migrate attributes/macros from bevy_butler to bevy_auto_plugin with clear 1:1 mappings, syntax changes, and examples. It’s formatted for easy copy-paste.

---

Key Syntax Changes

• Generics argument

  • Butler: generics = <T1, T2, ...>
  • Auto Plugin: generics(T1, T2, ...)

• Multiple concrete sets supported

  • You can repeat generics(...) to generate for many type lists with a single attribute, e.g.
    generics(bool, usize), generics(bool, u32).

---

TL;DR: Mapping Table

Note: to save screen real-estate generics are omitted, most attributes support them

Status Legend:

• ✅ Fully implemented
• 🟨 Mostly implemented
• 🟧 PR
• 🟥 Not yet

Butler	Auto Plugin	Required args	Optional args / notes	Status
butler_plugin	derive(AutoPlugin) / auto_plugin	—	see "Plugin" section below	✅
add_message	auto_add_message	plugin = PluginType	see docs	✅
add_observer	auto_add_observer	plugin = PluginType	see docs	✅
insert_resource	auto_insert_resource	plugin = PluginType resource(...)	see docs	✅
insert_state	auto_init_state	plugin = PluginType	see docs	✅
register_type	auto_register_type / auto_register_state_type	plugin = PluginType	auto_register_type auto_register_state_type	✅
add_system	auto_add_system / auto_system	plugin = PluginType schedule = Schedule	see docs config(...) missing pipe_in	🟨
add_sub_state	auto_init_sub_state	—	PR	✅
add_plugin	auto_add_plugin	—	PR	🟨
add_plugin_group	(TODO)	—	—	🟥
butler_plugin_group	(TODO)	—	—	🟥
N/A	auto_init_resource	plugin = PluginType see docs	see docs	✅
N/A	auto_name	plugin = PluginType see docs	see docs name = "..."	✅
N/A	auto_component	plugin = PluginType see docs	see docs	✅
N/A	auto_event	plugin = PluginType see docs	see docs	✅
N/A	auto_message	plugin = PluginType see docs	see docs	✅
N/A	auto_observer	plugin = PluginType see docs	see docs	✅
N/A	auto_resource	plugin = PluginType see docs	see docs	✅
N/A	auto_states	plugin = PluginType see docs	see docs	✅
N/A	auto_bind_plugin	plugin = PluginType	makes plugin = ... optional for all attributes below it	✅

---

Quick Examples

Plugin

There are three distinct ways to make a bindable plugin:

#[derive(AutoPlugin)]
#[auto_plugin(impl_plugin_trait)]
struct MyPlugin;

#[derive(AutoPlugin)]
struct MyPlugin;

impl Plugin for MyPlugin {
    #[auto_plugin]
    def build(&self, app: &mut App) {
        //
    }
}

#[derive(AutoPlugin)]
struct MyPlugin;

#[auto_plugin(plugin = MyPlugin)]
fn plugin(app: &mut App) {
    //
}

There are auto_plugin arguments if your plugin has generics.

---

Messages

// Butler
// #[derive(...)]
#[add_message(plugin = MyPlugin, generics = <T>)]
struct Message<T>(T);

// Auto Plugin
// #[derive(...)]
#[auto_add_message(plugin = MyPlugin, generics(T))]
struct Message<T>(T);

Multiple sets:

// #[derive(...)]
#[auto_add_message(plugin = MyPlugin, generics(bool, usize), generics(bool, u32))]
struct Message<T1, T2>(T1, T2);

---

Observers

// Butler
#[add_observer(plugin = MyPlugin, generics = <T>)]
fn on_event(_: On<T>) {}

// Auto Plugin
#[auto_add_observer(plugin = MyPlugin, generics(T))]
fn on_event(_: On<T>) {}

---

Resources

// Butler
// #[derive(...)]
#[insert_resource(plugin = MyPlugin, generics = <T>)]
struct MyResource<T>(T);

// Auto Plugin
// #[derive(...)]
#[auto_insert_resource(plugin = MyPlugin, generics(T))]
struct MyResource<T>(T);

---

States

// Butler
// #[derive(...)]
#[insert_state(plugin = MyPlugin, generics = <S>)]
enum MyState<T> {
  #[default]
  Init,
  Something(T),
}

// Auto Plugin
// #[derive(...)]
#[auto_init_state(plugin = MyPlugin, generics(S))]
enum MyState<T> {
  #[default]
  Init,
  Something(T),
}

---

Type Registration

// Butler
// #[derive(...)]
#[register_type(plugin = MyPlugin, generics = <T>)]
struct FooComponent<T>(T);

// Auto Plugin
// #[derive(...)]
#[auto_register_type(plugin = MyPlugin, generics(T))]
struct FooComponent<T>(T);

// For Bevy States:
// #[derive(...)]
#[auto_register_state_type(plugin = MyPlugin, generics(S))]
enum MyState<T> {
  #[default]
  Init,
  Something(T),
}

---

Systems

// Butler
#[add_system(plugin = MyPlugin, schedule = Update, generics = <T>)]
fn sys<T: Resource>(_: Res<T>) {}

// Auto Plugin
#[auto_system(
  plugin = MyPlugin,
  schedule = Update,
  generics(T),
  config(
    in_set = MySet,
    before = OtherSetOrSystem,
    after = AnotherSetOrSystem,
    run_if = some_condition,
    distributive_run_if = some_distributive_condition,
    ambiguous_with = SomeSystem,
    ambiguous_with_all = true,
    after_ignore_deferred = Foo,
    before_ignore_deferred = Bar,
  )
)]
fn sys<T: Resource>(_: Res<T>) {}

The config(...) keys correspond to Bevy’s IntoScheduleConfigs helpers.

---

Generics Examples

Component

If your items have generics, specify the concrete types using generics(...) (repeatable):

#[derive(AutoPlugin)]
#[auto_plugin(impl_plugin_trait)]
struct MyPlugin;

// #[derive(...)]
#[auto_component(
    plugin = MyPlugin,
    generics(usize, bool),
    generics(bool, bool),
    derive(Debug, Default),
    reflect(Debug, Default),
    register,
    auto_name,
)]
struct FooComponent<A, B>(A, B);

Generates something equivalent to:

impl Plugin for MyPlugin {
    fn build(&self, app: &mut App) {
        app.register_type::<FooComponent<usize, bool>>();
        app.register_type::<FooComponent<bool, bool>>();
    }
}

System

#[auto_system(
    plugin = MyPlugin,
    schedule = Update, 
    generics(Name), 
    generics(Transform),
    config( 
        run_if = some_condition,
        after = some_other_system,
    ),
)]
fn my_system<A: Component>(q: Query<&A>) {
    for _ in q.iter() {
        // ...
    }
}

Generates something equivalent to:

impl Plugin for MyPlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(Update, my_system::<Name>.run_if(some_condition).after(some_other_system));
        app.add_systems(Update, my_system::<Transform>.run_if(some_condition).after(some_other_system));
    }
}

---

“Mostly Implemented” Notes

• auto_system supports config(...) transforms that mirror Bevy’s schedule config methods:
  • in_set,
  • before,
  • after
  • run_if,
  • distributive_run_if
  • ambiguous_with,
  • ambiguous_with_all
  • after_ignore_deferred,
  • before_ignore_deferred
• pipe_in TODO

---

Not Yet Implemented (with Workarounds)

add_sub_state → TODO

Workaround (not recommended):

use bevy_auto_plugin::prelude::*;
use bevy::prelude::*;

#[derive(AutoPlugin)]
#[auto_plugin(impl_plugin_trait)]
struct MyPlugin;

#[derive(SubState)]
enum YourSubState {}

#[auto_run_on_build(plugin = MyPlugin)]
fn _add_sub_state(app: &mut App) {
    bevy_state::app::AppExtStates::add_sub_state::<YourSubState>(app);
}

---

add_plugin → TODO

Workaround (not recommended):

use bevy_auto_plugin::prelude::*;
use bevy::prelude::*;

#[derive(AutoPlugin)]
#[auto_plugin(impl_plugin_trait)]
struct MyRootPlugin;

mod my_sub_plugin {
    use super::*;

    #[derive(AutoPlugin)]
    #[auto_plugin(impl_plugin_trait)]
    struct MySubPlugin;

    #[auto_run_on_build(plugin = MyRootPlugin)]
    fn register_plugin(app: &mut App) {
        app.add_plugins(MySubPlugin);
    }
}

---

Migration Tips

• Prefer derive(AutoPlugin)
  Use #[derive(AutoPlugin)] plus #[auto_plugin(...)] for plugin definitions.
• Generics
  • Search & Replace generics
    • Change generics = <...> → generics(...).
  • Combine attributes where desired:
    • Use multiple generics(...) entries on a single attribute to generate multiple concrete registrations at once.
• System Schedule Configs via config(...)
  Move any set/before/after/run-if annotations into a single config(...) list per attribute.
• auto_run_on_build is provided for stopgaps or potentially exotic requirements.