Bevy Plugin System: Modular App Initialization

Problem & Desired Outcome

When a Bevy game grows, the main binary quickly becomes a tangled mix of asset loading, resource setup, and system registration. Developers often struggle to keep the core main.rs lean while ensuring deterministic startup order across different modules.

The goal is to encapsulate all initialization logic—resources, assets, systems—inside a reusable Plugin. Adding the plugin via App::add_plugins keeps the binary small, improves testability, and guarantees that each component starts in the correct order.

Prerequisites

• Rust toolchain (1.70+ recommended) and a Cargo project with bevy = "0.12" in Cargo.toml.
• Basic familiarity with Bevy ECS: Resources, Components, Systems, and the App builder pattern.
• Understanding that Plugin is a trait with a build method that receives a mutable App.

Focused Procedure

Below is a step‑by‑step example that demonstrates how to create a plugin that:

1. Inserts a custom resource.
2. Adds a startup system that logs a message.
3. Registers an update system that modifies the resource each frame.
4. Ensures the plugin is added before App::run.

1. Define the Resource and Plugin Struct

use bevy::prelude::*;

/// Simple counter resource.
#[derive(Debug, Default, Resource)]
pub struct Counter {
    pub count: u32,
}

/// Marker struct for the plugin.
pub struct CounterPlugin;

2. Implement the Plugin Trait

impl Plugin for CounterPlugin {
    fn build(&self, app: &mut App) {
        // 2.1 Insert the resource.
        app.insert_resource(Counter::default());

        // 2.2 Register a startup system.
        app.add_startup_system(startup_system);

        // 2.3 Register an update system.
        app.add_system(update_system);
    }
}

fn startup_system(mut counter: ResMut<Counter>) {
    counter.count = 42; // deterministic start value
    info!("Counter initialized to {}", counter.count);
}

fn update_system(mut counter: ResMut<Counter>) {
    counter.count += 1;
    debug!("Counter updated to {}", counter.count);
}

3. Wire the Plugin into main.rs

fn main() {
    App::new()
        .add_plugins(DefaultPlugins) // core Bevy plugins
        .add_plugins(CounterPlugin)   // our custom plugin
        .run();
}

Run the app with cargo run. The startup system should log the initial value, and the update system will increment the counter every frame.

Expected Checks

• During startup, the log line Counter initialized to 42 appears once.
• On each frame, the debug log Counter updated to N shows the counter incrementing.
• No duplicate resource errors or system registration panics are reported.
• Inspect the app’s resource list (e.g., via a debug system) to confirm Counter is present.

Recovery & Troubleshooting

• Duplicate Plugin Registration: If the same plugin is added twice, Bevy will panic during startup. Verify the plugin is only added once by checking the add_plugins call chain.
• System Ordering Conflicts: If another system needs to run before startup_system, use before or in_set to enforce order: app.add_system(startup_system.before(<OtherSet>));
• Missing Resource in Systems: If a system panics due to a missing resource, ensure the resource is inserted in the same plugin or an earlier plugin.
• Version‑Sensitive API Changes: Bevy 0.12 introduced add_systems for stage‑based registration. If you upgrade, replace add_system calls accordingly or refer to the changelog.

Limitations & Practical Verification

The example assumes a stable release of Bevy (0.12) and a simple console output. In production, you might replace info! and debug! with structured logging or an in‑game UI. To verify determinism, run the app with --profile=release and compare logs across runs.

Always isolate the plugin in a minimal Cargo project when debugging initialization issues. This removes interference from other plugins and makes the startup sequence easier to reason about.