Up to date

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

C# exported properties

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

using Godot;

public partial class ExportExample : Node3D
{
    [Export]
    public int Number { get; set; } = 5;
}

在該範例中，值「5」將被儲存，建置目前專案後，它將在屬性編輯器中可見。

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

Exporting can only be done with 自定變數型別.

備註

GDScript 中也能夠匯出屬性，相關資訊見 GDScript exported properties。

Basic use

Exporting works with fields and properties. They can have any access modifier.

[Export]
private int _number;

[Export]
public int Number { get; set; }

匯出的成員可以指定預設值；否則，將使用「型別的預設值 <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/default-values>」。

An int like Number defaults to 0. Text defaults to null because string is a reference type.

[Export]
public int Number { get; set; }

[Export]
public string Text { get; set; }

Default values can be specified for fields and properties.

[Export]
private string _greeting = "Hello World";

[Export]
public string Greeting { get; set; } = "Hello World";

Properties with a backing field use the default value of the backing field.

private int _number = 2;

[Export]
public int NumberWithBackingField
{
    get => _number;
    set => _number = value;
}

備註

A property's get is not actually executed to determine the default value. Instead, Godot analyzes the C# source code. This works fine for most cases, such as the examples on this page. However, some properties are too complex for the analyzer to understand.

For example, the following property attempts to use math to display the default value as 5 in the property editor, but it doesn't work:

[Export]
public int NumberWithBackingField
{
    get => _number + 3;
    set => _number = value - 3;
}

private int _number = 2;

The analyzer doesn't understand this code and falls back to the default value for int, 0. However, when running the scene or inspecting a node with an attached tool script, _number will be 2, and NumberWithBackingField will return 5. This difference may cause confusing behavior. To avoid this, don't use complex properties. Alternatively, if the default value can be explicitly specified, it can be overridden with the _PropertyCanRevert() and _PropertyGetRevert() methods.

Any type of Resource or Node can be exported. The property editor shows a user-friendly assignment dialog for these types. This can be used instead of GD.Load and GetNode. See Nodes and Resources.

[Export]
public PackedScene PackedScene { get; set; }

[Export]
public RigidBody2D RigidBody2D { get; set; }

建立屬性群組

可以使用“[ExportGroup]”屬性在屬性面板中對匯出的屬性進行群組。此屬性之後的每個匯出屬性都會新增到群組中。開始一個新群組或使用``[ExportGroup("")]`` 進行群組。

[ExportGroup("My Properties")]
[Export]
public int Number { get; set; } = 3;

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

群組可以巢狀，請使用 [ExportSubgroup] 在群組中建立子群組。

[ExportSubgroup("Extra Properties")]
[Export]
public string Text { get; set; } = "";
[Export]
public bool Flag { get; set; } = false;

您也可以變更主類別的名稱，或使用「[ExportCategory]」屬性在屬性列表中建立其他類別。

[ExportCategory("Main Category")]
[Export]
public int Number { get; set; } = 3;
[Export]
public string Text { get; set; } = "";

[ExportCategory("Extra Category")]
[Export]
public bool Flag { get; set; } = false;

備註

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

每行字數限制

屬性提示可用於將字串匯出為路徑

使用檔案

[Export(PropertyHint.File)]
public string GameFile { get; set; }

字串是目錄的路徑。

[Export(PropertyHint.Dir)]
public string GameDirectory { get; set; }

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

[Export(PropertyHint.File, "*.txt,")]
public string GameFile { get; set; }

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

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

[Export(PropertyHint.GlobalFile, "*.png")]
public string ToolImage { get; set; }

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

[Export(PropertyHint.GlobalDir)]
public string ToolDir { get; set; }

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

[Export(PropertyHint.MultilineText)]
public string Text { get; set; }

翻譯現有頁面

使用 range 屬性提示可以限制使用編輯器輸入的值。

允許 0 到 20 之間的整數。

[Export(PropertyHint.Range, "0,20,")]
public int Number { get; set; }

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

[Export(PropertyHint.Range, "-10,20,")]
public int Number { get; set; }

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

[Export(PropertyHint.Range, "-10,20,0.2")]
public float Number { get; set; }

如果新增提示“or_greater”和/或“or_less”，則在調整值時可以透過鍵入而不是使用滑桿來高於或低於限制。

[Export(PropertyHint.Range, "0,100,1,or_greater,or_less")]
public int Number { get; set; }

帶緩動提示的浮點數

Display a visual representation of the ease function when editing.

[Export(PropertyHint.ExpEasing)]
public float TransitionSpeed { get; set; }

Export with suffix hint

Display a unit hint suffix for exported variables. Works with numeric types, such as floats or vectors:

[Export(PropertyHint.None, "suffix:m/s\u00b2")]
public float Gravity { get; set; } = 9.8f;
[Export(PropertyHint.None, "suffix:m/s")]
public Vector3 Velocity { get; set; }

In the above example, \u00b2 is used to write the "squared" character (²).

顏色

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

[Export]
public Color Color { get; set; }

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

[Export(PropertyHint.ColorNoAlpha)]
public Color Color { get; set; }

節點

從Godot 4.0開始，可以直接匯出節點，而無需使用NodePaths。

[Export]
public Node Node { get; set; }

A specific type of node can also be directly exported. The list of nodes shown after pressing "Assign" in the inspector is filtered to the specified type, and only a correct node can be assigned.

[Export]
public Sprite2D Sprite2D { get; set; }

Custom node classes can also be exported directly. The filtering behavior depends on whether the custom class is a global class.

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

[Export]
public NodePath NodePath { get; set; }

public override void _Ready()
{
    var node = GetNode(NodePath);
}

資源

[Export]
public Resource Resource { get; set; }

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

