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
模式,才可在編輯器中使用上述方法。