@export und Annotationen in Godot 4

Einführung: Von Keywords zu Annotationen

Godot 4 hat mehrere GDScript-Keywords durch Annotationen mit @-Präfix ersetzt. Das war Teil einer größeren Bemühung, die GDScript-Syntax sauberer und konsistenter zu machen. Die drei wichtigsten Änderungen sind:

• export → @export
• onready → @onready
• tool → @tool

Annotationen werden in die Zeile vor (oder in dieselbe Zeile wie) die Deklaration gesetzt, die sie modifizieren. Godot 4 führte außerdem viele neue Annotationsvarianten wie @export_range, @export_group und @export_category ein, die es in Godot 3 nicht gab. Dieser Leitfaden behandelt sie alle.

Grundlegendes @export

Die @export-Annotation macht eine Variable im Godot-Inspector sichtbar und lässt dich Werte konfigurieren, ohne Code zu bearbeiten. Godot wählt automatisch das passende Editor-Widget basierend auf dem Typ der Variable.

@export var speed: float = 300.0
@export var player_name: String = "Player"
@export var health: int = 100
@export var color: Color = Color.WHITE
@export var texture: Texture2D
@export var scene: PackedScene

Tipp: Füge exportierten Variablen immer Typ-Annotationen hinzu. So stellt der Inspector das richtige Widget dar (z. B. einen Farbwähler für Color, einen Ressourcen-Slot für Texture2D).

@export_range — Numerische Schieberegler

@export_range beschränkt einen numerischen Wert auf ein Minimum und Maximum und zeigt einen Schieberegler im Inspector an. Du kannst auch eine Schrittgröße und Hinweise wie "or_greater" oder "or_less" angeben.

@export_range(0, 100) var health: int = 100
@export_range(0.0, 1.0, 0.01) var volume: float = 0.8
@export_range(0, 1000, 1, "or_greater") var damage: int = 10

Der Hinweis "or_greater" erlaubt das Eingeben von Werten über dem Maximum, während der Schiebereglerbereich fokussiert bleibt. Analog erlaubt "or_less" Werte unter dem Minimum.

@export_enum — Dropdown-Menüs

@export_enum erzeugt ein Dropdown im Inspector. Bei Verwendung mit String wird der Name der ausgewählten Option gespeichert. Bei Verwendung mit int kannst du explizite Werte zuweisen.

# Stores the string name: "Warrior", "Mage", or "Rogue"
@export_enum("Warrior", "Mage", "Rogue") var character_class: String

# Stores the integer value: 0, 1, or 2
@export_enum("Easy:0", "Normal:1", "Hard:2") var difficulty: int = 1

@export_file und @export_dir — Datei-/Verzeichnispfade

@export_file zeigt einen Dateidialog im Inspector an. Du kannst nach Dateiendung filtern. @export_dir zeigt einen Verzeichnisauswahldialog an.

@export_file("*.tscn") var next_level: String
@export_dir var save_directory: String

Der Filter-String verwendet Glob-Muster. Mehrere Filter können mit Kommas getrennt werden: "*.png,*.jpg".

@export_multiline und @export_placeholder

@export_multiline stellt einen großen Textbereich für mehrzeilige Strings bereit (ideal für Dialoge oder Beschreibungen). @export_placeholder zeigt einen Hinweistext im Feld an, wenn es leer ist.

@export_multiline var description: String
@export_placeholder("Enter name...") var player_name: String

@export_group und @export_subgroup — Inspector-Eigenschaften organisieren

@export_group erzeugt eine einklappbare Gruppen-Kopfzeile im Inspector. Alle folgenden @export-Variablen gehören zu dieser Gruppe, bis zur nächsten Gruppe oder Kategorie. @export_subgroup verschachtelt sich innerhalb der aktuellen Gruppe.

@export_group("Movement")
@export var speed: float = 300.0
@export var jump_force: float = 400.0

@export_group("Combat")
@export var attack_damage: int = 10
@export var defense: int = 5

@export_subgroup("Ranged")
@export var projectile_speed: float = 500.0

Gruppen und Untergruppen dienen rein der Organisation — sie beeinflussen nicht den Variablenzugriff im Code, sondern nur, wie Eigenschaften im Inspector erscheinen.

@export_category — Fette Kategorie-Kopfzeilen

@export_category erzeugt eine fette Kategorie-Kopfzeile auf oberster Ebene im Inspector. Anders als Gruppen können Kategorien nicht eingeklappt werden und wirken als starke visuelle Trennung zwischen nicht zusammengehörenden Eigenschaftssätzen.

@export_category("Player Stats")
@export var level: int = 1
@export var experience: int = 0

@export mit Node-Referenzen

Du kannst einen NodePath exportieren, damit Designer einen Node aus dem Szenenbaum auswählen können. In Godot 4.2+ kannst du eine typisierte Node-Referenz direkt exportieren — kein NodePath nötig.

