Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

GDScript exported properties

在 Godot 中可以匯出類別成員。也就是說匯出成員的數值可以與附加的資源一起保存 (如 場景) 。匯出成員也能在屬性面板編輯器中編輯。使用 export 關鍵字來匯出:

@export var number: int = 5

在該範例中,值“5”將被儲存並在屬性編輯器中可見。

匯出的變數必須以常數運算式來初始化,或必須以 export 關鍵字的參數來作為匯出提示 (請參考下方**範例** 一節)。

匯出成員變數的其中一個基本的好處就是能在編輯器中瀏覽並編輯。這樣一來,如美術或遊戲設計師之後就能通過修改數值來更改程式的執行方式。為此有一個特殊的匯出語法。

備註

也可以在其他語言如 C# 中匯出屬性。匯出的語法因語言而異。

Basic use

如果為匯出值分配了常數或常數運算式,就可以推斷型別,在編輯器中使用。

@export var number = 5

如果沒有預設值,那麼你可以為變數新增型別。

@export var number: int

可以匯出資源和節點。

@export var resource: Resource
@export var node: Node

建立屬性群組

可以使用 @export_group <class_@GDScript_annotation_@export_group>` 註解將檢視器中匯出的屬性群組。此註釋後的每個匯出屬性都會新增至群組。開始一個新群組或使用``@export_group("")`` 來退出。

@export_group("My Properties")
@export var number = 3

註解的第二個參數可用於僅對具有指定前綴的屬性進行群組。

群組不能巢狀,請使用:ref:@export_subgroup <class_@GDScript_annotation_@export_subgroup> 在群組內建立子群組。

@export_subgroup("Extra Properties")
@export var string = ""
@export var flag = false

您也可以變更主類別的名稱,或使用 @export_category <class_@GDScript_annotation_@export_category>` 註解在屬性列表中建立其他類別。

@export_category("Main Category")
@export var number = 3
@export var string = ""

@export_category("Extra Category")
@export var flag = false

備註

屬性列表是根據類別繼承來組織的,而新類別打破了這種期望。謹慎使用它們,尤其是在建立供公共使用的專案時。

每行字數限制

使用檔案

@export_file var f

字串是目錄的路徑。

@export_dir var f

字串是檔的路徑,在提示中提供自訂篩檢程式。

@export_file("*.txt") var f

也可以使用全域檔案系統中的路徑,但是僅支援工具模式的腳本。

字串是全域檔案系統中某個 PNG 檔的路徑。

@export_global_file("*.png") var tool_image

字串是全域檔案系統中某個目錄的路徑。

@export_global_dir var tool_dir

多行註解告訴編輯器顯示一個大的輸入欄位以進行多行編輯。

@export_multiline var text

翻譯現有頁面

允許 0 到 20 之間的整數。

@export_range(0, 20) var i

允許 -10 到 20 之間的整數。

@export_range(-10, 20) var j

允許 -10 到 20 之間的數,對齊到 0.2 的倍數。

@export_range(-10, 20, 0.2) var k: float

如果新增提示“or_greater”和/或“or_less”,則限制只能適用於滑桿。

@export_range(0, 100, 1, "or_greater", "or_less")

帶緩動提示的浮點數

編輯時顯示“ease()”函式的可視化表示。

@export_exp_easing var transition_speed

顏色

使用紅、綠、藍、Alpha 值指定的普通顏色。

@export var col: Color

使用紅、綠、藍值指定的顏色(Alpha 始終為 1)。

@export_color_no_alpha var col: Color

節點

從 Godot 4.0 開始,腳本中可以直接將節點作為屬性匯出,不必再使用 NodePath:

# Allows any node.
@export var node: Node

# Allows any node that inherits from BaseButton.
# Custom classes declared with `class_name` can also be used.
@export var some_button: BaseButton

如果需要,仍然可以和 Godot 3.x 中一樣匯出 NodePath:

@export var node_path: NodePath
var node = get_node(node_path)

如果你想要限制 NodePath 的型別,可以使用 @export_node_path 注解:

@export_node_path("Button", "TouchScreenButton") var some_button

資源

@export var resource: Resource

在屬性面板中,您可以將資源檔案從檔案系統停靠欄拖曳到變數槽中。

然而,開啟屬性面板下拉列表可能會導致要建立的可能類別的列表非常長。因此,如果您指定 Resource 的擴充,例如:

@export var resource: AnimationNode

下拉式選單將僅限於 AnimationNode 及其所有繼承類別。

請特別注意,即使腳本不是在編輯器中執行,匯出屬性依然可以被編輯。這個功能可以與 「工具」模式的腳本 一起使用。

匯出位元旗標

作為位元旗標的整數可以在單一屬性內儲存多個 true/false (布林) 值。只需要使用匯出提示 int, FLAGS, 就可以在編輯器中設定:

# Set any of the given flags from the editor.
@export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0

必須為每個旗標提供說明字串。在這個例子中, Fire 的值為 1, Water 為 2, Earth 為 4 而 Wind 則為 8。通常必須定義對應的常數 (如: const ELEMENT_WIND = 8 等)。

您可以使用冒號新增明確的值:

@export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0

只有 2 的冪值作為位元旗標選項才有效。允許的最低值為 1,因為 0 表示未選擇任何內容。您也可以新增其他旗標組合的選項:

@export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")
var spell_targets = 0

匯出提示在專案設定中也定義了物理與渲染層:

@export_flags_2d_physics var layers_2d_physics
@export_flags_2d_render var layers_2d_render
@export_flags_2d_navigation var layers_2d_navigation
@export_flags_3d_physics var layers_3d_physics
@export_flags_3d_render var layers_3d_render
@export_flags_3d_navigation var layers_3d_navigation

使用位元旗標會需要理解位元運算子。若不確定的話,則應該使用布林變數。

匯出選單

可以使用引用列舉的型別提示匯出屬性,以將其值限制為列舉的值。編輯器將在屬性面板中建立一個小元件,將以下內容列舉為「Thing 1」、「Thing 2」、「Another Thing」。該值將儲存為整數。

enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
@export var x: NamedEnum

也可以使用 @export_enum <class_@GDScript_annotation_@export_enum>` 註解將整數和字串屬性限制為特定的值列表。編輯器將在 Inspector 中建立一個小元件,列舉以下角色:戰士、魔術師、小偷。該值將儲存為整數,對應於所選選項的索引(即“0”、“1”或“2”)。

@export_enum("Warrior", "Magician", "Thief") var character_class: int

您可以使用冒號新增明確的值:

@export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int

如果是 string , 檔將從該路徑載入.

@export_enum("Rebecca", "Mary", "Leah") var character_name: String

如果你想設定一個初始值,你必須明確指定它:

@export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca"

匯出陣列

可以在匯出的陣列中使用初始設定式,但只能使用常數運算式。

若匯出的陣列指定了從 Resource 繼承來的型別,則陣列值在屬性面板中就可以從檔案系統中一次拖放多個檔案過來。

此預設的選項的預設值.

@export var a = [1, 2, 3]

匯出的陣列可以指定型別(使用與之前相同的提示)。

@export var ints: Array[int] = [1, 2, 3]

# Nested typed arrays such as `Array[Array[float]]` are not supported yet.
@export var two_dimensional: Array[Array] = [[1.0, 2.0], [3.0, 4.0]]

您可以省略預設值,但如果未分配,它將是“null”。

@export var b: Array
@export var scenes: Array[PackedScene]

若匯出的陣列指定了從 Resource 繼承來的型別,則陣列值在屬性面板中就可以從檔案系統中一次拖放多個檔案過來。

@export var textures: Array[Texture] = []
@export var scenes: Array[PackedScene] = []

打包型別陣列也可以工作,但只能初始化為空:

@export var vector3s = PackedVector3Array()
@export var strings = PackedStringArray()

從工具腳本中設定匯出變數

工具模式 腳本中更改匯出變數值是,顯示在屬性面板上的值不會自動更新。要更新屬性面板上的值,則需要在設定匯出變數值後呼叫 property_list_changed_notify()

進階匯出

為了避免不必要的複雜設計,並非所有匯出型別都有在語言層面上提供。下面說明了一些能使用低階 API 實作的常見匯出功能。

Before reading further, you should get familiar with the way properties are handled and how they can be customized with _set(), _get(), and _get_property_list() methods as described in 從物件中存取資料或邏輯.

也參考

若要在 C++ 中以上述方法繫結屬性,請參考 使用 _set/_get/_get_property_list 來繫結屬性

警告

腳本必須為 tool 模式,才可在編輯器中使用上述方法。