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.

Signal

代表 Object 中某個訊號的內建型別。

說明

Signal 是一種內建的 Variant 型別,它代表了一個 Object 實例的訊號。和所有的 Variant 型別一樣,它可以被儲存在變數中,也可以被傳遞給函式。訊號允許所有已連接的 Callable(以及它們各自所屬的物件)去監聽並響應事件,而無需彼此之間直接參照。這種設計讓程式碼保持了極高的靈活性,也更易於管理。你可以使用 Object.has_signal() 方法來檢查一個 Object 是否擁有指定名稱的訊號。

在 GDScript 中,可以使用 signal 關鍵字來聲明訊號;而在 C# 中,則可以在委託(delegate)上使用 [Signal] 特性(Attribute)來定義。

signal attacked

# 也可以聲明額外的參數。
# 這些參數在發射訊號時必須被傳入。
signal item_dropped(item_name, amount)

在 Godot 中,連接訊號是最常見的操作之一,API 提供了多種實現方式,下面會做詳細介紹。下面的程式碼塊展示了推薦的連接方法。

func _ready():
    var button = Button.new()
    # 這裡的 button_down 是一個 Signal(訊號)Variant 型別。因此,我們呼叫的是 Signal.connect() 方法,而不是 Object.connect()。
    # 關於該 API 更深入的介紹,請參見下方的討論。
    button.button_down.connect(_on_button_down)

    # 這裡假設存在一個定義了 `hit` 訊號的 `Player` 類。
    var player = Player.new()
    # 我們再次使用了 Signal.connect(),同時還使用了 Callable.bind() 方法。
    # 它會回傳一個新的 Callable,並且這個 Callable 已經綁定了相應的參數。
    player.hit.connect(_on_player_hit.bind("sword", 100))

func _on_button_down():
    print("Button down!")

func _on_player_hit(weapon_type, damage):
    print("Hit with weapon %s for %d damage." % [weapon_type, damage])

Object.connect() 還是 Signal.connect()?

如上文所示,連接訊號的推薦方法並不是 Object.connect()。下面的程式碼塊展示了連接訊號的四種選項,分別是使用這種舊版方法或推薦的 connect(),以及使用隱式的 Callable 或手動定義的 Callable。

func _ready():
    var button = Button.new()
    # 方法一:使用 Object.connect(),並為定義好的函式隱式建立一個 Callable。
    button.connect("button_down", _on_button_down)
    # 方法二:使用 Object.connect(),並通過指定目標物件和方法名來手動建置一個 Callable。
    button.connect("button_down", Callable(self, "_on_button_down"))
    # 方法三:使用 Signal.connect(),並為定義好的函式隱式建立一個 Callable。
    button.button_down.connect(_on_button_down)
    # 方法四:使用 Signal.connect(),並通過指定目標物件和方法名來手動建置一個 Callable。
    button.button_down.connect(Callable(self, "_on_button_down"))

func _on_button_down():
    print("Button down!")

雖然所有選項的最終結果都一樣(button 的 BaseButton.button_down 訊號都會被連接到 _on_button_down 上),但 選項 3 提供了最好的驗證機制:如果 button_down Signal 或者 _on_button_down Callable 沒有被定義,它會在編譯階段直接輸出出錯誤。另一方面,選項 2 僅僅取決於字串名稱,只能在程式執行時進行驗證:如果 "button_down" 不是一個訊號,或者 "_on_button_down" 不是 self 物件中的一個方法,它會在執行時產生一個錯誤。使用選項 1、2 或 4 的主要原因,是你確實需要使用字串(例如,根據從設定檔案中讀取的字串來以編程方式連接訊號)。除此之外,選項 3 是最推薦(也是最快)的方法。

綁定和傳遞參數:綁定參數的語法是通過 Callable.bind(),它會回傳一個綁定了參數的 Callable 副本。

當呼叫 emit() 或 Object.emit_signal() 時,也可以傳遞訊號參數。

下面的範例展示了這些訊號參數與綁定參數之間的關係。

