Struct SiMut

Source

pub struct SiMut<'a, T: ScriptInstance> { /* private fields */ }

Expand description

Mutable/exclusive reference guard for a T where T implements ScriptInstance.

This can be used to access the base object of a ScriptInstance, which in turn can be used to make reentrant calls to engine APIs. For details see SiMut::base_mut().

Implementations§

Source §

impl<'a, T: ScriptInstance> SiMut<'a, T>

Source

pub fn base(&self) -> ScriptBaseRef<'_, T>

Returns a shared reference suitable for calling engine methods on this object.

Holding a shared guard prevents other code paths from obtaining a mutable reference to self, as such it is recommended to drop the guard as soon as you no longer need it.


struct ExampleScriptInstance;

impl ScriptInstance for ExampleScriptInstance {
    type Base = Node;

    fn call(
        this: SiMut<Self>,
        method: StringName,
        args: &[&Variant],
    ) -> Result<Variant, CallErrorType>{
        let name = this.base().get_name();
        godot_print!("name is {name}");
        // However, we cannot call methods that require `&mut Base`, such as:
        // this.base().add_child(&node);
        Ok(Variant::nil())
    }
}

Source

pub fn base_mut(&mut self) -> ScriptBaseMut<'_, T>

Returns a mutable reference suitable for calling engine methods on this object.

This method will allow you to call back into the same object from Godot (re-entrancy). You have to keep the ScriptBaseRef guard bound for the entire duration the engine might re-enter a function of your ScriptInstance. The guard temporarily absorbs the &mut self reference, which allows for an additional mutable reference to be acquired.

Holding a mutable guard prevents other code paths from obtaining any reference to self, as such it is recommended to drop the guard as soon as you no longer need it.


struct ExampleScriptInstance;

impl ScriptInstance for ExampleScriptInstance {
    type Base = Object;

    fn call(
        mut this: SiMut<Self>,
        method: StringName,
        args: &[&Variant],
    ) -> Result<Variant, CallErrorType> {
        // Check whether method is available on this script
        if method == StringName::from("script_method") {
            godot_print!("script_method called!");
            return Ok(true.to_variant());
        }

        let node = Node::new_alloc();

        // We can call back into `self` through Godot:
        this.base_mut().call("script_method", &[]);

        Ok(Variant::nil())
    }
}