Struct Callable

pub struct Callable { /* private fields */ }

Expand description

A Callable represents a function in Godot.

Usually a callable is a reference to an Object and a method name, this is a standard callable. But can also be a custom callable, which is usually created from bind, unbind, or a GDScript lambda. See Callable::is_custom.

Currently, it is impossible to use bind and unbind in GDExtension, see godot-cpp#802.

§Godot docs

Callable (stable)

Implementations§

§

impl Callable

pub fn from_object_method<T, S>(object: &Gd<T>, method_name: S) -> Callable
where T: GodotClass, S: AsArg<StringName>,

Create a callable for the method object::method_name.

pub fn from_local_fn<F, S>(name: S, rust_function: F) -> Callable
where F: 'static + FnMut(&[&Variant]) -> Result<Variant, ()>, S: AsArg<GString>,

Available on since_api="4.2" only.

Create callable from single-threaded Rust function or closure.

name is used for the string representation of the closure, which helps debugging.

This constructor only allows the callable to be invoked from the same thread as creating it. If you need to invoke it from any thread, use from_sync_fn instead (requires crate feature experimental-threads; only enable if really needed).

pub fn from_sync_fn<F, S>(name: S, rust_function: F) -> Callable
where F: 'static + Send + Sync + FnMut(&[&Variant]) -> Result<Variant, ()>, S: AsArg<GString>,

Available on since_api="4.2" only.

Create callable from thread-safe Rust function or closure.

name is used for the string representation of the closure, which helps debugging.

This constructor requires Send + Sync bound and allows the callable to be invoked from any thread. If you guarantee that you invoke it from the same thread as creating it, use from_local_fn instead.

Callables created through multiple from_local_fn or from_sync_fn() calls are never equal, even if they refer to the same function. If you want to use equality, either clone an existing Callable instance, or define your own PartialEq impl with Callable::from_custom.

§Example

let callable = Callable::from_sync_fn("sum", |args: &[&Variant]| {
    let sum: i32 = args.iter().map(|arg| arg.to::<i32>()).sum();
    Ok(sum.to_variant())
});

pub fn from_fn<F, S>(name: S, rust_function: F) -> Callable
where F: 'static + Send + Sync + FnMut(&[&Variant]) -> Result<Variant, ()>, S: Into<GString>,

👎Deprecated: Now split into from_local_fn (single-threaded) and from_sync_fn (multi-threaded).

Available on since_api="4.2" only.

pub fn from_custom<C>(callable: C) -> Callable
where C: RustCallable,

Available on since_api="4.2" only.

Create a highly configurable callable from Rust.

See RustCallable for requirements on the type.

pub fn invalid() -> Callable

Creates an invalid/empty object that cannot be called.

Godot equivalent: Callable()

pub fn callv(&self, arguments: &Array<Variant>) -> Variant

Calls the method represented by this callable.

Arguments passed should match the method’s signature.

If called with more arguments than expected by the method, the extra arguments will be ignored and the call continues as normal.
If called with fewer arguments than expected it will crash Godot, without triggering UB.
If called with arguments of the wrong type then an error will be printed and the call will return NIL.
If called on an invalid Callable then no error is printed, and NIL is returned.

Godot equivalent: callv

pub fn bindv(&self, arguments: &Array<Variant>) -> Callable

Returns a copy of this Callable with one or more arguments bound, reading them from an array.

Godot equivalent: bindv

pub fn method_name(&self) -> Option<StringName>

Returns the name of the method represented by this callable. If the callable is a lambda function, returns the surrounding function’s name.

§Known Bugs

Getting the name of a lambda errors instead of returning its name, see godot#73052.

Godot equivalent: get_method

pub fn object(&self) -> Option<Gd<Object>>

Returns the object on which this callable is called.

Returns None when this callable doesn’t have any target object to call a method on (regardless of whether the method exists for that target or not). Also returns None if the object is dead. You can differentiate these two cases using object_id().

Godot equivalent: get_object