func _ready():
    # 這裡假設存在一個定義了 `hit` 訊號的 `Player` 類。
    var player = Player.new()
    # 使用 Callable.bind()。
    player.hit.connect(_on_player_hit.bind("sword", 100))

    # 發射訊號時新增的參數會最先傳遞。
    player.hit.emit("Dark lord", 5)

# 我們在發射訊號時傳遞了兩個參數 (`hit_by`, `level`),
# 並在連接訊號時綁定了另外兩個參數 (`weapon_type`, `damage`)。
func _on_player_hit(hit_by, level, weapon_type, damage):
    print("Hit by %s (level %d) with weapon %s for %d damage." % [hit_by, level, weapon_type, damage])

注意: 在布林環境下,如果訊號為 null(空),它的求值結果將為 false(假)(詳見 is_null())。除此之外,訊號的求值結果始終為 true(真)。

備註

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

教學

建構子

Signal

Signal()

Signal

Signal(from: Signal)

Signal

Signal(object: Object, signal: StringName)

方法

int

connect(callable: Callable, flags: int = 0)

void

disconnect(callable: Callable)

void

emit(...) vararg const

Array

get_connections() const

StringName

get_name() const

Object

get_object() const

int

get_object_id() const

bool

has_connections() const

bool

is_connected(callable: Callable) const

bool

is_null() const

運算子

bool

operator !=(right: Signal)

bool

operator ==(right: Signal)


建構子說明

Signal Signal() 🔗

建構空的 Signal,沒有綁定物件和訊號名稱。


Signal Signal(from: Signal)

建構給定 Signal 的副本。


Signal Signal(object: Object, signal: StringName)

新建 Signal 物件,參照 object 物件中名為 signal 的訊號。


方法說明

int connect(callable: Callable, flags: int = 0) 🔗

Connects this signal to the specified callable. Optional flags can be also added to configure the connection's behavior (see ConnectFlags constants). You can provide additional arguments to the connected callable by using Callable.bind(). Returns @GlobalScope.OK if the signal was successfully connected, or @GlobalScope.ERR_INVALID_PARAMETER if the Callable is null or invalid.

A signal can only be connected once to the same Callable. If the signal is already connected, this method returns @GlobalScope.ERR_INVALID_PARAMETER and prints an error, unless the signal is connected with Object.CONNECT_REFERENCE_COUNTED. To prevent this, use is_connected() first to check for existing connections.

for button in $Buttons.get_children():
    button.pressed.connect(_on_pressed.bind(button))

func _on_pressed(button):
    print(button.name, " was pressed")

Note: If the callable's object is freed, the connection will be lost.


void disconnect(callable: Callable) 🔗

Disconnects this signal from the specified Callable. If the connection does not exist, prints an error. Use is_connected() to make sure that the connection exists.


void emit(...) vararg const 🔗

發出該訊號。與該訊號相連的所有 Callable 都將被觸發。此方法支援可變數量的參數,所以參數可以用逗號分隔列表的形式傳遞。


Array get_connections() const 🔗

返回該訊號的連接 Array。連接用 Dictionary 表示,包含三個條目:

  • signal 是對此訊號的引用。

  • callable 是對連接的 Callable 的引用。

  • flags 是 ConnectFlags 的組合。


StringName get_name() const 🔗

返回該訊號的名稱。


Object get_object() const 🔗

返回發出該訊號的物件。


int get_object_id() const 🔗

返回發出該訊號的物件的 ID(見 Object.get_instance_id())。


bool has_connections() const 🔗

如果存在連接到該訊號的 Callable,則回傳 true。


bool is_connected(callable: Callable) const 🔗

如果指定的 Callable 已連接到此訊號,則返回 true。


bool is_null() const 🔗

如果該 Signal 不存在物件且訊號名為空,則回傳 true。等價於 signal == Signal()。


運算子說明

bool operator !=(right: Signal) 🔗

如果訊號的物件或名稱不同,則返回 true。


bool operator ==(right: Signal) 🔗

如果訊號的物件和名稱相同,則返回 true。