Installation

This guide will walk you through setting up godot-bevy in a Godot project.

Prerequisites

Before you begin, ensure you have:

Rust 1.88.0 or later - Install Rust
Godot 4.3 - Download Godot
Basic familiarity with both Rust and Godot

Installation Methods

There are two ways to set up godot-bevy in your project:

Plugin Installation (Recommended) - Use the godot-bevy editor plugin for automatic setup
Manual Installation - Set up the project manually

Plugin Installation

The easiest way to get started is using the godot-bevy editor plugin, which automatically generates the Rust project and configures the BevyApp singleton.

1. Install the Plugin

Download the addons/godot-bevy folder from the godot-bevy repository
Copy it to your Godot project's addons/ directory
In Godot, go to Project > Project Settings > Plugins
Enable the "Godot-Bevy Integration" plugin

2. Create Your Project

Go to Project > Tools > Setup godot-bevy Project
Configure your project settings:
- Project name: Used for the Rust crate name
- godot-bevy version: Library version (default: 0.12.0)
- Release build: Whether to build in release mode initially
Click "Create Project"

The plugin will automatically:

Create a rust/ directory with Cargo.toml and lib.rs
Generate the .gdextension file with correct platform paths
Create and register the BevyApp singleton scene
Build the Rust project
Restart the editor to apply changes

3. Run Your Project

After the editor restarts:

Press F5 or click the play button
You should see "Hello from Bevy ECS!" in the output console every second

The generated rust/src/lib.rs includes a complete example.

4. Plugin Features

The plugin provides additional useful features:

Add BevyApp Singleton Only: If you already have a Rust project, use Project > Tools > Add BevyApp Singleton to just create and register the singleton
Build Rust Project: Use Project > Tools > Build Rust Project to rebuild without restarting the editor

Manual Installation

If you prefer to set up everything manually, follow these steps:

1. Set Up Godot Project

First, create a new Godot project through the Godot editor:

Open Godot and click "New Project"
Choose a project name and location
Select "Compatibility" renderer for maximum platform support
Click "Create & Edit"

2. Set Up Rust Project

In your Godot project directory, create a new Rust library:

cd /path/to/your/godot/project
cargo init --lib rust
cd rust

3. Configure Cargo.toml

Edit rust/Cargo.toml:

[package]
name = "your_game_name"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["cdylib"]

[dependencies]
godot-bevy = "0.12"
bevy = { version = "0.19", default-features = false }
godot = "0.5"

godot-bevy supports Godot API levels 4.2 through 4.6 via the mutually exclusive Cargo features api-4-2, api-4-3, api-4-4, api-4-5, and api-4-6, with or without default features. Set compatibility_minimum in your .gdextension file to the level you build against; the example below assumes 4.3.

Configure Godot Integration

1. Create Extension File

Create rust.gdextension in your Godot project root:

[configuration]
entry_symbol = "gdext_rust_init"
compatibility_minimum = 4.3
reloadable = true

[libraries]
macos.debug = "res://rust/target/debug/libyour_game_name.dylib"
macos.release = "res://rust/target/release/libyour_game_name.dylib"
windows.debug.x86_32 = "res://rust/target/debug/your_game_name.dll"
windows.release.x86_32 = "res://rust/target/release/your_game_name.dll"
windows.debug.x86_64 = "res://rust/target/debug/your_game_name.dll"
windows.release.x86_64 = "res://rust/target/release/your_game_name.dll"
linux.debug.x86_64 = "res://rust/target/debug/libyour_game_name.so"
linux.release.x86_64 = "res://rust/target/release/libyour_game_name.so"
linux.debug.arm64 = "res://rust/target/debug/libyour_game_name.so"
linux.release.arm64 = "res://rust/target/release/libyour_game_name.so"
linux.debug.rv64 = "res://rust/target/debug/libyour_game_name.so"
linux.release.rv64 = "res://rust/target/release/libyour_game_name.so"

Replace your_game_name with your actual crate name from Cargo.toml.

2. Create BevyApp Autoload

In Godot, create a new scene
Add a BevyApp node as the root
Save it as bevy_app_singleton.tscn
Go to Project → Project Settings → Globals → Autoload
Add the scene with name "BevyAppSingleton"

Write Your First Code

Edit rust/src/lib.rs:

#![allow(unused)]
fn main() {
use godot::prelude::*;
use bevy::prelude::*;
use godot_bevy::prelude::*;

#[bevy_app]
fn build_app(app: &mut App) {
    app.add_systems(Startup, hello_world);
}

fn hello_world() {
    godot::prelude::godot_print!("Hello from godot-bevy!");
}
}