Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Callable

代表一個方法或一個獨立函式的內建型別。

說明

Callable is a built-in Variant type that represents a function. It can either be a method within an Object instance, or a custom callable used for different purposes (see is_custom()). Like all Variant types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks.

func print_args(arg1, arg2, arg3 = ""):
    prints(arg1, arg2, arg3)

func test():
    var callable = Callable(self, "print_args")
    callable.call("hello", "world")  # Prints "hello world ".
    callable.call(Vector2.UP, 42, callable)  # Prints "(0.0, -1.0) 42 Node(node.gd)::print_args"
    callable.call("invalid")  # Invalid call, should have at least 2 arguments.

// Default parameter values are not supported.
public void PrintArgs(Variant arg1, Variant arg2, Variant arg3 = default)
{
    GD.PrintS(arg1, arg2, arg3);
}

public void Test()
{
    // Invalid calls fail silently.
    Callable callable = new Callable(this, MethodName.PrintArgs);
    callable.Call("hello", "world"); // Default parameter values are not supported, should have 3 arguments.
    callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs"
    callable.Call("invalid"); // Invalid call, should have 3 arguments.
}

In GDScript, it's possible to create lambda functions within a method. Lambda functions are custom callables that are not associated with an Object instance. Optionally, lambda functions can also be named. The name will be displayed in the debugger, or when calling get_method().

func _init():
    var my_lambda = func (message):
        print(message)

    # Prints "Hello everyone!"
    my_lambda.call("Hello everyone!")

    # Prints "Attack!", when the button_pressed signal is emitted.
    button_pressed.connect(func(): print("Attack!"))

In GDScript, you can access methods and global functions as Callables:

tween.tween_callback(node.queue_free)  # Object methods.
tween.tween_callback(array.clear)  # Methods of built-in types.
tween.tween_callback(print.bind("Test"))  # Global functions.

Note: Dictionary does not support the above due to ambiguity with keys.

var dictionary = { "hello": "world" }

# This will not work, `clear` is treated as a key.
tween.tween_callback(dictionary.clear)

# This will work.
tween.tween_callback(Callable.create(dictionary, "clear"))

Note: In a boolean context, a callable will evaluate to false if it's null (see is_null()). Otherwise, a callable will always evaluate to true.

備註

使用 C# 操作此 API 時有顯著差異，詳見 C# API 與 GDScript 的不同。

建構子

Callable	Callable()
Callable	Callable(from: Callable)
Callable	Callable(object: Object, method: StringName)

方法

Callable	bind(...) vararg const
Callable	bindv(arguments: Array)
Variant	call(...) vararg const
void	call_deferred(...) vararg const
Variant	callv(arguments: Array) const
Callable	create(variant: Variant, method: StringName) static
int	get_argument_count() const
Array	get_bound_arguments() const
int	get_bound_arguments_count() const
StringName	get_method() const
Object	get_object() const
int	get_object_id() const
int	get_unbound_arguments_count() const
int	hash() const
bool	is_custom() const
bool	is_null() const
bool	is_standard() const
bool	is_valid() const
void	rpc(...) vararg const
void	rpc_id(peer_id: int, ...) vararg const
Callable	unbind(argcount: int) const

運算子

bool	operator !=(right: Callable)
bool	operator ==(right: Callable)

建構子說明

Callable Callable() 🔗

建構空的 Callable，沒有綁定物件和方法。

Callable Callable(from: Callable)

建構給定 Callable 的副本。

Callable Callable(object: Object, method: StringName)

Creates a new Callable for the method named method in the specified object.

Note: For methods of built-in Variant types, use create() instead.

方法說明

Callable bind(...) vararg const 🔗

返回該 Callable 的副本，綁定其中的一個或多個參數。呼叫時，被綁定的參數在提供給 call() 的參數之後傳遞。另見 unbind()。

注意：這個方法與其他類似方法鏈式呼叫時，參數列表的修改順序是從右至左的。

Callable bindv(arguments: Array) 🔗

返回該 Callable 的副本，綁定其中的一個或多個參數，參數從陣列中讀取。呼叫時，被綁定的參數在提供給 call() 的參數之後傳遞。另見 unbind()。

注意：這個方法與其他類似方法鏈式呼叫時，參數列表的修改順序是從右至左的。

Variant call(...) vararg const 🔗

呼叫該 Callable 所代表的方法。可以傳遞參數，必須與該方法的簽章相配對。

void call_deferred(...) vararg const 🔗

Calls the method represented by this Callable in deferred mode, i.e. at the end of the current frame. Arguments can be passed and should match the method's signature.

func _ready():
    grab_focus.call_deferred()

public override void _Ready()
{
    Callable.From(GrabFocus).CallDeferred();
}

Note: Deferred calls are processed at idle time. Idle time happens mainly at the end of process and physics frames. In it, deferred calls will be run until there are none left, which means you can defer calls from other deferred calls and they'll still be run in the current idle time cycle. This means you should not call a method deferred from itself (or from a method called by it), as this causes infinite recursion the same way as if you had called the method directly.

See also Object.call_deferred().

Variant callv(arguments: Array) const 🔗

