Trait godot::engine::ScriptInstance

pub trait ScriptInstance {
Show 17 methods    // Required methods
    fn class_name(&self) -> GString;
    fn set_property(&mut 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(
        &mut self,
        method: StringName,
        args: &[&Variant]
    ) -> Result<Variant, u32>;
    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(
        &mut self,
        name: StringName,
        value: &Variant
    ) -> bool;
}

Expand description

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

// 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 MyScriptInstance;
impl MyScriptInstance {
    fn from_gd(script: Gd<Script>) -> Self {
        Self { /* ... */ }
    }
}

impl ScriptInstance for MyScriptInstance {
    // 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 = MyScriptInstance::from_gd(script);

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

Required Methods§

fn class_name(&self) -> GString

Name of the new class the script implements.

fn set_property(&mut 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( &mut self, method: StringName, args: &[&Variant] ) -> Result<Variant, u32>

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 has to 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.