Trait ScriptInstance 

pub trait ScriptInstance: Sized {
    type Base: GodotClass;

    // Required methods
    fn class_name(&self) -> GString;
    fn set_property(
        this: SiMut<'_, Self>,
        name: StringName,
        value: &Variant,
    ) -> bool;
    fn get_property(&self, name: StringName) -> Option<Variant>;
    fn get_property_list(&self) -> Vec<PropertyInfo>;
    fn get_method_list(&self) -> Vec<MethodInfo>;
    fn call(
        this: SiMut<'_, Self>,
        method: StringName,
        args: &[&Variant],
    ) -> Result<Variant, CallErrorType>;
    fn is_placeholder(&self) -> bool;
    fn has_method(&self, method: StringName) -> bool;
    fn get_script(&self) -> &Gd<Script>;
    fn get_property_type(&self, name: StringName) -> VariantType;
    fn to_string(&self) -> GString;
    fn get_property_state(&self) -> Vec<(StringName, Variant)>;
    fn get_language(&self) -> Gd<ScriptLanguage>;
    fn on_refcount_decremented(&self) -> bool;
    fn on_refcount_incremented(&self);
    fn property_get_fallback(&self, name: StringName) -> Option<Variant>;
    fn property_set_fallback(
        this: SiMut<'_, Self>,
        name: StringName,
        value: &Variant,
    ) -> bool;
    fn get_method_argument_count(&self, _method: StringName) -> Option<u32>;