呼叫該 Callable 所代表的方法。與 call() 不同，這個方法需要所有參數都放在 arguments Array 之中。

Callable create(variant: Variant, method: StringName) static 🔗

Creates a new Callable for the method named method in the specified variant. To represent a method of a built-in Variant type, a custom callable is used (see is_custom()). If variant is Object, then a standard callable will be created instead.

Note: This method is always necessary for the Dictionary type, as property syntax is used to access its entries. You may also use this method when variant's type is not known in advance (for polymorphism).

int get_argument_count() const 🔗

Returns the total number of arguments this Callable should take, including optional arguments. This means that any arguments bound with bind() are subtracted from the result, and any arguments unbound with unbind() are added to the result.

Array get_bound_arguments() const 🔗

Returns the array of arguments bound via successive bind() or unbind() calls. These arguments will be added after the arguments passed to the call, from which get_unbound_arguments_count() arguments on the right have been previously excluded.

func get_effective_arguments(callable, call_args):
    assert(call_args.size() - callable.get_unbound_arguments_count() >= 0)
    var result = call_args.slice(0, call_args.size() - callable.get_unbound_arguments_count())
    result.append_array(callable.get_bound_arguments())
    return result

int get_bound_arguments_count() const 🔗

Returns the total amount of arguments bound via successive bind() or unbind() calls. This is the same as the size of the array returned by get_bound_arguments(). See get_bound_arguments() for details.

Note: The get_bound_arguments_count() and get_unbound_arguments_count() methods can both return positive values.

StringName get_method() const 🔗

返回該 Callable 所代表的方法的名稱。如果該可呼叫體是 lambda 函式，則返回該函式的名稱。

Object get_object() const 🔗

返回該 Callable 所呼叫的物件。

int get_object_id() const 🔗

返回該 Callable 中對象的 ID（見 Object.get_instance_id()）。

int get_unbound_arguments_count() const 🔗

Returns the total amount of arguments unbound via successive bind() or unbind() calls. See get_bound_arguments() for details.

Note: The get_bound_arguments_count() and get_unbound_arguments_count() methods can both return positive values.

int hash() const 🔗

返回該 Callable 對象的 32 位元雜湊值。

注意：內容相同的 Callable 雜湊值始終相同。反之則不然，返回的雜湊值相同並不意味著可呼叫體相等，因為不同的可呼叫體可能由於雜湊衝突而具有相同的雜湊值。引擎在 hash() 中使用 32 位雜湊演算法。

bool is_custom() const 🔗

Returns true if this Callable is a custom callable. Custom callables are used:

for binding/unbinding arguments (see bind() and unbind());
for representing methods of built-in Variant types (see create());
for representing global, lambda, and RPC functions in GDScript;
for other purposes in the core, GDExtension, and C#.

bool is_null() const 🔗

Returns true if this Callable has no target to call the method on. Equivalent to callable == Callable().

Note: This is not the same as not is_valid() and using not is_null() will not guarantee that this callable can be called. Use is_valid() instead.

bool is_standard() const 🔗

如果該 Callable 為標準可呼叫體，則返回 true。這個方法與 is_custom() 相對。如果該可呼叫體為 lambda 函式，則返回 false。

bool is_valid() const 🔗

如果該可呼叫體的物件存在，且分配了有效的方法名，或者為自訂可呼叫體，則返回 true。

void rpc(...) vararg const 🔗

在所有已連接的對等體上執行 RPC（Remote Procedure Call，遠端程式呼叫）。用於多人遊戲，一般不可用，除非所呼叫的函式有 RPC 標記（使用 @GDScript.@rpc 或 Node.rpc_config()）。在不支援的方法上呼叫該方法會導致出錯。見 Node.rpc()。

void rpc_id(peer_id: int, ...) vararg const 🔗

在指定的對等體 ID（請參閱多人遊戲文件）上執行 RPC（Remote Procedure Call，遠程程式呼叫）。用於多人遊戲，一般不可用，除非所呼叫的函式有 RPC 標記（使用 @GDScript.@rpc 或 Node.rpc_config()）。在不支援的方法上呼叫該方法會導致出錯。見 Node.rpc_id()。

Callable unbind(argcount: int) const 🔗

返回這個 Callable 的副本，解綁了一些參數。換句話說，呼叫新的可呼叫體時，用戶提供的最後幾個參數會被忽略，忽略幾個由 argcount 決定。剩餘的參數會被傳遞給該可呼叫體。這樣傳入的參數就能夠比原本可呼叫體所能處理的參數要多，例如帶有固定數量參數的訊號。另見 bind()。

注意：這個方法與其他類似方法鏈式呼叫時，參數列表的修改順序是從右至左的。

func _ready():
    foo.unbind(1).call(1, 2) # 呼叫 foo(1).
    foo.bind(3, 4).unbind(1).call(1, 2) # 呼叫 foo(1, 3, 4)，注意改動的不是 bind 中的參數。

運算子說明

bool operator !=(right: Callable) 🔗

如果兩個 Callable 呼叫的目標不同，則返回 true。

bool operator ==(right: Callable) 🔗

如果兩個 Callable 呼叫的自訂目標相同，則返回 true。