Up to date

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

Nodes und Szeneninstanzen¶

In dieser Anleitung wird erklärt, wie man Nodes abruft, Nodes erstellt, sie als Child-Element hinzufügt und Szenen aus dem Code instanziiert.

Zugang zu Nodes¶

Sie können eine Referenz auf einen Node erhalten, indem Sie die Methode Node.get_node() aufrufen. Damit dies funktioniert, muss der Child-Node im Szenenbaum vorhanden sein. Dies wird durch die _ready() Funktion des Parent-Nodes garantiert.

Wenn Sie zum Beispiel einen Szenenbaum wie diesen haben und einen Verweis auf die Nodes Sprite2D und Camera2D erhalten möchten, um in Ihrem Skript darauf zuzugreifen.

../../_images/nodes_and_scene_instances_player_scene_example.webp

Dazu können Sie den folgenden Code verwenden.

var sprite2d
var camera2d

func _ready():
    sprite2d = get_node("Sprite2D")
    camera2d = get_node("Camera2D")

private Sprite2D _sprite2D;
private Camera2D _camera2D;

public override void _Ready()
{
    base._Ready();

    _sprite2D = GetNode<Sprite2D>("Sprite2D");
    _camera2D = GetNode<Camera2D>("Camera2D");
}

Beachten Sie, dass Sie Zugriff auf Nodes über ihren Namen und nicht über ihren Typ erhalten. Oben: "Sprite2D" und "Camera2D" sind die Namen der Nodes in der Szene.

Wenn Sie den Sprite2D-Node im Szenendock in Skin umbenennen, müssen Sie die Zeile, die den Node erhält, im Skript in get_node("Skin") ändern.

Node-Pfade¶

Wenn Sie eine Referenz auf einen Node erhalten, sind Sie nicht darauf beschränkt, einen direkten Child-Node zu erhalten. Die Funktion get_node() unterstützt Pfade, ein bisschen wie bei der Arbeit mit einem Dateibrowser. Fügen Sie einen Schrägstrich hinzu, um Nodes zu trennen.

Nehmen Sie die folgende Beispielszene, in der das Skript an den UserInterface-Node angehängt ist.

../../_images/nodes_and_scene_instances_ui_scene_example.webp

Um den AnimationPlayer-Node zu erhalten, würden Sie den folgenden Code verwenden.

var animation_player

func _ready():
    animation_player = get_node("ShieldBar/AnimationPlayer")

private AnimationPlayer _animationPlayer;

public override void _Ready()
{
    base._Ready();

    _animationPlayer = GetNode<AnimationPlayer>("ShieldBar/AnimationPlayer");
}

Bemerkung

Wie bei Dateipfaden, können Sie ".." verwenden, um einen Parent-Node zu erhalten. Es ist bewährte Praxis, dies zu vermeiden, um einen Kapselungsbruch zu vermeiden. Sie können den Pfad auch mit einem Schrägstrich beginnen, um ihn absolut zu machen. In diesem Fall wäre Ihr oberster Node "/root", der vordefinierte Root-Viewport der Anwendung.

Syntaktischer Zucker¶

Sie können zwei Abkürzungen verwenden, um Ihren Code in GDScript zu verkürzen. Erstens, wenn Sie die Anmerkung @onready vor eine Membervariable setzen, wird diese direkt vor dem _ready()-Callback initialisiert.

@onready var sprite2d = get_node("Sprite2D")

Es gibt auch eine Kurzschreibweise für get_node(): das Dollarzeichen, "$". Man setzt es vor den Namen oder den Pfad des Nodes, den man erhalten möchte.

@onready var sprite2d = $Sprite2D
@onready var animation_player = $ShieldBar/AnimationPlayer

Nodes erstellen¶

Um einen Node im Code zu erstellen, rufen Sie die Methode new() auf, genau wie für jeden anderen klassenbasierten Datentyp auch.

Sie können die Referenz des neu erstellten Nodes in einer Variablen speichern und add_child() aufrufen, um ihn als Child des Nodes hinzuzufügen, an den Sie das Skript angehängt haben.

var sprite2d

func _ready():
    var sprite2d = Sprite2D.new() # Create a new Sprite2D.
    add_child(sprite2d) # Add it as a child of this node.

private Sprite2D _sprite2D;

public override void _Ready()
{
    base._Ready();

    _sprite2D = new Sprite2D(); // Create a new Sprite2D.
    AddChild(_sprite2D); // Add it as a child of this node.
}

Um einen Node zu löschen und aus dem Speicher zu befreien, können Sie seine queue_free()-Methode aufrufen. Dadurch wird der Node in eine Warteschlange gestellt, um am Ende des aktuellen Frames gelöscht zu werden, nachdem die Verarbeitung abgeschlossen ist. Zu diesem Zeitpunkt entfernt die Engine den Node aus der Szene und gibt das Objekt im Speicher frei.

sprite2d.queue_free()

_sprite2D.QueueFree();

Vor dem Aufruf von sprite2d.queue_free() sieht der Remote-Szenenbaum wie folgt aus.

Nachdem die Engine den Node freigegeben hat, wird das Sprite im Remote-Szenenbaum nicht mehr angezeigt.

Sie können alternativ free() aufrufen, um den Node sofort zu zerstören. Sie sollten dies mit Vorsicht tun, da jede Referenz auf diesen Node sofort null wird. Wir empfehlen, queue_free() zu benutzen, wenn Sie nicht wissen, was Sie tun.

Wenn Sie einen Node freigeben, werden auch alle seine Child-Nodes freigegeben. Um einen ganzen Zweig des Szenenbaums zu löschen, müssen Sie also nur den obersten übergeordneten Node freigeben.

Instanziierung von Szenen¶

Szenen sind Vorlagen, aus denen Sie beliebig viele Reproduktionen erstellen können. Dieser Vorgang wird Instanziierung genannt, und er erfolgt im Code in zwei Schritten:

Laden der Szene vom lokalen Laufwerk.
Erstellen einer Instanz der geladenen Ressource PackedScene.

var scene = load("res://my_scene.tscn")

var scene = GD.Load<PackedScene>("res://MyScene.tscn");

Das Vorladen der Szene kann das Benutzererlebnis verbessern, da der Ladevorgang beim Lesen des Skripts durch den Compiler und nicht zur Laufzeit erfolgt. Diese Funktion ist nur mit GDScript verfügbar.

var scene = preload("res://my_scene.tscn")

Zu diesem Zeitpunkt ist scene eine gepackte Szenenressource, kein Node. Um den eigentlichen Node zu erzeugen, müssen Sie PackedScene.instantiate() aufrufen. Sie gibt einen Baum von Nodes zurück, den du als Child deines aktuellen Nodes verwenden kannst.

var instance = scene.instantiate()
add_child(instance)

var instance = scene.Instantiate();
AddChild(instance);

Der Vorteil dieses zweistufigen Prozesses besteht darin, dass Sie eine gepackte Szene geladen lassen und neue Instanzen im Handumdrehen erstellen können. Zum Beispiel, um schnell mehrere Feinde oder Kugeln zu instanziieren.