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.

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.

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

#[gdextension]
unsafe impl ExtensionLibrary for MyExtension {}

Safety

By using godot-rust, you accept the safety considerations as outlined in the book. Please make sure you fully understand the implications.

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.

Object Safety

This trait is not object safe.

Implementors