Up to date

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

Nodos y instancias de escenas

Esta guía explica cómo obtener nodos, crear nodos, agregarlos como hijos e instanciar escenas desde el código.

Obteniendo nodos

Puedes obtener una referencia a un nodo llamando al método Node.get_node(). Para que esto funcione, el nodo hijo debe estar presente en el árbol de escena. Obtenerlo en la función _ready() del nodo padre garantiza que esté disponible.

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

Para hacer eso, puedes usar el siguiente código.

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

Rutas de nodos

Cuando obtienes una referencia a un nodo, no estás limitado a obtener solo un hijo directo. La función get_node() admite rutas, de manera similar a cómo funciona en un explorador de archivos. Agrega una barra diagonal (/) para separar los nodos en la ruta.

Toma la siguiente escena de ejemplo, con el script adjunto al nodo 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")

Nota

Como con las rutas de archivos, también puedes usar ".." para obtener un nodo padre. Sin embargo, la mejor práctica es evitar hacerlo para no romper la encapsulación. También puedes comenzar la ruta con una barra diagonal (/) para hacerla absoluta, en cuyo caso el nodo más alto sería "/root", el viewport raíz predefinido de la aplicación.

Azucar sintactico

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

Correcto. También existe una notación abreviada para get_node(): el signo de dólar, "$". Lo colocas antes del nombre o la ruta del nodo que deseas obtener.

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

Creación de nodos

Para crear un nodo mediante código, se debe usar el método new() como en cualquier otro tipo de dato basado en clases.

Puedes almacenar la referencia del nuevo nodo creado en una variable y llamar a add_child() para agregarlo como hijo del nodo al que adjuntaste el script.

var sprite2d

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

Para eliminar un nodo y liberarlo de la memoria, puedes llamar a su método queue_free(). Al hacerlo, el nodo se encola para ser eliminado al final del fotograma actual después de que haya terminado de procesar. En ese momento, el motor quitará el nodo de la escena y liberará el objeto en la memoria.

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

Después de que el motor liberó el nodo, el árbol de escena remoto ya no muestra el sprite.

../../_images/nodes_and_scene_instances_remote_tree_no_sprite.webp

Alternativamente, puedes llamar a free() para destruir inmediatamente el nodo. Debes hacerlo con cuidado, ya que cualquier referencia a él se convertirá instantáneamente en null. Recomendamos usar queue_free() a menos que sepas lo que estás haciendo.

Cuando liberas un nodo, también liberas a todos sus hijos. Gracias a esto, para eliminar una rama completa del árbol de escena, solo necesitas liberar el nodo padre más alto (topmost).

Instanciación de escenas

Las escenas son plantillas desde las cuales puedes crear tantas reproducciones como desees. Esta operación se llama instanciación, y realizarla desde el código se realiza en dos pasos:

  1. Loading the scene from the local drive.

  2. Crear una instancia del recurso PackedScene cargado.

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

Precargar la escena puede mejorar la experiencia del usuario, ya que la operación de carga ocurre cuando el compilador lee el script y no en tiempo de ejecución. Esta característica solo está disponible en 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)

La ventaja de este proceso en dos pasos es que puedes mantener una escena empaquetada cargada y crear nuevas instancias sobre la marcha. Por ejemplo, para crear rápidamente varias instancias de enemigos o balas.