Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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

備註

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

每行字數限制

String as a path to a file. See @export_file.

@export_file var f

String as a path to a directory. See @export_dir.

@export_dir var f

String as a path to a file, custom filter provided as hint. See again @export_file.

@export_file("*.txt") var f

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

String as a path to a PNG file in the global filesystem. See @export_global_file.

@export_global_file("*.png") var tool_image

String as a path to a directory in the global filesystem. See @export_global_dir.

@export_global_dir var tool_dir

The multiline annotation tells the editor to show a large input field for editing over multiple lines. See @export_multiline.

@export_multiline var text

翻譯現有頁面

See @export_range for all of the following.

允許 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

The limits can be made to affect only the slider if you add the hints "or_less" and/or "or_greater". If either these hints are used, it will be possible for the user to enter any value or drag the value with the mouse when not using the slider, even if outside the specified range.

@export_range(0, 100, 1, "or_less", "or_greater") var l: int

The "exp" hint can be used to make a value have an exponential slider instead of a linear slider. This means that when dragging the slider towards the right, changes will become progressively faster when dragging the mouse. This is useful to make editing values that can be either very small or very large easier, at the cost of being less intuitive.

@export_range(0, 100000, 0.01, "exp") var exponential: float

For values that are meant to represent an easing factor, use 帶緩動提示的浮點數 instead.

The "hide_slider" hint can be used to hide the horizontal bar that appears below float properties, or the up/down arrows that appear besides int properties:

@export_range(0, 1000, 0.01, "hide_slider") var no_slider: float

Adding suffixes and handling degrees/radians

A suffix can also be defined to make the value more self-explanatory in the inspector. For example, to define a value that is meant to be configured as "meters" (m) by the user:

@export_range(0, 100, 1, "suffix:m") var m: int

For angles that are stored in radians but displayed as degrees to the user, use the "radians_as_degrees" hint:

@export_range(0, 360, 0.1, "radians_as_degrees") var angle: float

This performs automatic conversion when the value is displayed or modified in the inspector and also displays a degree (°) suffix. This approach is used by Godot's own rotation properties throughout the editor.

If the angle is stored in degrees instead, use the "degrees" hint to display the degree symbol while disabling the automatic degrees-to-radians conversion when the value is modified from the inspector.

帶緩動提示的浮點數

Display a visual representation of the ease() function when editing. See @export_exp_easing.

@export_exp_easing var transition_speed

顏色

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

@export var col: Color

Color given as red-green-blue value (alpha will always be 1). See @export_color_no_alpha.

@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

The drop-down menu will be limited to AnimationNode and all its derived classes.

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

匯出位元旗標

See @export_flags.

作為位元旗標的整數可以在單一屬性內儲存多個 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

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

匯出選單

See @export_enum.

可以使用引用列舉的型別提示匯出屬性，以將其值限制為列舉的值。編輯器將在屬性面板中建立一個小元件，將以下內容列舉為「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()

Other export variants can also be used when exporting arrays:

@export_range(-360, 360, 0.001, "degrees") var laser_angles: Array[float] = []
@export_file("*.json") var skill_trees: Array[String] = []
@export_color_no_alpha var hair_colors = PackedColorArray()
@export_enum("Espresso", "Mocha", "Latte", "Capuccino") var barista_suggestions: Array[String] = []

`@export_storage`

See @export_storage.

By default, exporting a property has two effects:

makes the property stored in the scene/resource file (PROPERTY_USAGE_STORAGE);
adds a field to the Inspector (PROPERTY_USAGE_EDITOR).

However, sometimes you may want to make a property serializable, but not display it in the editor to prevent unintentional changes and cluttering the interface.

To do this you can use @export_storage. This can be useful for @tool scripts. Also the property value is copied when Resource.duplicate() or Node.duplicate() is called, unlike non-exported variables.

var a # Not stored in the file, not displayed in the editor.
@export_storage var b # Stored in the file, not displayed in the editor.
@export var c: int # Stored in the file, displayed in the editor.

`@export_custom`

If you need more control than what's exposed with the built-in @export annotations, you can use @export_custom instead. This allows defining any property hint, hint string and usage flags, with a syntax similar to the one used by the editor for built-in nodes.

For example, this exposes the altitude property with no range limits but a m (meter) suffix defined:

@export_custom(PROPERTY_HINT_NONE, "altitude:m") var altitude: Vector3

The above is normally not feasible with the standard @export_range syntax, since it requires defining a range.

See the class reference for a list of parameters and their allowed values.

警告

When using @export_custom, GDScript does not perform any validation on the syntax. Invalid syntax may have unexpected behavior in the inspector.

`@export_tool_button`

If you need to create a clickable inspector button, you can use @export_tool_button. This exports a Callable property as a clickable button. When the button is pressed, the callable is called.

Export a button with label "Hello" and icon "Callable". When you press it, it will print "Hello world!".

@tool
extends Node

@export_tool_button("Hello", "Callable") var hello_action = hello

func hello():
    print("Hello world!")

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

從工具模式腳本中更改匯出變數值是，顯示在屬性面板上的值不會自動更新。要更新屬性面板上的值，則需要在設定匯出變數值後呼叫 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 來繫結屬性。

警告

The script must operate in the @tool mode so the above methods can work from within the editor.