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.