Godot Scene Tree: Nodes, get_node(), $ and add_child()

A Godot game is a tree of nodes. Each node does one job (draw a sprite, play a sound, detect a collision), and nodes hold child nodes. This script builds a small tree in code and prints it:

extends Node

func _ready():
	name = "Main"
	var level := Node2D.new()
	level.name = "Level"
	add_child(level)

	var player := Node2D.new()
	player.name = "Player"
	level.add_child(player)

	for i in 2:
		var coin := Node2D.new()
		coin.name = "Coin%d" % i
		level.add_child(coin)

	print_tree_pretty()

 ┖╴Main
    ┖╴Level
       ┠╴Player
       ┠╴Coin0
       ┖╴Coin1

In the editor you build the same tree in the Scene dock, and save it as a scene file (.tscn). A scene can be placed inside other scenes, so a Player scene, an Enemy scene and a Coin scene become parts of a Level scene.

Finding Nodes: get_node() and $

get_node() takes a path of names, relative to the node the script is on. $ is a shorter way to write it:

extends Node

func _ready():
	name = "Main"
	var ui := Control.new()
	ui.name = "UI"
	add_child(ui)
	var score := Label.new()
	score.name = "Score"
	ui.add_child(score)

	$UI/Score.text = "Score: 10"
	print(get_node("UI/Score").text)
	print($UI/Score.get_path())
	print($UI/Score.get_parent().name)
	print(get_node_or_null("UI/Lives") == null)

Score: 10
/root/Main/UI/Score
UI
true

A path depends on the tree's layout, so moving a node breaks the paths to it. For nodes you use often, right click them in the Scene dock and choose Access as Unique Name, then use %Name: it keeps working wherever the node moves inside the scene.

Adding and Removing Nodes

add_child() puts a node in the tree. queue_free() removes and deletes it at the end of the frame:

const CoinScene = preload("res://coin.tscn")

func spawn_coin(at: Vector2) -> void:
	var coin := CoinScene.instantiate()
	coin.position = at
	add_child(coin)

func _on_coin_collected(coin: Node) -> void:
	coin.queue_free()

• instantiate() creates a scene with all its children. Node2D.new() creates a single bare node.
• remove_child() takes a node out of the tree without deleting it, so you can add it somewhere else. reparent() does both in one call.
• Prefer queue_free() to free() for nodes in the tree: it waits until the frame is done, so code that still uses the node this frame does not crash.

Children and Groups

extends Node

func _ready():
	for i in 3:
		var enemy := Node.new()
		enemy.name = "Enemy%d" % i
		enemy.add_to_group("enemies")
		add_child(enemy)

	print(get_child_count())
	for child in get_children():
		print(child.name)
	var enemies := get_tree().get_nodes_in_group("enemies")
	print(enemies.size(), " in the group")
	print(get_child(0).is_in_group("enemies"))

3
Enemy0
Enemy1
Enemy2
3 in the group
true

Groups tag nodes anywhere in the tree. get_tree().call_group("enemies", "freeze") calls a method on every member, which is easier than keeping your own list.

The Order of _ready()

Godot calls _ready() on children before their parent, so a parent's _ready() can always use its children. _enter_tree() runs the other way, parents first:

extends Node

class Loud extends Node:
	func _enter_tree():
		print("enter ", name)
	func _ready():
		print("ready ", name)

func _ready():
	var parent := Loud.new()
	parent.name = "Parent"
	var child := Loud.new()
	child.name = "Child"
	parent.add_child(child)
	add_child(parent)

enter Parent
enter Child
ready Child
ready Parent

This is why get_node() is safe in _ready() and fails in _init(): during _init() the node has no children yet and is not in the tree. The @onready annotation is the usual way to store a child node in a variable.

get_tree()

get_tree() returns the SceneTree, the object that runs the game. Common uses:

get_tree().paused = true                           # pause the game
get_tree().reload_current_scene()                  # restart the level
get_tree().change_scene_to_file("res://menu.tscn") # load another scene
get_tree().quit()                                  # close the game
await get_tree().create_timer(1.0).timeout         # wait one second