GDScript exportierte Propertys

In Godot, class members can be exported. This means their value gets saved along with the resource (such as the scene) they're attached to, and get transferred over when using RPCs. They will also be available for editing in the property editor. Exporting is done by using the @export annotation.

@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

Gruppieren der Exporte

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 as a path to a file. See @export_file.

@export_file var f

String as a path to a directory. See @export_dir.

@export_dir var f

String as a path to a file, custom filter provided as hint. See again @export_file.

@export_file("*.txt") var f

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

String as a path to a PNG file in the global filesystem. See @export_global_file.

@export_global_file("*.png") var tool_image

String as a path to a directory in the global filesystem. See @export_global_dir.

@export_global_dir var tool_dir

The multiline annotation tells the editor to show a large input field for editing over multiple lines. See @export_multiline.

@export_multiline var text

Begrenzung der Eingabebereiche des Editors

See @export_range for all of the following.

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

The limits can be made to affect only the slider if you add the hints "or_less" and/or "or_greater". If either these hints are used, it will be possible for the user to enter any value or drag the value with the mouse when not using the slider, even if outside the specified range.

@export_range(0, 100, 1, "or_less", "or_greater") var l: int

The "exp" hint can be used to make a value have an exponential slider instead of a linear slider. This means that when dragging the slider towards the right, changes will become progressively faster when dragging the mouse. This is useful to make editing values that can be either very small or very large easier, at the cost of being less intuitive.

@export_range(0, 100000, 0.01, "exp") var exponential: float

For values that are meant to represent an easing factor, use Floats mit Easing-Hint instead.

The "hide_slider" hint can be used to hide the horizontal bar that appears below float properties, or the up/down arrows that appear besides int properties:

@export_range(0, 1000, 0.01, "hide_slider") var no_slider: float

Adding suffixes and handling degrees/radians

A suffix can also be defined to make the value more self-explanatory in the inspector. For example, to define a value that is meant to be configured as "meters" (m) by the user:

@export_range(0, 100, 1, "suffix:m") var m: int

For angles that are stored in radians but displayed as degrees to the user, use the "radians_as_degrees" hint:

@export_range(0, 360, 0.1, "radians_as_degrees") var angle: float

This performs automatic conversion when the value is displayed or modified in the inspector and also displays a degree (°) suffix. This approach is used by Godot's own rotation properties throughout the editor.

If the angle is stored in degrees instead, use the "degrees" hint to display the degree symbol while disabling the automatic degrees-to-radians conversion when the value is modified from the inspector.

Floats mit Easing-Hint

Display a visual representation of the ease() function when editing. See @export_exp_easing.

@export_exp_easing var transition_speed

Farben

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

@export var col: Color

Color given as red-green-blue value (alpha will always be 1). See @export_color_no_alpha.

@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

The drop-down menu will be limited to AnimationNode and all its derived classes.

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

See @export_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

See @export_enum.

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()

Andere Exportvarianten können auch beim Export von Arrays verwendet werden:

@export_range(-360, 360, 0.001, "degrees") var laser_angles: Array[float] = []
@export_file("*.json") var skill_trees: Array[String] = []
@export_color_no_alpha var hair_colors = PackedColorArray()
@export_enum("Espresso", "Mocha", "Latte", "Capuccino") var barista_suggestions: Array[String] = []

`@export_storage`

See @export_storage.

Standardmäßig hat das Exportieren einer Property zwei Auswirkungen:

es erreicht, dass die Property in der Szene/Ressourcendatei gespeichert wird (PROPERTY_USAGE_STORAGE);
es fügt dem Inspektor ein Feld hinzu (PROPERTY_USAGE_EDITOR).

Es kann jedoch vorkommen, dass Sie eine Property zwar serialisierbar machen, sie aber nicht im Editor anzeigen möchten, um unbeabsichtigte Änderungen und ein unübersichtliches Interface zu vermeiden.

Dazu können Sie @export_storage verwenden. Dies kann für @tool-Skripte nützlich sein. Außerdem wird der Property-Wert kopiert, wenn Resource.duplicate() oder Node.duplicate() aufgerufen wird, im Gegensatz zu nicht exportierten Variablen.

var a # Not stored in the file, not displayed in the editor.
@export_storage var b # Stored in the file, not displayed in the editor.
@export var c: int # Stored in the file, displayed in the editor.

`@export_custom`

If you need more control than what's exposed with the built-in @export annotations, you can use @export_custom instead. This allows defining any property hint, hint string and usage flags, with a syntax similar to the one used by the editor for built-in nodes.

For example, this exposes the altitude property with no range limits but a m (meter) suffix defined:

@export_custom(PROPERTY_HINT_NONE, "suffix:m") var altitude: float

The above is normally not feasible with the standard @export_range syntax, since it requires defining a range.

See the class reference for a list of parameters and their allowed values.

Warnung

When using @export_custom, GDScript does not perform any validation on the syntax. Invalid syntax may have unexpected behavior in the inspector.

`@export_tool_button`

If you need to create a clickable inspector button, you can use @export_tool_button. This exports a Callable property as a clickable button. When the button is pressed, the callable is called.

Export a button with label "Hello" and icon "Callable". When you press it, it will print "Hello world!".

@tool
extends Node

@export_tool_button("Hello", "Callable") var hello_action = hello

func hello():
    print("Hello world!")

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.