Godot 4 中的 @export 與註解

簡介：從關鍵字到註解

Godot 4 將多個 GDScript 關鍵字替換為以 @ 為前綴的註解。這是讓 GDScript 語法更簡潔、更一致的一項更大努力的一部分。三個最重要的變更是：

• export → @export
• onready → @onready
• tool → @tool

註解會放在其所修飾宣告的前一行（或同一行）。Godot 4 還引入了許多在 Godot 3 中不存在的新註解變體，例如 @export_range、@export_group 與 @export_category。本指南會全部涵蓋。

基本的 @export

@export 註解會將變數公開至 Godot 檢視器（Inspector），讓你無需編輯程式碼即可設定值。Godot 會根據變數的型別自動選擇合適的編輯器控制項。

@export var speed: float = 300.0
@export var player_name: String = "Player"
@export var health: int = 100
@export var color: Color = Color.WHITE
@export var texture: Texture2D
@export var scene: PackedScene

提示：務必為匯出的變數加上型別註解。這能確保檢視器顯示正確的控制項（例如 Color 顯示調色盤、Texture2D 顯示資源插槽）。

@export_range — 數值滑桿

@export_range 會將數值限制在最小值與最大值之間，並在檢視器中顯示滑桿。你也可以指定步進大小以及像 "or_greater" 或 "or_less" 這樣的提示。

@export_range(0, 100) var health: int = 100
@export_range(0.0, 1.0, 0.01) var volume: float = 0.8
@export_range(0, 1000, 1, "or_greater") var damage: int = 10

"or_greater" 提示允許輸入超過最大值的值，同時保持滑桿範圍聚焦。同樣地，"or_less" 允許低於最小值的值。

@export_enum — 下拉選單

@export_enum 會在檢視器中建立下拉選單。與 String 搭配使用時，會儲存所選選項的名稱。與 int 搭配使用時，你可以指定明確的值。

# Stores the string name: "Warrior", "Mage", or "Rogue"
@export_enum("Warrior", "Mage", "Rogue") var character_class: String

# Stores the integer value: 0, 1, or 2
@export_enum("Easy:0", "Normal:1", "Hard:2") var difficulty: int = 1

@export_file 與 @export_dir — 檔案／目錄路徑

@export_file 會在檢視器中顯示檔案對話框。你可以依副檔名進行篩選。@export_dir 會顯示目錄選擇對話框。

@export_file("*.tscn") var next_level: String
@export_dir var save_directory: String

篩選字串使用 glob 樣式。多個篩選條件可用逗號分隔："*.png,*.jpg"。

@export_multiline 與 @export_placeholder

@export_multiline 為多行字串提供大型文字區域（非常適合對話或說明文字）。@export_placeholder 會在欄位為空時於其中顯示提示文字。

@export_multiline var description: String
@export_placeholder("Enter name...") var player_name: String

@export_group 與 @export_subgroup — 整理檢視器屬性

@export_group 會在檢視器中建立可摺疊的群組標題。其後所有的 @export 變數都會歸屬於該群組，直到下一個群組或類別為止。@export_subgroup 則巢狀於目前群組之內。

@export_group("Movement")
@export var speed: float = 300.0
@export var jump_force: float = 400.0

@export_group("Combat")
@export var attack_damage: int = 10
@export var defense: int = 5

@export_subgroup("Ranged")
@export var projectile_speed: float = 500.0

群組與子群組純粹用於整理 — 它們不會影響程式碼中的變數存取，只會影響屬性在檢視器中的顯示方式。

@export_category — 粗體類別標題

@export_category 會在檢視器中建立粗體的頂層類別標題。與群組不同，類別無法摺疊，並作為不相關屬性集合之間強烈的視覺分隔。

@export_category("Player Stats")
@export var level: int = 1
@export var experience: int = 0

帶節點參照的 @export

你可以匯出 NodePath，讓設計師從場景樹中選取節點。在 Godot 4.2+ 中，你可以直接匯出型別化的節點參照 — 無需 NodePath。

