GDScript 匯出

匯出簡介

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

extends Button

export var number = 5 # Value will be saved and visible in the property editor.

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

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

備註

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

範例

# If the exported value assigns a constant or constant expression,
# the type will be inferred and used in the editor.

export var number = 5

# Export can take a basic data type as an argument, which will be
# used in the editor.

export(int) var number

# Export can also take a resource type to use as a hint.

export(Texture) var character_face
export(PackedScene) var scene_file
# There are many resource types that can be used this way, try e.g.
# the following to list them:
export(Resource) var resource

# Integers and strings hint enumerated values.

# Editor will enumerate as 0, 1 and 2.
export(int, "Warrior", "Magician", "Thief") var character_class
# Editor will enumerate with string names.
export(String, "Rebecca", "Mary", "Leah") var character_name

# Named enum values

# Editor will enumerate as THING_1, THING_2, ANOTHER_THING.
enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
export(NamedEnum) var x

# Strings as paths

# String is a path to a file.
export(String, FILE) var f
# String is a path to a directory.
export(String, DIR) var f
# String is a path to a file, custom filter provided as hint.
export(String, FILE, "*.txt") var f

# Using paths in the global filesystem is also possible,
# but only in scripts in "tool" mode.

# String is a path to a PNG file in the global filesystem.
export(String, FILE, GLOBAL, "*.png") var tool_image
# String is a path to a directory in the global filesystem.
export(String, DIR, GLOBAL) var tool_dir

# The MULTILINE setting tells the editor to show a large input
# field for editing over multiple lines.
export(String, MULTILINE) var text

# Limiting editor input ranges

# Allow integer values from 0 to 20.
export(int, 20) var i
# Allow integer values from -10 to 20.
export(int, -10, 20) var j
# Allow floats from -10 to 20 and snap the value to multiples of 0.2.
export(float, -10, 20, 0.2) var k
# Allow values 'y = exp(x)' where 'y' varies between 100 and 1000
# while snapping to steps of 20. The editor will present a
# slider for easily editing the value.
export(float, EXP, 100, 1000, 20) var l

# Floats with easing hint

# Display a visual representation of the 'ease()' function
# when editing.
export(float, EASE) var transition_speed

# Colors

# Color given as red-green-blue value (alpha will always be 1).
export(Color, RGB) var col
# Color given as red-green-blue-alpha value.
export(Color, RGBA) var col

# Nodes

# Another node in the scene can be exported as a NodePath.
export(NodePath) var node_path
# Do take note that the node itself isn't being exported -
# there is one more step to call the true node:
var node = get_node(node_path)

# Resources

export(Resource) var resource
# In the Inspector, you can then drag and drop a resource file
# from the FileSystem dock into the variable slot.

# Opening the inspector dropdown may result in an
# extremely long list of possible classes to create, however.
# Therefore, if you specify an extension of Resource such as:
export(AnimationNode) var resource
# The drop-down menu will be limited to AnimationNode and all
# its inherited classes.

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

匯出位元旗標

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

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

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

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

export(int, LAYERS_2D_PHYSICS) var layers_2d_physics
export(int, LAYERS_2D_RENDER) var layers_2d_render
export(int, LAYERS_3D_PHYSICS) var layers_3d_physics
export(int, LAYERS_3D_RENDER) var layers_3d_render

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

匯出陣列

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

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

# Default value must be a constant expression.

export var a = [1, 2, 3]

# Exported arrays can specify type (using the same hints as before).

export(Array, int) var ints = [1, 2, 3]
export(Array, int, "Red", "Green", "Blue") var enums = [2, 1, 0]
export(Array, Array, float) var two_dimensional = [[1.0, 2.0], [3.0, 4.0]]

# You can omit the default value, but then it would be null if not assigned.

export(Array) var b
export(Array, PackedScene) var scenes

# Arrays with specified types which inherit from resource can be set by
# drag-and-dropping multiple files from the FileSystem dock.

export(Array, Texture) var textures
export(Array, PackedScene) var scenes

# Typed arrays also work, only initialized empty:

export var vector3s = PoolVector3Array()
export var strings = PoolStringArray()

# Default value can include run-time values, but can't
# be exported.

var c = [a, 2, 3]

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

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

進階匯出

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

在進一步閱讀之前,建議您先熟悉屬性的處理方法以及如何使用 _set(), _get()_get_property_list() 方法來自定屬性處理,詳細說明可參考 從物件中存取資料或邏輯

也參考

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

警告

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

新增腳本分類

為了在視覺上更好區分各個屬性,可以將一種特殊的腳本分類嵌入至屬性面板中,作為分割線使用。 Script Variables 就是一個內建分類的範例。

func _get_property_list():
    var properties = []
    properties.append(
        {
            name = "Debug",
            type = TYPE_NIL,
            usage = PROPERTY_USAGE_CATEGORY | PROPERTY_USAGE_SCRIPT_VARIABLE
        }
    )
    return properties
  • name 是要加入屬性面板中的分類名稱;

  • PROPERTY_USAGE_CATEGORY 代表這個屬性要作為腳本分類來使用,所以可以忽略型別 TYPE_NIL ,因為實際上這個型別不會在腳本邏輯內使用,但還是必須要在這裡定義。

建立屬性群組

可將名稱類似的屬性放在群組內。

func _get_property_list():
    var properties = []
    properties.append({
            name = "Rotate",
            type = TYPE_NIL,
            hint_string = "rotate_",
            usage = PROPERTY_USAGE_GROUP | PROPERTY_USAGE_SCRIPT_VARIABLE
    })
    return properties
  • name 是群組名稱,在屬性面板中可以展開摺疊,內包含了一組屬性列表;

  • 接下來所有新增的屬性都會被摺疊放在群組中,且會以 hint_string 索引鍵定義的前置字串來縮短名稱。例如, 在本例中 rotate_speed 會被縮短為 speed

  • PROPERTY_USAGE_GROUP 代表這個屬性要被作為腳本群組來使用,所以可以忽略型別 TYPE_NIL ,因為實際上這個型別不會在腳本邏輯內使用,但還是必須要在這裡定義。