Up to date

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

GDScript exportierte Propertys

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 werden auch für die Bearbeitung im Property-Editor verfügbar sein. Der Export erfolgt durch die Verwendung der @export-Anmerkung.

@export var number: int = 5

In diesem Beispiel wird der Wert 5 gespeichert und im Property-Editor angezeigt.

Eine exportierte Variable muss mit einem konstanten Ausdruck initialisiert werden oder einen Typspezifizierer in der Variable haben. Einige der Annotationen für den Export haben einen bestimmten Typ und benötigen keine Typisierung der Variablen (siehe Abschnitt Beispiele unten).

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.

Bemerkung

Der Export von Propertys kann auch in anderen Sprachen wie C# durchgeführt werden. Die Syntax variiert je nach Sprache. Siehe Exportierte Propertys in C# für Informationen über C#-Exporte.

Grundlegende Verwendung

Wenn der exportierte Wert einer Konstante oder einem konstanten Ausdruck zugewiesen wird, wird der Typ abgeleitet und im Editor verwendet.

@export var number = 5

Wenn es keinen Default-Wert gibt, können Sie der Variablen einen Typ hinzufügen.

@export var number: int

Ressourcen und Nodes können exportiert werden.

@export var resource: Resource
@export var node: Node

Gruppierung von Exporten

Mit der Annotation @export_group können Sie Ihre exportierten Propertys innerhalb des Inspektors gruppieren. Jede exportierte Property nach dieser Annotation wird der Gruppe hinzugefügt. Beginnen Sie eine neue Gruppe oder verwenden Sie @export_group(""), um die Gruppe zu verlassen.

@export_group("My Properties")
@export var number = 3

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

Gruppen können nicht verschachtelt werden. Verwenden Sie @export_subgroup um Untergruppen innerhalb einer Gruppe zu erstellen.

@export_subgroup("Extra Properties")
@export var string = ""
@export var flag = false

Sie können auch den Namen Ihrer Hauptkategorie ändern oder mit der Annotation @export_category zusätzliche Kategorien in der Property-Liste erstellen.

@export_category("Main Category")
@export var number = 3
@export var string = ""

@export_category("Extra Category")
@export var flag = false

Bemerkung

Die Liste der Propertys ist auf der Grundlage der Klassenvererbung organisiert, und die neuen Kategorien brechen mit dieser Erwartung. Verwenden Sie sie sorgfältig, insbesondere bei der Erstellung von Projekten, die für die Öffentlichkeit bestimmt sind.

Strings als Pfade

String als Pfad zu einer Datei.

@export_file var f

String als Pfad zu einem Verzeichnis.

@export_dir var f

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

@export_file("*.txt") var f

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_global_file("*.png") var tool_image

String als Pfad zu einem Verzeichnis im globalen Dateisystem.

@export_global_dir var tool_dir

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

@export_multiline var text

Begrenzung der Eingabebereiche des Editors

Erlauben von Integer-Werten zwischen 0 und 20.

@export_range(0, 20) var i

Erlauben von Integer-Werten zwischen -10 und 20.

@export_range(-10, 20) var j

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

@export_range(-10, 20, 0.2) var k: float

Die Grenzen können nur für den Schieberegler gelten, wenn Sie die Hinweise "or_greater" und/oder "or_less" hinzufügen.

@export_range(0, 100, 1, "or_greater", "or_less")

Floats mit Easing-Hint

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

@export_exp_easing var transition_speed

Farben

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

@export var col: Color

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

@export_color_no_alpha var col: Color

Nodes

Seit Godot 4.0 können Nodes direkt als Property in ein Skript exportiert werden, ohne NodePaths verwenden zu müssen:

# 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

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

@export var node_path: NodePath
var node = get_node(node_path)

Wenn Sie die Node-Typen für NodePaths einschränken wollen, können Sie die Annotation @export_node_path verwenden:

@export_node_path("Button", "TouchScreenButton") var some_button

Ressourcen

@export var 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 eine Erweiterung der Ressource angeben, wie z. B.:

@export var resource: AnimationNode

Das Dropdown-Menü wird auf AnimationNode und alle seine geerbten Klassen beschränkt.

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

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

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

Sie müssen für jedes Flag eine String-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. const ELEMENT_WIND = 8 und so weiter).

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

@export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0

Als Bitflag-Optionen sind nur Werte in Zweierpotenzen 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_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")
var spell_targets = 0

Export-Annotationen werden auch für die in den Projekteinstellungen definierten Physik-, Render- und Navigationsebenen bereitgestellt:

@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

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

Exportieren von Enums

Propertys können mit einem Typ-Hinweis exportiert werden, der auf eine Aufzählung verweist, um ihre Werte auf die Werte der Aufzählung zu beschränken. Der Editor erstellt ein Widget im Inspektor, das die folgenden Aufzählungen enthält: "Thing 1", "Thing 2", "Another Thing". Der Wert wird als Integer gespeichert.

enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
@export var x: NamedEnum

Integer- und String-Propertys können auch mit der Annotation @export_enum auf eine bestimmte Liste von Werten beschränkt werden. Der Editor erstellt ein Widget im Inspektor, das die folgenden Werte aufzählt: Krieger, Magier, Dieb. Der Wert wird als Integer gespeichert, entsprechend dem Index der gewählten Option (d.h. 0, 1 oder 2).

@export_enum("Warrior", "Magician", "Thief") var character_class: int

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

@export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int

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

@export_enum("Rebecca", "Mary", "Leah") var character_name: String

Wenn Sie einen Anfangswert festlegen wollen, müssen Sie ihn explizit angeben:

@export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca"

Exportieren von Arrays

Exportierte Arrays können Initialisierer haben, diese müssen jedoch konstante Ausdrücke sein.

Wenn das exportierte Array einen Typ angibt, der von Resource erbt, können die Array-Werte im Inspektor festgelegt werden, indem mehrere Dateien gleichzeitig aus dem FileSystem-Dock per Drag&Drop gezogen abgelegt werden.

Der Defaultwert muss ein konstanter Ausdruck sein.

@export var a = [1, 2, 3]

Exportierte Arrays können den Typ angeben (mit denselben Hints wie zuvor).

@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]]

Sie können den Defaultwert weglassen, aber er wäre dann null, wenn er nicht zugewiesen wird.

@export var b: Array
@export var scenes: Array[PackedScene]

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

@export var textures: Array[Texture] = []
@export var scenes: Array[PackedScene] = []

Gepackte Arrays funktionieren ebenfalls, allerdings nur bei leeren Initialisierungen:

@export var vector3s = PackedVector3Array()
@export var strings = PackedStringArray()

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 notify_property_list_changed() 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 weiterlesen, sollten Sie sich mit der Art und Weise vertraut machen, wie Propertys behandelt werden und wie sie mit _set(), _get(), und _get_property_list()-Methoden beliebig 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.