# Classic NodePath export
@export var target_path: NodePath

# Godot 4.2+: typed node export (direct reference, no NodePath needed)
@export var sprite: Sprite2D
@export var collision: CollisionShape2D

Typisierte Node-Exports sind der empfohlene Ansatz im modernen Godot 4. Der Inspector zeigt einen Node-Picker, der auf den angegebenen Typ gefiltert ist, und du bekommst volle Autovervollständigung im Skript-Editor.

@export_flags — Bitmask-Kontrollkästchen

@export_flags erzeugt einen Satz Kontrollkästchen, bei dem jede Option einem Bit in einer Ganzzahl entspricht. Godot bietet außerdem integrierte Flag-Exports für Physik- und Render-Layer.

# Custom flags: Fire=1, Water=2, Earth=4, Wind=8
@export_flags("Fire", "Water", "Earth", "Wind") var elements: int

# Built-in physics layer flags
@export_flags_2d_physics var collision_layers: int
@export_flags_2d_render var render_layers: int
@export_flags_3d_physics var collision_layers_3d: int

@onready — Verzögerte Initialisierung

@onready verzögert die Initialisierung einer Variable, bis der Node den Szenenbaum betritt (entspricht der Zuweisung in _ready()). Das ist unverzichtbar, wenn du Kind-Nodes mit $ referenzierst, weil Kinder zur Parse-Zeit noch nicht verfügbar sind.

# Godot 3 (old syntax):
# onready var sprite = $Sprite2D

# Godot 4:
@onready var sprite: Sprite2D = $Sprite2D
@onready var anim: AnimationPlayer = $AnimationPlayer
@onready var label: Label = $UI/ScoreLabel

Best Practice: Typisiere deine @onready-Variablen immer. Das aktiviert Autovervollständigung und fängt Typfehler zur Parse-Zeit statt zur Laufzeit ab.

@tool — Skripte im Editor ausführen

@tool lässt ein Skript innerhalb des Godot-Editors ausführen (nicht nur zur Laufzeit). Das ist mächtig, um eigene Vorschauen, Gizmos und live aktualisierte Eigenschaften zu erstellen. Platziere es ganz oben im Skript, vor extends.

@tool
extends Node2D

@export var radius: float = 100.0:
    set(value):
        radius = value
        queue_redraw()  # Redraw in editor when value changes

func _draw() -> void:
    draw_circle(Vector2.ZERO, radius, Color.WHITE)

Achtung: Sei vorsichtig mit @tool-Skripten. Code in _process() und _physics_process() läuft im Editor. Verwende Engine.is_editor_hint(), um reine Spiel-Logik abzusichern.

Weitere Annotationen

@icon

Legt ein eigenes Symbol für den Node-Typ des Skripts im Szenen-Dock und im Dialog „Node erstellen" fest.

@icon("res://icons/enemy.svg")
extends CharacterBody2D

@warning_ignore

Unterdrückt bestimmte GDScript-Warnungen für die nächste Anweisung. Nützlich, wenn du absichtlich eine Variable überschattest oder einen ungenutzten Parameter hast.

@warning_ignore("unused_parameter")
func _on_body_entered(body: Node2D) -> void:
    queue_free()

@warning_ignore("shadowed_variable")
var size: int = 10

@static_unload

Markiert ein Skript, damit Godot es aus dem Speicher entladen kann, wenn keine Instanzen existieren. Das kann den Speicherverbrauch für Skripte reduzieren, die nur vorübergehend genutzt werden. Das Skript darf keine statischen Variablen oder Daten haben, die erhalten bleiben müssen.

@static_unload
extends RefCounted

# This script can be safely unloaded when not in use

Best Practices für statische Typisierung

Auch wenn es keine Annotationen sind, hängen statische Typ-Hinweise eng damit zusammen und werden in Godot 4 dringend empfohlen. Sie verbessern die Autovervollständigung, ermöglichen Fehlerprüfung zur Kompilierzeit und können die Performance verbessern.

# Variable type annotations
var speed: float = 300.0
var player: CharacterBody2D = null
var items: Array[String] = []
var scores: Dictionary = {}

# Function return types and parameter types
func get_damage() -> int:
    return attack - defense

func apply_force(direction: Vector2, strength: float) -> void:
    velocity += direction * strength

# Type inference with :=
var pos := Vector2(100, 200)  # Inferred as Vector2

Hinweis: Sei vorsichtig mit := in for-Schleifen, wenn du über untypisierte Arrays iterierst. Verwende stattdessen explizite Typ-Annotationen: for item: String in array.

Migrations-Spickzettel: Godot 3 auf 4

Kurzreferenz zum Umwandeln der Godot-3-Export-Syntax in Godot-4-Annotationen: