Up to date

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

Nœuds et instances de scène

Ce guide explique comment obtenir des nœuds, créer des nœuds, les ajouter comme enfant et instancier des scènes à partir du code.

Obtenir des nœuds

Vous pouvez obtenir une référence à un nœud en appelant la méthode Node.get_node(). Pour que cela fonctionne, le nœud enfant doit être présent dans l'arbre de la scène. L'obtenir dans la fonction _ready() du nœud parent le garantit.

If, for example, you have a scene tree like this, and you want to get a reference to the Sprite2D and Camera2D nodes to access them in your script.

../../_images/nodes_and_scene_instances_player_scene_example.webp

Pour ce faire, vous pouvez utiliser le code suivant.

var sprite2d
var camera2d

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

Note that you get nodes using their name, not their type. Above, "Sprite2D" and "Camera2D" are the nodes' names in the scene.

../../_images/nodes_and_scene_instances_sprite_node.webp

If you rename the Sprite2D node as Skin in the Scene dock, you have to change the line that gets the node to get_node("Skin") in the script.

../../_images/nodes_and_scene_instances_sprite_node_renamed.webp

Chemins des nœuds

Lorsque vous obtenez une référence à un noeud, vous n'êtes pas limité à obtenir un enfant direct. La fonction get_node() supporte les chemins, un peu comme lorsque vous travaillez avec un navigateur de fichiers. Ajoutez une barre oblique pour séparer les noeuds.

Prenez l'exemple de scène suivant, avec le script attaché au nœud UserInterface.

../../_images/nodes_and_scene_instances_ui_scene_example.webp

To get the AnimationPlayer node, you would use the following code.

var animation_player

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

Note

Comme pour les chemins de fichiers, vous pouvez utiliser "..." pour obtenir un nœud parent. La meilleure pratique est d'éviter de le faire pour ne pas rompre l'encapsulation. Vous pouvez également commencer le chemin par un slash avant pour le rendre absolu, auquel cas votre nœud le plus haut serait "/root", la fenêtre racine prédéfinie de l'application.

Sucre syntaxique

You can use two shorthands to shorten your code in GDScript. Firstly, putting the @onready annotation before a member variable makes it initialize right before the _ready() callback.

@onready var sprite2d = get_node("Sprite2D")

Il existe aussi une notation courte pour get_node() : le signe dollar, "$". Vous le placez devant le nom ou le chemin du noeud que vous voulez obtenir.

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

Création de nœuds

Pour créer un noeud à partir du code, appelez sa méthode new() comme pour tout autre type de données basé sur une classe.

Vous pouvez stocker la référence du noeud nouvellement créé dans une variable et appeler add_child() pour l'ajouter comme enfant du noeud auquel vous avez attaché le script.

var sprite2d

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

Pour supprimer un noeud et le libérer de la mémoire, vous pouvez appeler sa méthode queue_free(). Cette méthode met le noeud en file d'attente pour le supprimer à la fin de l'image courante, une fois le traitement terminé. À ce moment-là, le moteur supprime le nœud de la scène et libère l'objet en mémoire.

sprite2d.queue_free()

Before calling sprite2d.queue_free(), the remote scene tree looks like this.

../../_images/nodes_and_scene_instances_remote_tree_with_sprite.webp

Après que le moteur ait libéré le nœud, l'arbre de scène distant n'affiche plus le sprite.

../../_images/nodes_and_scene_instances_remote_tree_no_sprite.webp

Vous pouvez également appeler free() pour détruire immédiatement le noeud. Vous devez le faire avec précaution car toute référence à ce noeud deviendra instantanément null. Nous vous recommandons d'utiliser queue_free() à moins que vous ne sachiez ce que vous faites.

Lorsque vous libérez un nœud, cela libère également tous ses enfants. Grâce à cela, pour supprimer une branche entière de l'arbre de scène, il suffit de libérer le nœud parent le plus élevé.

Instancier des scènes

Les scènes sont des modèles à partir desquels vous pouvez créer autant de reproductions que vous le souhaitez. Cette opération s'appelle l'instanciation et se fait en deux étapes à partir du code :

  1. Loading the scene from the local drive.

  2. Création d'une instance de la ressource chargée PackedScene.

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

Le préchargement de la scène peut améliorer l'expérience de l'utilisateur car l'opération de chargement se produit lorsque le compilateur lit le script et non au moment de l'exécution. Cette fonctionnalité n'est disponible qu'avec GDScript.

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

At that point, scene is a packed scene resource, not a node. To create the actual node, you need to call PackedScene.instantiate(). It returns a tree of nodes that you can use as a child of your current node.

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

L'avantage de ce processus en deux étapes est que vous pouvez garder une scène chargée et créer de nouvelles instances à la volée. Par exemple, pour créer rapidement une instance pour plusieurs ennemis ou balles.