Attribute Macro godot_api

#[godot_api]

Proc-macro attribute to be used with impl blocks of #[derive(GodotClass)] structs.

Can be used in two ways:

#[derive(GodotClass)]
#[class(init, base=Node)]
struct MyClass {}

// 1) inherent impl block: user-defined, custom API.
#[godot_api]
impl MyClass { /* ... */ }

// 2) trait impl block: implement Godot-specific APIs.
#[godot_api]
impl INode for MyClass { /* ... */ }

The second case works by implementing the corresponding trait I* for the base class of your class (for example IRefCounted or INode3D). Then, you can add functionality such as:

• init constructors
• lifecycle methods like ready or process
• on_notification method
• to_string method

Neither of the two #[godot_api] blocks is required. For small data bundles inheriting RefCounted, you may be fine with accessing properties directly from GDScript.

See also book chapter Registering functions and following.

Table of contents

• Constructors
  • User-defined init
  • Generated init
• Lifecycle functions
• User-defined functions
  • Associated functions and methods
  • Virtual methods
• Constants and signals

Constructors

Note that init (the Godot default constructor) can be either provided by overriding it, or generated with a #[class(init)] attribute on the struct. Classes without init cannot be instantiated from GDScript.

User-defined init

#[derive(GodotClass)]
// no #[class(init)] here, since init() is overridden below.
// #[class(base=RefCounted)] is implied if no base is specified.
struct MyStruct;

#[godot_api]
impl IRefCounted for MyStruct {
    fn init(_base: Base<RefCounted>) -> Self {
        MyStruct
    }
}

Generated init

This initializes the Base<T> field, and every other field with either Default::default() or the value specified in #[init(val = ...)].

#[derive(GodotClass)]
#[class(init, base=Node)]
pub struct MyNode {
    base: Base<Node>,

    #[init(val = 42)]
    some_integer: i64,
}

Lifecycle functions

You can override the lifecycle functions ready, process, physics_process and so on, by implementing the trait corresponding to the base class.

#[derive(GodotClass)]
#[class(init, base=Node)]
pub struct MyNode;

#[godot_api]
impl INode for MyNode {
    fn ready(&mut self) {
        godot_print!("Hello World!");
    }
}

Using any trait other than the one corresponding with the base class will result in compilation failure.

#[derive(GodotClass)]
#[class(init, base=Node3D)]
pub struct My3DNode;

#[godot_api]
impl INode for My3DNode {
    fn ready(&mut self) {
        godot_print!("Hello World!");
    }
}

User-defined functions

You can use the #[func] attribute to declare your own functions. These are exposed to Godot and callable from GDScript.

Associated functions and methods

If #[func] functions are called from the engine, they implicitly bind the surrounding Gd<T> pointer: Gd::bind() in case of &self, Gd::bind_mut() in case of &mut self. To avoid that, use #[func(gd_self)], which requires an explicit first argument of type Gd<T>.

Functions without a receiver become static functions in Godot. They can be called from GDScript using MyStruct.static_function(). If they return Gd<Self>, they are effectively constructors that allow taking arguments.

#[derive(GodotClass)]
#[class(init)]
struct MyStruct {
    field: i64,
    base: Base<RefCounted>,
}

#[godot_api]
impl MyStruct {
    #[func]
    pub fn hello_world(&mut self) {
        godot_print!("Hello World!")
    }

    #[func]
    pub fn static_function(constructor_arg: i64) -> Gd<Self> {
        Gd::from_init_fn(|base| {
           MyStruct { field: constructor_arg, base }
        })
    }

    #[func(gd_self)]
    pub fn explicit_receiver(mut this: Gd<Self>, other_arg: bool) {
        // Only bind Gd pointer if needed.
        if other_arg {
            this.bind_mut().field = 55;
        }
    }
}

Virtual methods

Functions with the #[func(virtual)] attribute are virtual functions, meaning attached scripts can override them.

#[derive(GodotClass)]
#[class(init)]
struct MyStruct {
    // Virtual functions require base object.
    base: Base<RefCounted>,
}

#[godot_api]
impl MyStruct {
    #[func(virtual)]
    fn language(&self) -> GString {
        "Rust".into()
    }
}

In GDScript, your method is available with a _ prefix, following Godot convention for virtual methods:

extends MyStruct

func _language():
   return "GDScript"

Now, obj.language() from Rust will dynamically dispatch the call.

Make sure you understand the limitations in the tutorial.

Constants and signals

Please refer to the book.