godot-nodes-scenes

Godot Nodes & Scenes (4.x)

Compose games from nodes and scenes, instance them at runtime, and access the tree without crashing on freed or missing nodes. Targets Godot 4.7.

When to use

• Use when structuring .tscn scenes, choosing how to break a feature into nodes, instancing a PackedScene (bullets, enemies, UI), or setting up autoload singletons.
• Use when debugging get_node() / $Path returning null, or "Attempt to call on a previously freed instance".

When not to use: GDScript language/syntax → godot-gdscript; signal-based decoupling → godot-signals-groups; physics bodies/collisions → godot-physics.

Core workflow

1. Model with composition. A scene is a tree of nodes saved as .tscn. Build small, single-purpose scenes (Player, Bullet, Enemy) and compose larger scenes from them. Favor adding child nodes over deep inheritance.
2. Make a scene reusable by giving its root a script and exposing @export config. Save it; it becomes a PackedScene you can instance many times.
3. Instance at runtime with preload/load → scene.instantiate() → add_child(instance). Set position/state after adding (or before, both work).
4. Access nodes safely. Use @onready var x = $Path for fixed children; use unique names (%Name) for nodes deep in the tree; never assume a node still exists.
5. Use autoloads for global state/services (game state, audio, scene switching) — registered in Project Settings > Globals (Autoload), accessible by name everywhere.
6. Free nodes with queue_free() and guard later access with is_instance_valid().

Patterns

1. Instance a scene at runtime

extends Node2D
 
const BULLET := preload("res://bullet.tscn")   # preload: loaded at compile time
 
func

2. Safe node access: $, get_node_or_null, and unique names

3. An autoload singleton (global game state)

4. Change the running scene

Pitfalls

• $Path / get_node() return null or error when the path is wrong or the node isn't in the tree yet. Use @onready, verify the path matches the scene, or use get_node_or_null() for optional nodes.
• Renaming a node breaks $Path. Use unique names (%Name, set via right-click

  Access as Unique Name) so deep references survive renames and reparenting.

• free() mid-frame can crash other code still using the node. Prefer queue_free() (deletes at end of frame) and check is_instance_valid(node).
• Setting child state before add_child() is fine, but _ready() on the child only runs after it enters the tree — don't expect its @onready vars before that.
• Autoload order matters: autoloads are added before the main scene, in list order. An autoload can't depend on the main scene existing yet.
• instance() was renamed to instantiate() in Godot 4. preload runs at parse time (path must be constant); load runs at runtime (path can be a variable).
• change_scene_to_file() is deferred, not immediate — Godot swaps and frees the old scene at the end of the current frame. Any code after the call still runs against the old tree, and get_tree().current_scene isn't the new scene until next frame. Don't read the new scene's nodes on the same line; do it from the new scene's _ready().

References

• For scene inheritance, owner/ownership when saving scenes from code, groups vs unique names, and node-path edge cases, read references/tree-and-instancing.md.

Related skills

• godot-gdscript — language, lifecycle, and @onready.
• godot-signals-groups — decouple instanced scenes from their spawner.
• godot-resources — share data between instances without duplicating it.
• save-systems — persist scene/game state across runs.