Trait ExtensionLibrary

pub unsafe trait ExtensionLibrary {
    // Provided methods
    fn editor_run_behavior() -> EditorRunBehavior { ... }
    fn min_level() -> InitLevel { ... }
    fn on_level_init(level: InitLevel) { ... }
    fn on_level_deinit(level: InitLevel) { ... }
    fn override_hot_reload() -> Option<bool> { ... }
}

Defines the entry point for a GDExtension Rust library.

Every library should have exactly one implementation of this trait. It is always used in combination with the #[gdextension] proc-macro attribute.

Example

The simplest usage is as follows. This will automatically perform the necessary init and cleanup routines, and register all classes marked with #[derive(GodotClass)], without needing to mention them in a central list. The order in which classes are registered is not specified.

use godot::init::*;

// This is just a type tag without any functionality.
// Its name is irrelevant.
struct MyExtension;

#[gdextension]
unsafe impl ExtensionLibrary for MyExtension {}

Custom entry symbol

There is usually no reason to, but you can use a different entry point (C function in the dynamic library). This must match the key that you specify in the .gdextension file. Let’s say your .gdextension file has such a section:

[configuration]
entry_symbol = "custom_name"

then you can implement the trait like this:

struct MyExtension;

#[gdextension(entry_symbol = custom_name)]
unsafe impl ExtensionLibrary for MyExtension {}

Note that this only changes the name. You cannot provide your own function – use the on_level_init() hook for custom startup logic.

Safety

The library cannot enforce any safety guarantees outside Rust code, which means that you as a user are responsible to uphold them: namely in GDScript code or other GDExtension bindings loaded by the engine. Violating this may cause undefined behavior, even when invoking safe functions.

Provided Methods

fn editor_run_behavior() -> EditorRunBehavior

Determines if and how an extension’s code is run in the editor.

fn min_level() -> InitLevel

Determines the initialization level at which the extension is loaded (Scene by default).

If the level is lower than [InitLevel::Scene], the engine needs to be restarted to take effect.

fn on_level_init(level: InitLevel)

Custom logic when a certain init-level of Godot is loaded.

This will only be invoked for levels >= Self::min_level(), in ascending order. Use if or match to hook to specific levels.

fn on_level_deinit(level: InitLevel)

Custom logic when a certain init-level of Godot is unloaded.

This will only be invoked for levels >= Self::min_level(), in descending order. Use if or match to hook to specific levels.

fn override_hot_reload() -> Option<bool>

Whether to enable hot reloading of this library. Return None to use the default behavior.

Enabling this will ensure that the library can be hot reloaded. If this is disabled then hot reloading may still work, but there is no guarantee. Enabling this may also lead to memory leaks, so it should not be enabled for builds that are intended to be final builds.

By default, this is enabled for debug builds and disabled for release builds.

Note that this is only checked once upon initializing the library. Changing this from true to false will be picked up as the library is then fully reloaded upon hot-reloading, however changing it from false to true is almost certainly not going to work unless hot-reloading is already working regardless of this setting.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors