Trait godot_core::obj::script::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, GDExtensionCallErrorType>;
    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;
}

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().

Example

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

// 1) Define the script.
#[derive(GodotClass)]
#[class(init, base=ScriptExtension)]
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 {
    unsafe fn instance_create(&self, _for_object: Gd<Object>) -> *mut std::ffi::c_void {
        // Upcast Gd<ScriptExtension> to Gd<Script>.
        let script = self.to_gd().upcast();
        let script_instance = MyInstance::from_gd(script);

        // Note on safety: the returned pointer must be obtained
        // through create_script_instance().
        create_script_instance(script_instance)
    }
}

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, GDExtensionCallErrorType>

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. If this function and IScriptExtension::is_placeholder_fallback_enabled return true, Godot will call Self::property_set_fallback instead of Self::set_property.

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 Gd<T> which contains a reference counted object 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 types getter.

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

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

Object Safety

This trait is not object safe.

Implementors