Introduction

Welcome to the godot-rust book! This is a work-in-progress user guide for gdext, the Rust binding for Godot 4.

If you're new to Rust, before getting started, it is highly recommended that you familiarize yourself with concepts outlined in the officially maintained Rust Book.

To read the book about gdnative (Godot 3 binding), follow this link.

The purpose of godot-rust

Godot is a batteries-included game engine that fosters a productive and fun gamedev workflow. It ships GDScript as a built-in scripting language and also provides official support for C++ and C# bindings. Its GDExtension mechanism allows more languages to be integrated, in our case Rust.

Rust brings a modern, robust and performant experience to game development. If you are interested in scalability, strong type systems or just enjoy Rust as a language, you may consider using it with Godot, to combine the best of both worlds.

About this project

godot-rust is a community-developed open source project. It is maintained independently of Godot itself, but we are in close contact with engine developers, to foster a steady exchange of ideas. This has allowed us to address a lot of Rust's needs upstream, but also led to improvements of the engine itself in several cases.

Currently supported features

For an up-to-date overview of implementation status, consult issue #24.

Terminology

To avoid confusion, here is an explanation of names and technologies you may encounter over the course of this book:

  • godot-rust: The entire project, encompassing Rust bindings for Godot 3 and 4, as well as related efforts (book, community, etc.).
  • GDExtension: C API provided by Godot 4.
  • GDNative: C API provided by Godot 3.
  • gdext (lowercase): the Rust binding for GDExtension (Godot 4) -- what this book focuses on.
  • gdnative (lowercase): the Rust binding for GDNative (Godot 3).
  • Extension: An extension is a dynamic C library, developed by any language binding (Rust, C++, Swift, ...). It uses the GDExtension API and can be loaded by Godot 4.

GDExtension API: what's new

This section briefly mentions the difference between the native interfaces in Godot 3 and 4 from a functional point of view, without going into Rust.

While the underlying FFI (foreign function interface) layer has been completely rewritten, a lot of concepts remain the same from a user point of view. In particular, Godot's approach with a node-based scene graph, composed of classes in an inheritance relation, has not changed.

That said, there are some notable differences:

  1. No more native scripts

    With GDNative, Rust classes could be registered as native scripts. These scripts are attached to nodes in order to enhance their functionality, analogous to how GDScript scripts could be attached. GDExtension on the other hand directly supports Rust types as engine classes, see also next point.

    Keep this in mind when porting GDScript code to Rust: instead of replacing the GDScript with a native script, you need to change the node type to a Rust class that inherits the node.

  2. First-class citizen types

    In Godot 3, user-defined native classes had lots of limitations in the editor: type annotations were not fully supported, they could not easily be used as custom resources, etc. With GDExtension, user-defined classes in Rust behave much closer to GDScript classes.

  3. Always-on

    There is no differentiation between "tool" and "normal" scripts anymore, as it was the case in GDNative. Rust logic runs as soon as the Godot editor launches, but gdext explicitly changes this behavior. By default, all virtual callbacks (ready, process etc.) are not invoked in editor mode. This behavior can be configured when implementing the ExtensionLibrary trait.

  4. No recompilation while editor is open

    Prior to Godot 4.2, it was not possible to recompile a Rust library and let changes take effect when the game is launched from the editor. This has recently been implemented though, see issue #66231.

**