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.

Si, par exemple, vous avez un arbre de scène comme celui-ci, et que vous voulez obtenir une référence aux nœuds Sprite et Camera2D pour y accéder dans votre script.

../../_images/nodes_and_scene_instances_player_scene_example.png

Pour ce faire, vous pouvez utiliser le code suivant.

var sprite
var camera2d

func _ready():
    sprite = get_node("Sprite")
    camera2d = get_node("Camera2D")

private Sprite _sprite;
private Camera2D _camera2d;

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

    _sprite = GetNode<Sprite>("Sprite");
    _camera2d = GetNode<Camera2D>("Camera2D");
}

Notez que vous obtenez les nœuds en utilisant leur nom, et non leur type. Ci-dessus, "Sprite" et "Camera2D" sont les noms des noeuds dans la scène.

Si vous renommez le nœud Sprite en Skin dans le dock Scene, vous devez changer la ligne qui obtient le nœud en get_node("Skin") dans le script.

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.png

Pour obtenir le nœud Tween, vous devez utiliser le code suivant.

var tween

func _ready():
    tween = get_node("ShieldBar/Tween")

private Tween _tween;

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

    _tween = GetNode<Tween>("ShieldBar/Tween");
}

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¶

Vous pouvez utiliser deux abréviations pour raccourcir votre code dans GDScript. Tout d'abord, en plaçant le mot-clé onready devant une variable membre, on l'initialise juste avant le callback ready().

onready var sprite = get_node("Sprite")

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 sprite = $Sprite
onready var tween = $ShieldBar/Tween

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 sprite

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

private Sprite _sprite;

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

    _sprite = new Sprite(); // Create a new Sprite.
    AddChild(_sprite); // 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.

sprite.queue_free()

_sprite.QueueFree();

Afficher d'appeler sprite.queue_free(), l'arborescence de scène distante ressemble à ça.

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

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 :

Chargement de la scène depuis le disque dur.
Création d'une instance de la ressource chargée PackedScene.

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

var scene = GD.Load<PackedScene>("res://MyScene.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://MyScene.tscn")

À ce stade, scene est une ressource de scène empaquetée, non un nœud. Pour créer le nœud actuel, vous devez appeler PackedScene.instance(). Il retourne un arbre de nœuds que vous pouvez considérer comme enfant de votre nœud actuel.

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

var instance = scene.Instance();
AddChild(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.