godot-bevy

godot-bevy brings Bevy's powerful ECS to Godot, allowing you to write high-performance game logic in Rust while leveraging Godot's excellent editor and rendering capabilities.

Special thanks to Blaze for their support of this project. They provide high-performance Linux (AMD64 & ARM64) and Apple Silicon macOS runners for GitHub Actions, greatly reducing our automated build times.

📚 Documentation

Read the godot-bevy Book →

The book covers everything you need to know: - Installation and setup - Core concepts and architecture - Plugin system (opt-in features) - Transform system and physics - Input handling - Examples and best practices

🚀 Quick Start

Add to your Cargo.toml:

[dependencies]
godot-bevy = "0.11.0"  # Latest with opt-in plugin system
bevy = { version = "0.18", default-features = false }
godot = "0.4"

Basic example:

use bevy::prelude::*;
use godot::prelude::*;
use godot_bevy::prelude::*;

#[bevy_app]
fn build_app(app: &mut App) {
    // Add the features you need (v0.8+ opt-in plugin system)
    app.add_plugins(GodotTransformSyncPlugin::default())  // Transform sync
        .add_plugins(GodotAudioPlugin);                   // Audio system

    // Print to the Godot console
    godot_print!("Hello from Godot-Bevy!");

    // Add your game systems
    app.add_systems(Update, position_system);
}

// A system is a normal Rust function. This system moves all Node2Ds to the right, such as Sprite2Ds.
//
// The `transform` parameter is a Bevy `Query` that matches all `Transform` components.
// `Transform` is a Godot-Bevy-provided component that matches all Node2Ds in the scene.
// (https://docs.rs/godot-bevy/latest/godot_bevy/plugins/core/transforms/struct.Transform.html)
//
// For more information on Bevy Components, Systems, and Queries, see:
// (https://bevy.org/learn/quick-start/getting-started/ecs/).
fn position_system(mut transform: Query<&mut Transform>) {
    // For single matches, you can use `single_mut()` instead:
    // `if let Ok(mut transform) = transform.single_mut() {`
    for mut transform in transform.iter_mut() {
        // Move the node to the right.
        transform.translation.x += 1.0;
    }
}

🔧 Plugin System (v0.8+)

godot-bevy now uses an opt-in plugin system for maximum efficiency:

// Minimal setup - only core features
#[bevy_app]
fn build_app(app: &mut App) {
    // Scene tree and assets included by default
    app.add_systems(Update, my_systems);
}

// Add specific features as needed
#[bevy_app]
fn build_app(app: &mut App) {
    app.add_plugins(GodotTransformSyncPlugin::default())  // Transform sync
        .add_plugins(GodotAudioPlugin)                    // Audio system
        .add_plugins(BevyInputBridgePlugin);              // Input handling
}

// Or everything at once (like v0.7.x)
#[bevy_app]
fn build_app(app: &mut App) {
    app.add_plugins(GodotDefaultPlugins);
}

Benefits: Smaller binaries, better performance, clearer dependencies. See the Plugin System Guide for details.

🎮 Examples

Check out the examples directory: - 2D Platformer - Physics-based platformer - Dodge the Creeps - Classic arcade game - Simple Movement - Basic transform usage

✨ Inspiration and Acknowledgements

This library was inspired by and originally built upon the work of bevy_godot, which provided similar functionality for Godot 3. godot-bevy extends this concept to support Godot 4 and Bevy 0.16. It has now diverged quite a bit.

⊹ Version Compatibility Matrix

🦀 MSRV

The minimum supported Rust version is 1.88.0.

The MSRV is the minimum Rust version that can be used to compile each crate.

📕 License

godot-bevy is distributed under the terms of both the MIT license and the Apache License (Version 2.0). See LICENSE-APACHE and LICENSE-MIT for details. Opening a pull request is assumed to signal agreement with these licensing terms.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Developing environment

If you're on MacOS or Linux, you can quickly get started developing against this package using https://devenv.sh/, and (optionally) https://direnv.net/. Once they are setup/installed, you can leverage devenv shell in the root of this package to setup a development environment that includes all system dependencies, rust, godot, and other developer tools used in this package. Check out devenv.nix for details. You can, of course, skip this and use system-installed tooling of your own; but keep in mind that your system dependency versions (like Godot) may drift from what other contributors or our CI tooling use.