Up to date

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

Exportierte Propertys in C#

In Godot können Klassenmember exportiert werden. Das bedeutet, dass ihr Wert zusammen mit der Ressource (z. B. der Szene) gespeichert wird, der sie zugeordnet sind. Sie sind dann auch für die Bearbeitung im Property-Editor verfügbar. Das Exportieren wird mit dem [Export]-Attribut durchgeführt.

using Godot;

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

In diesem Beispiel wird der Wert 5 gespeichert und nach dem Erstellen des aktuellen Projekts im Property-Editor angezeigt.

Einer der größten Vorteile exportierter Variablen ist, dass diese im Editor sichtbar und veränderbar sind. Auf diese Weise können Grafiker, Spiele-Designer, etc. diese Werte verändert, die dann das Spielgeschehen beeinflussen. Hierfür gibt es eine spezielle Export-Syntax.

Exportieren kann nur mit Variant-kompatiblen-Typen durchgeführt werden.

Bemerkung

Der Export von Propertys kann auch in GDScript erfolgen, Informationen dazu finden Sie unter GDScript exportierte Propertys.

Grundlegende Verwendung

Exportieren funktioniert mit Feldern und Propertys.

[Export]
private int _number;

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

Exportierte Member können einen Defaultwert angeben; andernfalls wird stattdessen der Defaultwert des Typs verwendet.

[Export]
private int _number; // Defaults to '0'

[Export]
private string _text; // Defaults to 'null' because it's a reference type

[Export]
private string _greeting = "Hello World"; // Exported field specifies a default value

[Export]
public string Greeting { get; set; } = "Hello World"; // Exported property specifies a default value

// This property uses `_greeting` as its backing field, so the default value
// will be the default value of the `_greeting` field.
[Export]
public string GreetingWithBackingField
{
    get => _greeting;
    set => _greeting = value;
}

Ressourcen und Nodes können exportiert werden.

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

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

Gruppieren der Exporte

Es ist möglich, die exportierten Propertys innerhalb des Inspektors mit dem Attribut [ExportGroup] zu gruppieren. Jede exportierte Property nach diesem Attribut wird zu dieser Gruppe hinzugefügt. Beginnen Sie eine neue Gruppe oder verwenden Sie [ExportGroup("")], um sie abzubrechen.

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

Das zweite Argument des Attributs kann verwendet werden, um nur Propertys mit dem angegebenen Präfix zu gruppieren.

Gruppen können nicht verschachtelt werden, verwenden Sie [ExportSubgroup] um Untergruppen innerhalb einer Gruppe zu erstellen.

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

Sie können auch den Namen Ihrer Hauptkategorie ändern oder zusätzliche Kategorien in der Property-Liste mit dem Attribut [ExportCategory] erstellen.

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

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

Bemerkung

Die Liste der Propertys ist auf der Grundlage der Klassenvererbung organisiert, und neue Kategorien brechen mit dieser Erwartung. Verwenden Sie sie sorgfältig, insbesondere bei der Erstellung von Projekten für die öffentliche Nutzung.

Strings als Pfade

Property-Hints können verwendet werden, um Strings als Pfade zu exportieren

String als Pfad zu einer Datei.

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

String als Pfad zu einem Verzeichnis.

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

String als Pfad zu einer Datei, benutzerdefinierter Filter wird als Hint angegeben.

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

Die Verwendung von Pfaden im globalen Dateisystem ist ebenfalls möglich, allerdings nur in Skripten im Tool-Modus.

String als Pfad zu einer PNG-Datei im globalen Dateisystem.

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

String als Pfad zu einem Verzeichnis im globalen Dateisystem.

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

Die mehrzeilige Annotation weist den Editor an, ein großes Eingabefeld zur Bearbeitung über mehrere Zeilen anzuzeigen.

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

Begrenzung der Eingabebereiche des Editors

Mit Hilfe des Range Property-Hints können Sie einschränken, was mit dem Editor als Wert eingegeben werden kann.

Erlauben von Integer-Werten zwischen 0 und 20.

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

Erlauben von Integer-Werten zwischen -10 und 20.

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

Erlauben von Floats zwischen -10 und 20 und Einrasten des Wertes auf Vielfache von 0.2.

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

Wenn Sie die Hints "or_greater" und/oder "or_less" hinzufügen, können Sie beim Einstellen des Wertes über oder unter die Grenzen gehen, indem Sie ihn eingeben, anstatt den Schieberegler zu verwenden.

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

Floats mit Easing-Hint

Zeigt eine visuelle Darstellung der Funktion 'ease()' bei der Bearbeitung an.

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

Farben

Normale Farbe, die als Rot-Grün-Blau-Alpha-Wert angegeben wird.

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

Die Farbe wird als Rot-Grün-Blau-Wert angegeben (Alpha ist immer 1).

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

Nodes

Seit Godot 4.0 können Nodes direkt exportiert werden, ohne NodePaths verwenden zu müssen.

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

Es können auch eigene Node-Klassen verwendet werden, siehe Globale C#-Klassen.

Das Exportieren von NodePaths wie in Godot 3.x ist immer noch möglich, falls Sie es benötigen:

[Export]
private NodePath _nodePath;

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

Ressourcen

[Export]
private Resource Resource;

Im Inspektor können Sie dann eine Ressourcendatei aus dem Dateisystem-Dock per Drag&Drop in den Variablenslot ziehen.

Das Öffnen des Inspektor-Dropdowns kann jedoch zu einer extrem langen Liste möglicher zu erstellender Klassen führen. Wenn Sie daher einen von Resource abgeleiteten Typ angeben, z.B.:

[Export]
private AnimationNode Resource;

Das Dropdown-Menü wird auf AnimationNode und alle seine geerbten Klassen beschränkt. Benutzerdefinierte Ressourcenklassen können ebenfalls verwendet werden, siehe Globale C#-Klassen.

Es ist zu beachten, dass die exportierten Propertys auch dann editierbar sind, wenn das Skript im Editor nicht ausgeführt wird. Dies kann in Verbindung mit einem Skript im "Tool"-Modus verwendet werden.

Exportieren von Bit-Flags

Member, deren Typ ein Enum mit dem Attribut [Flags] ist, können exportiert werden und ihre Werte sind auf die Member des Enum-Typs beschränkt. Der Editor erzeugt ein Widget im Inspektor, das es erlaubt, keines, eines oder mehrere der Enum-Mitglieder auszuwählen. Der Wert wird als Integer gespeichert.

// Use power of 2 values for the values of the enum members.
[Flags]
public enum MyEnum
{
    Fire = 1 << 1,
    Water = 1 << 2,
    Earth = 1 << 3,
    Wind = 1 << 4,

    // A combination of flags is also possible.
    FireAndWater = Fire | Water,
}

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

Integer, die als Bit-Flags verwendet werden, können mehrere true/false (boolesche)-Werte in einer Property speichern. Mit dem Property-Hinweis Flags können sie im Editor gesetzt werden.

// Set any of the given flags from the editor.
[Export(PropertyHint.Flags, "Fire,Water,Earth,Wind")]
public int SpellElements { get; set; } = 0;

Sie müssen für jedes Flag eine Beschreibung angeben. In diesem Beispiel hat Fire den Wert 1, Water den Wert 2, Earth den Wert 4 und Wind entspricht dem Wert 8. Normalerweise sollten Konstanten entsprechend definiert werden (z.B. private const int ElementWind = 8 und so weiter).

Sie können explizite Werte mit einem Doppelpunkt hinzufügen:

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

Als Bit-Flag-Optionen sind nur Werte in 2er-Potenzen zulässig. Der niedrigste zulässige Wert ist 1, da 0 bedeutet, dass nichts ausgewählt ist. Sie können auch Optionen hinzufügen, die eine Kombination aus anderen Flags sind:

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

Für die in den Projekteinstellungen definierten Physik- und Renderebenen werden ebenfalls Exportkommentare bereitgestellt.

[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; }

Die Verwendung von Bit-Flags erfordert ein gewisses Verständnis der bitweisen Operationen. Verwenden Sie im Zweifelsfall stattdessen boolesche Variablen.

