Bevy Plugins

Bevy enables us to break up our game into smaller features using plugins.

A plugin is any function that takes an &mut App and modifies it. These functions can do anything in your normal App definition, even adding other plugins.

fn plugin(app: &mut App) {
  app.add_system(some_plugin_system);
}

fn main() {
  App::new().add_plugins(plugin);
}

Plugins are useful for bundling up all the setup and runtime behavior of a feature into something we can toggle on and off. Plugins encapsulate the complexity of the feature into something we can "plug-into" our app.

By performing the necessary setup such as adding systems, resources and events to your game, each plugin is responsible for injecting its behavior into your game loop.

Plugins are how third party crates add functionality to Bevy. For example, avian has a plugin that adds physics to your games.

The Plugin trait

Usually we prefer using simple functions, but if your plugin has additional life-cycle requirements you can implement the Plugin trait and define the life-cycle methods you are interested in.

pub struct CameraPlugin;

impl Plugin for CameraPlugin {
  fn cleanup(&self, _app: &mut App) {
    info!("Time to clean up");
  }

  fn build(&self, app: &mut App) {
    app.add_systems(Startup, initialize_camera);
  }
}

fn initialize_camera(mut commands: Commands) {
  commands.spawn(Camera2d);
}

Plugin life-cycle

Each Plugin will go through a life-cycle of:

1. We add our plugin to the App with add_plugins
2. Our plugin has its build method called
3. Bevy eventually calls ready on our plugin
4. Bevy internally polls to ensure all plugins succeeded
5. Finally, Bevy calls cleanup on our plugin.

Plugin ordering and dependencies

Plugins are run in the order they are added to the App. They are also defined during the app's definition phase before the app starts running. They cannot be changed at runtime.

Ideally a plugin would fully encapsulate its dependencies, but that's not always possible. Plugins that have dependencies do not currently have a good way to ensure those dependencies.

Bevy will also panic (by default) if you try and add the same plugin to your app more than once. You can work around this by checking if is_plugin_added before adding it.

fn plugin(app: &mut App) {
    if !app.is_plugin_added::<physics::PhysicsPlugin>() {
        app.add_plugins(physics::PhysicsPlugin);
    }

    if !app.is_plugin_added::<bevy::input::InputPlugin>() {
        app.add_plugins(bevy::input::InputPlugin);
    }
}

This is a good practice for testing so that the test for your plugin can run without running the entire app.

Plugin configuration

If your plugin becomes complicated enough to demand configuration you can add fields to the struct that implements Plugin.

pub struct CameraPlugin {
  debug: bool,
}

impl Plugin for CameraPlugin {
  fn build(&self, app: &mut App) {
    app.add_systems(Startup, initialize_camera);

    if self.debug {
      // Do something
    }
  }
}

fn main() {
  App::new()
    .add_plugins(CameraPlugin { debug: true })
}

Plugin groups

Having plugins call other plugins is powerful and leads to a hierarchy of plugin dependencies. This can make it hard to configure.

Collections of plugins with a complicated setup can use the PluginGroup trait which allow us to group related plugins together and then configure them later.

This can be great choice for library authors writing plugins that others can add to their game.

pub struct GamePlugins;

impl PluginGroup for GamePlugins {
  fn build(self) -> PluginGroupBuilder {
    PluginGroupBuilder::start::<Self>()
      .add(CameraPlugin::default())
      .add(PhysicsPlugin::default())
      .add(LogicPlugin)
  }
}

This will let us (or anyone consuming your plugins) configure exactly how the set of plugins runs in the context of our app:

fn main() {
  App::new()
    .add_plugins(DefaultPlugins)
    .add_plugins(
      game::GamePlugins
        .build()
        .disable::<physics::PhysicsPlugin>()
    )
    .run();
}

The default plugins

Bevy includes DefaultPlugins in the bevy::prelude which gives us all of the obvious things our game would need:

Then depending on the features you enable (all enabled by default) you have more plugins that are added:

The minimal plugins

Instead of DefaultPlugins, Bevy also provides MinimalPlugins which only includes the bare essentials to get an app running:

• TaskPoolPlugin
• FrameCountPlugin
• TimePlugin
• ScheduleRunnerPlugin
• CiTestingPlugin (with feature bevy_ci_testing)

This can be especially useful during tests to setup an app without any rendering concerns.