# Classic NodePath export
@export var target_path: NodePath

# Godot 4.2+: typed node export (direct reference, no NodePath needed)
@export var sprite: Sprite2D
@export var collision: CollisionShape2D

型別化的節點匯出是現代 Godot 4 中推薦的做法。檢視器會顯示依指定型別篩選的節點選取器，你也能在腳本編輯器中獲得完整的自動補全。

@export_flags — 位元遮罩核取方塊

@export_flags 會建立一組核取方塊，其中每個選項對應到整數中的一個位元。Godot 也為物理圖層與渲染圖層提供了內建的旗標匯出。

# Custom flags: Fire=1, Water=2, Earth=4, Wind=8
@export_flags("Fire", "Water", "Earth", "Wind") var elements: int

# Built-in physics layer flags
@export_flags_2d_physics var collision_layers: int
@export_flags_2d_render var render_layers: int
@export_flags_3d_physics var collision_layers_3d: int

@onready — 延遲初始化

@onready 會延遲變數的初始化，直到節點進入場景樹為止（等同於在 _ready() 中賦值）。當你使用 $ 參照子節點時這是必需的，因為子節點在剖析時尚不可用。

# Godot 3 (old syntax):
# onready var sprite = $Sprite2D

# Godot 4:
@onready var sprite: Sprite2D = $Sprite2D
@onready var anim: AnimationPlayer = $AnimationPlayer
@onready var label: Label = $UI/ScoreLabel

最佳實踐：務必為 @onready 變數加上型別。這能啟用自動補全，並在剖析時而非執行時捕捉型別錯誤。

@tool — 在編輯器中執行腳本

@tool 會讓腳本在 Godot 編輯器內執行（而非僅在執行時）。這對於建立自訂預覽、Gizmo 以及即時更新的屬性非常強大。請將它放在腳本的最頂端、extends 之前。

@tool
extends Node2D

@export var radius: float = 100.0:
    set(value):
        radius = value
        queue_redraw()  # Redraw in editor when value changes

func _draw() -> void:
    draw_circle(Vector2.ZERO, radius, Color.WHITE)

警告：使用 @tool 腳本時要小心。_process() 與 _physics_process() 中的程式碼會在編輯器內執行。請使用 Engine.is_editor_hint() 來保護僅限遊戲的邏輯。

其他註解

@icon

為腳本的節點型別在場景面板與「建立節點」對話框中設定自訂圖示。

@icon("res://icons/enemy.svg")
extends CharacterBody2D

@warning_ignore

抑制下一條陳述式的特定 GDScript 警告。當你刻意遮蔽某個變數或有未使用的參數時很有用。

@warning_ignore("unused_parameter")
func _on_body_entered(body: Node2D) -> void:
    queue_free()

@warning_ignore("shadowed_variable")
var size: int = 10

@static_unload

標記一個腳本，讓 Godot 在沒有實例存在時可以將其從記憶體中卸載。這能減少僅暫時使用的腳本的記憶體用量。該腳本不得有任何需要保留的靜態變數或資料。

@static_unload
extends RefCounted

# This script can be safely unloaded when not in use

靜態型別最佳實踐

雖然靜態型別提示並非註解，但它們密切相關，且在 Godot 4 中被強烈推薦。它們能改善自動補全、啟用編譯時的錯誤檢查，並可提升效能。

# Variable type annotations
var speed: float = 300.0
var player: CharacterBody2D = null
var items: Array[String] = []
var scores: Dictionary = {}

# Function return types and parameter types
func get_damage() -> int:
    return attack - defense

func apply_force(direction: Vector2, strength: float) -> void:
    velocity += direction * strength

# Type inference with :=
var pos := Vector2(100, 200)  # Inferred as Vector2

注意：在 for 迴圈中對未型別化的陣列進行迭代時，使用 := 要小心。請改用明確的型別註解：for item: String in array。

遷移速查表：Godot 3 到 4

將 Godot 3 匯出語法轉換為 Godot 4 註解的快速參考：