Exportieren von Enums

Member, deren Typ ein Enum ist, können exportiert werden und ihre Werte sind auf die Member des Enum-Typs beschränkt. Der Editor erstellt ein Widget im Inspector, das die folgenden Elemente aufzählt: "Ding 1", "Ding 2", "Noch ein Ding". Der Wert wird als Integer gespeichert.

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

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

Integer- und String-Members können auch auf eine bestimmte Liste von Werten beschränkt werden, indem die [Export]-Annotation mit dem PropertyHint.Enum-Hinweis verwendet wird. Der Editor erstellt ein Widget im Inspektor, das die folgenden Werte aufzählt: Warrior, Magician, Thief. Der Wert wird als Integer gespeichert, wobei der Index der ausgewählten Option entspricht (d.h. 0, 1 oder 2).

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

Sie können explizite Werte mit einem Doppelpunkt hinzufügen:

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

Wenn der Typ String ist, wird der Wert als String gespeichert.

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

Wenn Sie einen Initialwert setzen wollen, müssen Sie diesen explizit angeben:

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

Exportieren von Collections

Wie in der C# Variant-Dokumentation erläutert, sind nur bestimmte C#-Arrays und die im Godot.Collections-Namespace definierten Collection-Typen Variant-kompatibel, daher können nur diese Typen exportiert werden.

Exportieren von Godot-Arrays

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

Die Verwendung des generischen Godot.Collections.Array<T> erlaubt die Angabe des Typs der Array-Elemente, die als Hint für den Editor verwendet werden. Der Inspektor beschränkt die Elemente auf den angegebenen Typ.

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

Der Defaultwert von Godot-Arrays ist null, ein anderer Defaultwert kann angegeben werden:

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

Arrays mit bestimmten Typen, die von Resource erben, können durch Drag&Drop mehrerer Dateien aus dem Dateisystem-Dock gesetzt werden.

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

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

Exportieren von Godot-Dictionarys

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

Die Verwendung des generischen Godot.Collections.Dictionary<TKey, TValue> erlaubt es, den Typ der Key- und Value-Elemente des Dictionarys zu spezifizieren.

Bemerkung

Typisierte Dictionarys werden derzeit im Godot-Editor nicht unterstützt, so dass der Inspektor die Typen, die zugewiesen werden können, nicht einschränkt, was zu Laufzeit-Exceptions führen kann.

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

Der Defaultwert von Godot-Dictionarys ist null, ein anderer Defaultwert kann angegeben werden:

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

Exportieren von C#-Arrays

C#-Arrays können exportiert werden, solange der Elementtyp ein Variant-kompatibler-Typ ist.

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

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

Der Defaultwert von C#-Arrays ist null, ein anderer Default kann angegeben werden:

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

Festlegen exportierter Variablen aus einem Tool-Skript

Wenn Sie den Wert einer exportierten Variablen aus einem Skript im Tool-Modus ändern, wird der Wert im Inspektor nicht automatisch aktualisiert. Um ihn zu aktualisieren, rufen Sie NotifyPropertyListChanged() auf, nachdem Sie den Wert der exportierten Variable gesetzt haben.

Fortgeschrittene Exporte

Nicht jede Art von Export kann auf der Sprachebene selbst bereitgestellt werden, um unnötige Designkomplexität zu vermeiden. Im Folgenden werden einige mehr oder weniger häufig verwendete Exportfunktionen beschrieben, die mit einer Low-Level-API implementiert werden können.

Bevor Sie weiter lesen, sollten Sie sich mit der Art und Weise vertraut machen, wie Propertys behandelt werden und wie sie mit _Set(), _Get(), und _GetPropertyList()-Methoden angepasst werden können, wie in Zugriff auf Daten oder Logik aus einem Objekt beschrieben.

Siehe auch

Informationen zum Binden von Propertys mit den oben genannten Methoden in C++ finden Sie unter Binding von Propertys mit _set/_get/_get_property_list.

Warnung

Das Skript muss im Tool -Modus arbeiten, damit die oben genannten Methoden im Editor ausgeführt werden können.