    // Provided methods
    fn on_property_get_revert(&self, name: StringName) -> Option<Variant> { ... }
    fn on_validate_property(
        &self,
        property: PropertyInfo,
    ) -> Option<PropertyInfo> { ... }
    fn on_notification(this: SiMut<'_, Self>, what: i32, reversed: bool) { ... }
    fn get_class_category(&self) -> Option<&PropertyInfo> { ... }
    fn get_owner(&self) -> Option<Gd<Object>> { ... }
}

Implement custom scripts that can be attached to objects in Godot.

To use script instances, implement this trait for your own type.

You can use the create_script_instance() function to create a low-level pointer to your script instance. This pointer should then be returned from IScriptExtension::instance_create_rawptr().

Example

use godot::prelude::*;
use godot::classes::{Script, ScriptExtension};
use godot::extras::{IScriptExtension, ScriptInstance};

// 1) Define the script.
// This needs #[class(tool)] since the script extension runs in the editor.
#[derive(GodotClass)]
#[class(init, base=ScriptExtension, tool)]
struct MyScript {
   base: Base<ScriptExtension>,
   // ... other fields
}

// 2) Define the script _instance_, and implement the trait for it.
struct MyInstance;
impl MyInstance {
    fn from_gd(script: Gd<Script>) -> Self {
        Self { /* ... */ }
    }
}

impl ScriptInstance for MyInstance {
    // Implement all the methods...
}

// 3) Implement the script's virtual interface to wire up 1) and 2).
#[godot_api]
impl IScriptExtension for MyScript {
    // Implement all the methods...
}

Required Associated Types

type Base: GodotClass

Required Methods

fn class_name(&self) -> GString

Name of the new class the script implements.

fn set_property( this: SiMut<'_, Self>, name: StringName, value: &Variant, ) -> bool

Property setter for Godot’s virtual dispatch system.

The engine will call this function when it wants to change a property on the script.

fn get_property(&self, name: StringName) -> Option<Variant>

Property getter for Godot’s virtual dispatch system.

The engine will call this function when it wants to read a property on the script.

fn get_property_list(&self) -> Vec<PropertyInfo>

A list of all the properties a script exposes to the engine.

fn get_method_list(&self) -> Vec<MethodInfo>

A list of all the methods a script exposes to the engine.

fn call( this: SiMut<'_, Self>, method: StringName, args: &[&Variant], ) -> Result<Variant, CallErrorType>

Method invoker for Godot’s virtual dispatch system. The engine will call this function when it wants to call a method on the script.

All method calls are taking a mutable reference of the script instance, as the engine does not differentiate between immutable and mutable method calls like rust.

It’s important that the script does not cause a second call to this function while executing a method call. This would result in a panic.

fn is_placeholder(&self) -> bool

Identifies the script instance as a placeholder, routing property writes to a fallback if applicable.

If this function and IScriptExtension::is_placeholder_fallback_enabled return true, Godot will call Self::property_set_fallback instead of Self::set_property.

Note: this is the script-side placeholder (broken/unavailable script), distinct from the class-side editor placeholder substituted for “runtime classes” (non-tool classes, that don’t run in the editor).

fn has_method(&self, method: StringName) -> bool

Validation function for the engine to verify if the script exposes a certain method.

fn get_script(&self) -> &Gd<Script>

Lets the engine get a reference to the script this instance was created for.

This function has to return a reference, because scripts are reference-counted in Godot, and it must be guaranteed that the object is not freed before the engine increased the reference count. (Every time a ref-counted Gd<T> is dropped, the reference count is decremented.)

fn get_property_type(&self, name: StringName) -> VariantType

Lets the engine fetch the type of a particular property.

fn to_string(&self) -> GString

String representation of the script instance.

fn get_property_state(&self) -> Vec<(StringName, Variant)>

A dump of all property names and values that are exposed to the engine.

fn get_language(&self) -> Gd<ScriptLanguage>

Lets the engine get a reference to the ScriptLanguage this instance belongs to.

fn on_refcount_decremented(&self) -> bool

Callback from the engine when the reference count of the base object has been decreased. When this method returns true the engine will not free the object the script is attached to.

fn on_refcount_incremented(&self)

Callback from the engine when the reference count of the base object has been increased.

fn property_get_fallback(&self, name: StringName) -> Option<Variant>

The engine may call this function if it failed to get a property value via ScriptInstance::get_property or the native type’s getter.

fn property_set_fallback( this: SiMut<'_, Self>, name: StringName, value: &Variant, ) -> bool

The engine may call this function if IScriptExtension::is_placeholder_fallback_enabled is enabled.

fn get_method_argument_count(&self, _method: StringName) -> Option<u32>

Available on since_api=4.3 only.

This function will be called to handle calls to Object::get_method_argument_count and Callable::get_argument_count.

If None is returned the public methods will return 0.

Provided Methods

fn on_property_get_revert(&self, name: StringName) -> Option<Variant>

Lets the script instance return a default value for a property.

This is a combination of Godot’s ScriptInstance::_property_get_revert and ScriptInstance::_property_can_revert. This means that this function will usually be called twice by Godot to find the revert.

Note that this should be a pure function. That is, it should always return the same value for a property as long as self remains unchanged. Otherwise, this may lead to unexpected (safe) behavior.

fn on_validate_property(&self, property: PropertyInfo) -> Option<PropertyInfo>

Lets the script instance modify existing properties.

Function will be called for every existing property. See official engine documentation for details.

fn on_notification(this: SiMut<'_, Self>, what: i32, reversed: bool)

This function will be called for every incoming lifecycle notification. To create a GDScript equivalent implementation, the script instance should forward this call to a _notification function in the script.

fn get_class_category(&self) -> Option<&PropertyInfo>

Provides a way to override the behavior of ScriptExtension::get_class_category on a per instance basis.

The engine expects a PropertyInfo with the script name as the property_name, the script path as the hint_string and PropertyUsageFlags::CATEGORY as the usage flag.

fn get_owner(&self) -> Option<Gd<Object>>

Lets the engine get a reference to the object this instance was created for.

The engine uses this function inside the built-in debugger to get the script’s “self” object.

This function has to return a reference, because the owner might be reference-counted in Godot, and it must be guaranteed that the object is not freed before the engine increased the reference count. (Every time a ref-counted Gd<T> is dropped, the reference count is decremented.)

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors