Godot 4 的碰撞圖層與物理設定

為什麼碰撞圖層很重要

碰撞圖層是 Godot 4 中所有物理互動的基礎 — 移動、命中判定、射線投射、Area 觸發等等。理解 Layer 與 Mask 之間的差異至關重要，而誤解它正是新手與資深開發者都最常遇到的絆腳石之一。

Layer 與 Mask — 思維模型

Godot 中每個物理物件都有兩個位元遮罩屬性：

• Layer = 「我存在於這些圖層上」（我是什麼）
• Mask = 「我掃描這些圖層」（我能看見／命中什麼）

在專案設定中為圖層命名

在撰寫任何程式碼之前，先為你的圖層命名。這會讓檢視器（Inspector）更容易使用，並在專案成長時避免混淆。

專案設定 > 圖層名稱 > 2D 物理（或 3D 物理）：

在程式碼中設定圖層（GDScript）

Godot 4 提供兩種做法 — 以數值為基礎的 API（推薦）以及直接的位元遮罩指派：

# Godot 4 API — value-based (1-indexed, recommended)
set_collision_layer_value(1, true)   # I am on layer 1
set_collision_mask_value(2, true)    # I detect layer 2

# Or use bitmask directly
collision_layer = 1   # Layer 1 only (bit 0)
collision_mask = 6    # Layers 2 and 3 (bits 1 + 2 = 6)

# Read current state
var on_layer_1: bool = get_collision_layer_value(1)
var scans_layer_2: bool = get_collision_mask_value(2)

常見的圖層配置

平台遊戲 / 橫向捲軸

俯視 / Roguelike

Area2D / Area3D 圖層

Area 使用相同的 Layer/Mask 系統。此外，它們還有兩個開關屬性：

• monitoring — 若為 true，此 Area 會主動偵測進入它的其他物件。
• monitorable — 若為 true，其他 Area 便能偵測到此 Area。

訊號：area_entered 與 body_entered

當一個 PhysicsBody（CharacterBody、RigidBody、StaticBody）進入 Area 時，body_entered 會被觸發。當另一個 Area 進入時，area_entered 會被觸發。請務必為你的使用情境連接正確的訊號。

# Pickup Area2D — detect when the Player body enters
func _ready() -> void:
    body_entered.connect(_on_body_entered)

func _on_body_entered(body: Node2D) -> void:
    if body.is_in_group("player"):
        collect()
        queue_free()

RayCast 碰撞遮罩

RayCast 節點只有 Mask（沒有 Layer），因為它們是偵測器，而非物理物體。設定 Mask 以過濾射線可以命中的對象：

# RayCast that only detects enemies (layer 2)
$RayCast2D.collision_mask = 2  # Layer 2 = Enemy
# Or use the value-based API:
$RayCast2D.set_collision_mask_value(1, false)  # Ignore Player
$RayCast2D.set_collision_mask_value(2, true)   # Detect Enemy
$RayCast2D.set_collision_mask_value(3, false)  # Ignore Environment

# Line-of-sight ray that ignores projectiles
$LineOfSight.collision_mask = 0
$LineOfSight.set_collision_mask_value(1, true)  # Player
$LineOfSight.set_collision_mask_value(3, true)  # Environment

實務範例：Player – Enemy – Projectile

以下是典型動作遊戲的完整圖層設定。註解說明了每個決定背後的考量：

# Player (CharacterBody2D)
# Layer: 1 (Player)          — "I am the player"
# Mask: 2 (Enemy), 3 (Environment), 5 (Pickup)
#   — I collide with enemies, walls, and can pick up items

# Enemy (CharacterBody2D)
# Layer: 2 (Enemy)            — "I am an enemy"
# Mask: 1 (Player), 3 (Environment)
#   — I collide with the player and walls

# Player Bullet (Area2D)
# Layer: 4 (Projectile)       — "I am a projectile"
# Mask: 2 (Enemy), 3 (Environment)
#   — I hit enemies and walls, but NOT the player who fired me

# Enemy Bullet (Area2D)
# Layer: 4 (Projectile)       — "I am a projectile"
# Mask: 1 (Player), 3 (Environment)
#   — I hit the player and walls, but NOT the enemy who fired me

除錯技巧

• 可見碰撞形狀：在編輯器中，前往 除錯 > 可見碰撞形狀，即可在執行時繪製所有碰撞形狀。這能立即揭露缺失或錯位的碰撞體。
• 檢視器檢查：選取一個節點，並在檢視器中展開 Collision > Layer 和 Collision > Mask。將滑鼠移到每個位元上即可看到它的名稱（若你已在專案設定中為它們命名）。
• 在執行時輸出：print("Layer: ", collision_layer, " Mask: ", collision_mask)，以在遊玩期間驗證位元遮罩的值。

Godot 3 → 4 遷移變更

常見錯誤

1. 忘記設定 Mask

你的物件有一個 Layer，但 Mask 是空的（全部為零）。該物件存在於物理世界中，卻不偵測任何東西。其他具有相符遮罩的物件仍然能偵測到它，但此物件上的 move_and_slide() 會穿透一切。

2. 混淆 Layer 與 Mask

將玩家的 Layer 設為 2（Enemy），而不是設定它的 Mask。如此一來，就物理引擎而言，玩家就是一個敵人。永遠記住：Layer = 我是什麼，Mask = 我掃描什麼。

3. 使用位元遮罩值而非圖層編號

寫下 set_collision_layer_value(4, true)，以為它會設定位元遮罩值 4（圖層 1+2）。實際上，它啟用的是圖層 4。以數值為基礎的 API 接受的是圖層編號，而非位元值。

4. 期望雙向卻只有單向偵測

物件 A 遮罩了 B 的 Layer，但 B 並未遮罩 A 的 Layer。A 上的 move_and_slide() 會與 B 碰撞，但 B 上的 move_and_slide() 會穿透 A。若要讓兩個 CharacterBody 節點互相阻擋，雙方都必須在自己的 Mask 中包含對方的 Layer。