bevy-butler

Relevant Skills

Rust
Metaprogramming and Macros
Github Actions
Game Engine Development

Development Timeline

January 6, 2025: bevy-butler is created
January 22, 2025: Version 0.5.0 is released as the first stable version

Description

bevy-butler is a plugin for the Bevy engine, an experimental ECS engine built in Rust. It lets developers cut down on boilerplate by annotating their system functions, events, resources, and other objects to automatically add them to their game's event scheduler. It adds numerous procedural macros that allow annotating systems and structures to automatically include them in a specified plugin, rather than having to manually register them all in the plugin's build function.

Before I created this crate, Bevy systems were laid out in a way that splits implementation details between multiple locations. The system functions and parameters were declared at the function, but details like scheduling, ordering, and run conditions are declared when the system is registered.


// System implementation happens here...
fn player_add_gravity(
    mut query: Query<&mut Transform, With<Player>>,
    time: Res<Time>,
) {
    for mut xform in &mut query {
        xform.translation -= Vec3::new(0.0, 9.8, 0.0) * time.elapsed_secs();
    }
}

struct PlayerPlugin;

impl Plugin for PlayerPlugin {
    fn build(&self, app: &mut App) {
        // ...but scheduling happens all the way down here!
        app.add_systems(FixedUpdate, player_add_gravity);
    }
}

This fragmentation of implementation details makes maintaining a much larger project with many interconnected systems much more difficult. bevy-butler is an attempt to fix this by putting system registration details directly at the system declaration


// System scheduling details are right above the implementation!
#[system(plugin = PlayerPlugin, schedule = FixedUpdate)]
fn player_add_gravity(
    mut query: Query<&mut Transform, With<Player>>,
    time: Res<Time>,
) {
    for mut xform in &mut query {
        xform.translation -= Vec3::new(0.0, 9.8, 0.0) * time.elapsed_secs();
    }
}

// `Plugin` is automatically implemented with `player_add_gravity` included.
#[butler_plugin]
struct PlayerPlugin;

The declaration of systems can also include other scheduling details in this annotation, like run conditions and ordering.


// Runs before `goodbye_world` if the `Hello` resource exists
#[system(
    plugin = HelloPlugin,
    schedule = Startup,
    run_if = resource_exists::<Hello>,
    before = goodbye_world
)]
fn hello_world() {
    info!("Hello, world!");
}

// Runs after `hello_world` if the `Hello` resource exists
#[system(
    plugin = HelloPlugin,
    schedule = Startup,
    run_if = resource_exists::<Hello>,
    after = hello_world
)]
fn goodbye_world() {
    info!("Goodbye, world!");
}

There are macros for many other Bevy features, including observers, events and resources.