然而，開啟屬性面板下拉列表可能會導致要建立的可能類別的列表非常長。因此，如果您指定從 Resource 衍生的型別，例如：

[Export]
public AnimationNode AnimationNode { get; set; }

下拉式選單將僅限於 AnimationNode 及其所有繼承類別。也可以使用自訂資源類，請參閱 doc_c_sharp_global_classes。

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

匯出位元旗標

可以匯出型別為具有「[Flags]」屬性的列舉的成員，並且它們的值僅限於列舉型別的成員。編輯器將在屬性面板中建立一個小元件，允許選擇不選擇、選擇一個或多個列舉成員。該值將儲存為整數。

A flags enum uses powers of 2 for the values of the enum members. Members that combine multiple flags using logical OR (|) are also possible.

[Flags]
public enum SpellElements
{
    Fire = 1 << 1,
    Water = 1 << 2,
    Earth = 1 << 3,
    Wind = 1 << 4,

    FireAndWater = Fire | Water,
}

[Export]
public SpellElements MySpellElements { get; set; }

Integers used as bit flags can store multiple true/false (boolean) values in one property. By using the Flags property hint, any of the given flags can be set from the editor.

[Export(PropertyHint.Flags, "Fire,Water,Earth,Wind")]
public int SpellElements { get; set; } = 0;

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

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

[Export(PropertyHint.Flags, "Self:4,Allies:8,Foes:16")]
public int SpellTargets { get; set; } = 0;

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

[Export(PropertyHint.Flags, "Self:4,Allies:8,Self and Allies:12,Foes:16")]
public int SpellTargets { get; set; } = 0;

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

[Export(PropertyHint.Layers2DPhysics)]
public uint Layers2DPhysics { get; set; }
[Export(PropertyHint.Layers2DRender)]
public uint Layers2DRender { get; set; }
[Export(PropertyHint.Layers3DPhysics)]
public uint Layers3DPhysics { get; set; }
[Export(PropertyHint.Layers3DRender)]
public uint Layers3DRender { get; set; }

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

匯出選單

可以匯出列舉型別的成員，且其值僅限於列舉型別的成員。編輯器將在屬性面板中建立一個小元件，將以下內容列舉為「Thing 1」、「Thing 2」、「Another Thing」。該值將儲存為整數。

public enum MyEnum
{
    Thing1,
    Thing2,
    AnotherThing = -1,
}

[Export]
public MyEnum MyEnum { get; set; }

也可以使用帶有“PropertyHint.Enum”提示的“[Export]”註釋將整數和字串成員限制為特定的值列表。編輯器將在 Inspector 中建立一個小元件，列舉以下角色：戰士、魔術師、小偷。該值將儲存為整數，對應於所選選項的索引（即“0”、“1”或“2”）。

[Export(PropertyHint.Enum, "Warrior,Magician,Thief")]
public int CharacterClass { get; set; }

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

[Export(PropertyHint.Enum, "Slow:30,Average:60,Very Fast:200")]
public int CharacterSpeed { get; set; }

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

[Export(PropertyHint.Enum, "Rebecca,Mary,Leah")]
public string CharacterName { get; set; }

如果要設定初始值，則必須明確指定：

[Export(PropertyHint.Enum, "Rebecca,Mary,Leah")]
public string CharacterName { get; set; } = "Rebecca";

其他建議

如 C# Variant <doc_c_sharp_variant> 檔案中所述，只有某些 C# 陣列和「Godot.Collections」命名空間中定義的集合型別是 Variant 相容的，因此，只能匯出這些型別。

匯出陣列

[Export]
public Godot.Collections.Array Array { get; set; }

Using the generic Godot.Collections.Array<T> allows specifying the type of the array elements, which will be used as a hint for the editor. The Inspector will restrict the elements to the specified type.

[Export]
public Godot.Collections.Array<string> Array { get; set; }

The default value of Godot arrays is null. A different default can be specified:

[Export]
public Godot.Collections.Array<string> CharacterNames { get; set; } = new Godot.Collections.Array<string>
{
    "Rebecca",
    "Mary",
    "Leah",
};

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

[Export]
public Godot.Collections.Array<Texture> Textures { get; set; }

[Export]
public Godot.Collections.Array<PackedScene> Scenes { get; set; }

其他建議

[Export]
public Godot.Collections.Dictionary Dictionary { get; set; }

Using the generic Godot.Collections.Dictionary<TKey, TValue> allows specifying the types of the key and value elements of the dictionary.

備註

目前 Godot 編輯器不支援型別化字典，因此 Inspector 不會限制可以指派的型別，這可能會導致執行時期異常。

[Export]
public Godot.Collections.Dictionary<string, int> Dictionary { get; set; }

The default value of Godot dictionaries is null. A different default can be specified:

[Export]
public Godot.Collections.Dictionary<string, int> CharacterLives { get; set; } = new Godot.Collections.Dictionary<string, int>
{
    ["Rebecca"] = 10,
    ["Mary"] = 42,
    ["Leah"] = 0,
};

匯出陣列

C# arrays can exported as long as the element type is a Variant-compatible type.

[Export]
public Vector3[] Vectors { get; set; }

[Export]
public NodePath[] NodePaths { get; set; }

The default value of C# arrays is null. A different default can be specified:

[Export]
public Vector3[] Vectors { get; set; } = new Vector3[]
{
    new Vector3(1, 2, 3),
    new Vector3(3, 2, 1),
}

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

從 工具模式 腳本中更改匯出變數值是，顯示在屬性面板上的值不會自動更新。要更新屬性面板上的值，則需要在設定匯出變數值後呼叫 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 _GetPropertyList() methods as described in 從物件中存取資料或邏輯.

也參考

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

警告

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