Godot 信號是什麼：signal、connect 和 emit 用法詳解

Fri, 19 Jun 2026 23:12:13 +0800

Godot 中的「信號」可以理解成節點發出的通知：

某件事情發生了，誰關心這件事，誰就來處理。

例如：

按鈕：我被點擊了。
金幣：我被玩家收集了。
玩家：我的生命值改變了。
敵人：我死亡了。
計時器：時間到了。

其他節點可以連接這些信號，並在信號發出時執行一個函式。發送者不需要直接找到接收者，這能減少節點之間的相互依賴。

信號的三個核心步驟

一個完整的信號流程通常有三步：

宣告信號。
連接信號。
發出信號。

可以把它想像成門鈴：

概念	類比
`signal`	安裝門鈴
`connect`	把門鈴接到屋內響鈴器
`emit`	按下門鈴
接收函式	屋裡的人聽到後開門

所以最重要的記憶方式是：

1
2
3

signal  = 定義通知
connect = 安排接收者
emit    = 發出通知

Godot 有兩類信號

Godot 中常見的信號可以分為兩類：內建信號和自訂信號。

內建信號

內建信號是 Godot 節點本身已經提供的信號。

常見例子：

Button.pressed
Timer.timeout
Area2D.body_entered
Area2D.body_exited

如果金幣節點繼承自 Area2D，那麼它天然就有 body_entered 信號。當 CharacterBody2D 進入金幣的碰撞區域時，Godot 會自動發出這個信號。

自訂信號

自訂信號由我們自己宣告。

例如金幣被收集：

`1`	`signal collected`

這個 collected 不是 Godot 內建的，而是我們自己定義的通知類型。

金幣範例中的兩層信號

一個簡單的金幣腳本可以這樣寫：

extends Area2D

signal collected


func _ready() -> void:
    body_entered.connect(_on_body_entered)


func _on_body_entered(body: Node2D) -> void:
    if body.name != "Player":
        return

    collected.emit()
    queue_free()

這裡實際使用了兩層信號。

第一層：body_entered

這句程式碼：

`1`	`body_entered.connect(_on_body_entered)`

意思是：

當有物理物件進入 Coin 的 Area2D 時，呼叫 _on_body_entered()。

流程如下：

Player 進入金幣碰撞區域
        ↓
Area2D 發出 body_entered
        ↓
執行 _on_body_entered(body)

傳入的 body 就是進入金幣區域的節點。如果 Player 進入金幣區域，那麼：

`1`	`body == Player`

第二層：collected

這句程式碼：

`1`	`signal collected`

是在宣告信號，表示 Coin 可以發出一個名叫 collected 的通知。

接著：

`1`	`collected.emit()`

表示正式發出通知：

這個金幣已經被收集了。

但要注意：發出信號，不代表一定有人接收。

如果沒有節點連接 collected，它仍然會發出，但不會產生額外效果。金幣之所以消失，是因為後面還有：

`1`	`queue_free()`

並不是因為 collected.emit() 會自動讓金幣消失。

完整通信流程

金幣被玩家碰到以後，完整流程是：

Player 進入 Coin
        ↓
Coin 的 Area2D 發出 body_entered
        ↓
Coin 執行 _on_body_entered()
        ↓
確認進入者是 Player
        ↓
Coin 發出 collected
        ↓
Main 接收 collected
        ↓
Main 增加分數
        ↓
Coin 執行 queue_free()
        ↓
金幣消失

這裡有兩個發送者：

1
2

Area2D → 發出 body_entered
Coin   → 發出 collected

body_entered 負責告訴 Coin：「有東西進入了你的區域。」

collected 負責告訴 Main：「這個金幣被收集了。」

怎樣讓 Main 接收金幣信號

假設場景結構如下：

Main  Node2D
├─ Player
├─ Coin
└─ CanvasLayer
   └─ ScoreLabel

可以用編輯器連接，也可以用程式碼連接。

方法一：在 Godot 編輯器裡連接

打開 main.tscn。

第一步，選中場景樹裡的：

Coin

第二步，在右側面板從「檢查器」切換到：

節點

英文介面是：

Node

第三步，找到自訂信號：

`1`	`collected()`

雙擊它。

第四步，選擇接收節點：

Main

點擊「連接」。Godot 會在 Main 的腳本中生成類似函式：

1
2

func _on_coin_collected() -> void:
    pass

把它改成：

var score: int = 0


func _on_coin_collected() -> void:
    score += 1
    print("目前分數：", score)

執行後，收集金幣時會輸出：

目前分數：1

方法二：用程式碼連接信號

也可以不透過編輯器，直接在 main.gd 中連接：

extends Node2D

var score: int = 0

@onready var coin: Area2D = $Coin


func _ready() -> void:
    coin.collected.connect(_on_coin_collected)


func _on_coin_collected() -> void:
    score += 1
    print("目前分數：", score)

核心程式碼是：

`1`	`coin.collected.connect(_on_coin_collected)`

它表示：

1
2
3

發送者：coin
信號：collected
接收函式：_on_coin_collected

Godot 4 推薦直接透過 Signal 物件呼叫 connect()，例如：

`1`	`coin.collected.connect(_on_coin_collected)`

不要照搬一些 Godot 3 舊教學裡的舊寫法。

讓信號攜帶資料

信號不只能通知「事情發生了」，還可以攜帶資料。

例如不同金幣分值不同：

extends Area2D

signal collected(value: int)

@export var value: int = 1


func _ready() -> void:
    body_entered.connect(_on_body_entered)


func _on_body_entered(body: Node2D) -> void:
    if body.name != "Player":
        return

    collected.emit(value)
    queue_free()

普通金幣可以設定：

`1`	`value = 1`

大金幣可以設定：

`1`	`value = 5`

Main 接收時也要增加參數：

var score: int = 0


func _on_coin_collected(value: int) -> void:
    score += value
    print("獲得：", value)
    print("總分：", score)

通信過程：

Coin：我被收集了，價值是 5
              ↓
Main：收到 value = 5
              ↓
score += 5

為什麼不讓 Coin 直接修改 UI

不推薦這樣寫：

1
2
3

func _on_body_entered(body: Node2D) -> void:
    get_node("../CanvasLayer/ScoreLabel").text = "1"
    queue_free()

因為這樣會讓 Coin 依賴 Main 的具體節點結構：

Coin 必須知道 ScoreLabel 在哪裡。
Coin 必須知道分數如何保存。
Coin 必須知道 UI 怎樣更新。

只要你移動 UI 節點，Coin 的路徑就可能失效。

更好的結構是：

Coin 只負責：
「我被收集了。」

Main 負責：
「增加分數。」

UI 負責：
「顯示分數。」

也就是：

Coin
  │ collected(value)
  ▼
Main
  │ 更新 score
  ▼
ScoreLabel

這正是信號降低節點耦合的作用。

最容易混淆的三個概念

signal

宣告一個信號：

`1`	`signal collected`

相當於建立一種通知類型。

connect()

指定信號發出後呼叫哪個函式：

`1`	`collected.connect(_on_collected)`

emit()

正式發出信號：

`1`	`collected.emit()`

記憶方式：

1
2
3

signal  = 定義通知
connect = 安排接收者
emit    = 發出通知

信號 on KnightLi的博客