Scene tree and nodes

Purpose

scene/ is the layer above core that gives the engine its game-friendly shape: a MainLoop subclass called SceneTree that owns a tree of Nodes, and a large hierarchy of built-in node types for 2D, 3D, GUI, animation, audio, physics, navigation, and XR. When an exported game runs, SceneTree is what the engine ticks every frame; almost everything visible to a game developer lives here.

Directory layout

scene/
├── main/         SceneTree, Node, Window, Viewport, CanvasItem, CanvasLayer, MultiplayerAPI, Timer
├── 2d/           Node2D and 2D node types (Sprite2D, TileMap, Camera2D, Light2D, GPUParticles2D, …)
│   ├── physics/      CollisionShape2D, RigidBody2D, CharacterBody2D, Joint2D, Area2D, …
│   └── navigation/   NavigationAgent2D, NavigationRegion2D, NavigationLink2D, NavigationObstacle2D
├── 3d/           Node3D and 3D node types (Camera3D, Light3D, MeshInstance3D, GPUParticles3D, LightmapGI, …)
│   ├── physics/      CollisionShape3D, RigidBody3D, CharacterBody3D, Joint3D, Area3D, SoftBody3D, …
│   ├── navigation/   NavigationAgent3D, NavigationRegion3D, NavigationLink3D, NavigationObstacle3D
│   └── xr/           XROrigin3D, XRCamera3D, XRController3D, XRAnchor3D
├── animation/    AnimationPlayer, AnimationTree, AnimationMixer, AnimationStateMachine, Tween
├── audio/        AudioStreamPlayer (the 2D/3D variants live in 2d/, 3d/)
├── debugger/     SceneDebugger client (drives the editor's running scene tree dock)
├── gui/          Control and the entire UI widget set (Button, Label, TextEdit, Tree, Container, …)
├── resources/    Resource subclasses (Mesh, Texture2D, Material, AudioStream, Theme, PackedScene, …)
└── theme/        DefaultTheme builder (compiles the editor's default theme images)

Node and SceneTree

Node (scene/main/node.cpp, ~130 KB) is the universal in-scene base. Each Node:

• Has a name, a parent, an ordered list of children, and a Node *get_parent()/get_node(NodePath)/find_child API for navigation.
• Receives notifications (NOTIFICATION_READY, NOTIFICATION_ENTER_TREE, NOTIFICATION_PROCESS, NOTIFICATION_PHYSICS_PROCESS, NOTIFICATION_EXIT_TREE, etc.) the engine raises during the frame.
• Can opt into _process(delta) and _physics_process(delta).
• Belongs to zero or more "groups" (add_to_group("enemies")); SceneTree::get_nodes_in_group is how systems find sets of nodes.
• Owns an optional MultiplayerAPI peer authority and an optional script.

SceneTree (scene/main/scene_tree.cpp, ~75 KB) is the active MainLoop. It:

• Owns the root Window (which is also a Viewport).
• Drives per-frame phases: physics → process → idle/animation → render submission.
• Maintains process_groups and paused state (so individual subtrees can pause).
• Exposes change_scene_to_packed(...), reload_current_scene, and friends for scene loading.
• Acts as the MultiplayerAPI host (each subtree can override its peer).

graph TD
    OS[Main::iteration] --> ST[SceneTree::process]
    ST --> Input[propagate input via Viewport::push_input]
    ST --> Physics[physics_process at fixed dt]
    ST --> Process[process at variable dt]
    ST --> Anim[AnimationMixer / Tween updates]
    ST --> FTI[SceneTreeFTI<br/>interpolate transforms]
    ST --> RS[RenderingServer::draw]
    ST --> Defer[MessageQueue::flush deferred calls]

SceneTreeFTI (scene/main/scene_tree_fti.cpp) interpolates Node2D/Node3D transforms between physics ticks so high-refresh-rate displays render smoothly even when physics runs at 60 Hz.

Viewport, Window, CanvasLayer

Viewport (scene/main/viewport.cpp, ~201 KB — the largest .cpp under scene/) is a render surface plus an event router. Its responsibilities:

• Holding a World3D (3D scenarios) and World2D (canvas) instance.
• Routing InputEvents through _unhandled_input, _input, _gui_input, with focus tracking, GUI hover state, drag-and-drop, and tooltip handling.
• Owning post-processing, MSAA settings, screen-space effects, FSR/TAA controls.
• Hosting SubViewport chains for portals, render-to-texture, and the 3D editor's preview viewport.

Window (scene/main/window.cpp, ~135 KB) is a Viewport that maps to an OS window via DisplayServer. The root of any scene tree is a Window; additional Window nodes (for popups, dialogs, child windows) are created and managed via the same path.

CanvasLayer (scene/main/canvas_layer.cpp) decouples a 2D subtree's transform from the camera, which is how HUDs sit fixed on screen while the game world scrolls underneath.

Node hierarchies

graph TD
    Object --> Node
    Node --> CanvasItem
    Node --> Node3D
    Node --> Window
    Node --> Timer
    CanvasItem --> Node2D
    CanvasItem --> Control
    Node2D --> Sprite2D
    Node2D --> Camera2D
    Node2D --> CollisionObject2D
    CollisionObject2D --> Area2D
    CollisionObject2D --> PhysicsBody2D
    Node3D --> Camera3D
    Node3D --> Light3D
    Node3D --> VisualInstance3D
    VisualInstance3D --> MeshInstance3D
    VisualInstance3D --> GPUParticles3D
    Node3D --> CollisionObject3D
    CollisionObject3D --> Area3D
    CollisionObject3D --> PhysicsBody3D
    Control --> Container
    Control --> Label
    Control --> Button
    Control --> TextEdit
    Control --> Tree
    Window --> AcceptDialog
    Window --> FileDialog

The hierarchy is intentionally wide: there are over 200 built-in node types and the inspector + scripting can introspect any of them via ClassDB.

2D vs 3D split

Both worlds share patterns but use parallel APIs.

Concept	2D	3D
Spatial base	Node2D (transform via Transform2D)	Node3D (transform via Transform3D)
Visual base	CanvasItem	VisualInstance3D
Camera	Camera2D	Camera3D
Physics body	PhysicsBody2D (Static, Animatable, Rigid, Character)	PhysicsBody3D (same family + SoftBody3D)
Particles (CPU)	CPUParticles2D	CPUParticles3D
Particles (GPU)	GPUParticles2D	GPUParticles3D
Lights	Light2D	OmniLight3D, SpotLight3D, DirectionalLight3D
Tile-based world	TileMap / TileMapLayer	(none — use MeshInstance3D + GridMap module)
Skeleton	Skeleton2D (bones via Bone2D)	Skeleton3D + BoneAttachment3D + IK modifiers
Navigation	NavigationAgent2D, NavigationRegion2D	3D equivalents in scene/3d/navigation/

scene/3d/ also includes a substantial IK and animation toolkit (spline_ik_3d, two_bone_ik_3d, look_at_modifier_3d, spring_bone_simulator_3d, retarget_modifier_3d) since modern 3D games rely on procedural skeletal animation.

TileMapLayer (scene/2d/tile_map_layer.cpp, ~158 KB) is the largest 2D file. It is the modern multi-layer replacement for the older monolithic TileMap and is what TileSet resources drive.

GUI (Control)

Control (scene/gui/control.cpp, ~182 KB) is the base for every UI widget. Beyond Node it adds:

• A Rect2 layout (anchor + offset, or container-driven sizing).
• Focus management with directional + tab navigation.
• Theme overrides — the widget walks parents to resolve Theme values for fonts, colors, stylebox, and icons.
• Mouse / keyboard / touch event routing, drag-and-drop, and tooltips.

Built on Control:

• Containers that auto-layout children: BoxContainer, GridContainer, FlowContainer, MarginContainer, SplitContainer, TabContainer, ScrollContainer, AspectRatioContainer.
• Buttons and toggles: Button, CheckBox, OptionButton, MenuButton, LinkButton, TextureButton.
• Text widgets: Label, RichTextLabel (289 KB cpp, the largest GUI widget — handles BBCode, inline images, effects), LineEdit, TextEdit (323 KB — the largest .cpp under scene/, the basis of the script editor), CodeEdit (extends TextEdit with code completion, gutters, syntax highlight).
• Lists / trees: ItemList, Tree (~258 KB cpp — the inspector and many editor docks are Trees).
• Color / file dialogs: ColorPicker, FileDialog, AcceptDialog, ConfirmationDialog.
• Visual graph: GraphEdit + GraphNode (used by VisualShader and the editor's Animation State Machine).

Resources

scene/resources/ defines the Resource-derived data types instances reference at runtime:

• Meshes: Mesh, ArrayMesh, ImporterMesh, PrimitiveMesh family (Box, Sphere, Plane, Cylinder, …), MultiMesh, MeshLibrary.
• Textures: Texture2D, Texture3D, TextureLayered, Texture2DArray, CompressedTexture2D, AtlasTexture, GradientTexture, PortableCompressedTexture2D, CurveTexture, NoiseTexture2D (from the noise module).
• Materials: BaseMaterial3D, ORMMaterial3D, ShaderMaterial, CanvasItemMaterial, ParticleProcessMaterial, Sky, Environment, Compositor + CompositorEffect.
• Audio: AudioStream, AudioStreamWAV, AudioStreamPlaylist, AudioStreamPolyphonic, AudioStreamRandomizer, AudioBusLayout, plus effect resources (AudioEffectReverb, AudioEffectChorus, …).
• Animation: Animation, AnimationLibrary, AnimationTree resource forms.
• Tile sets: TileSet, TileSetSource, TileSetAtlasSource, TileSetScenesCollectionSource.
• Theme: Theme, StyleBox family (StyleBoxFlat, StyleBoxTexture, StyleBoxLine).
• Scenes: PackedScene + SceneState (the on-disk representation of .tscn/.scn).
• Shaders: Shader, ShaderInclude, ShaderMaterial.

Animation

scene/animation/ implements the keyframe and graph-based animation systems. AnimationMixer is the new shared base; AnimationPlayer provides timeline playback, while AnimationTree evaluates a state machine / blend tree of AnimationNodes. Tween (scene/animation/tween.cpp) is the procedural interpolation engine used widely by GUI code.

Audio

scene/audio/ contains AudioStreamPlayer (non-positional). Positional variants live in scene/2d/audio_stream_player_2d.cpp and scene/3d/audio_stream_player_3d.cpp and feed into the Audio server via dedicated bus lookups, attenuation curves, and area effects.

How nodes get registered

Every node and resource type registers with ClassDB in register_scene_types.cpp. The function is generated incrementally — adding a new node means including its header, calling GDREGISTER_CLASS(MyNode);, and providing _bind_methods() on the class.

Integration points

• Node lifecycle calls into Servers (rendering, physics, audio, navigation) when nodes enter/exit the tree to register/unregister their RIDs.
• Viewport is the bridge to the Display server and Rendering server.
• MultiplayerAPI integrates the multiplayer module so RPC calls and replication work via signals on Node.
• AnimationMixer reads Resource-shaped Animation data and pushes property changes back through the inspector-aware Object API.

Entry points for modification

• Adding a new node type → drop my_node.h/my_node.cpp in scene/2d, scene/3d, or scene/gui; subclass the appropriate base; register in scene/register_scene_types.cpp.
• Changing the main loop ordering → SceneTree::physics_process, SceneTree::process in scene_tree.cpp. Pay attention to the deferred-call flush placement.
• Layout / GUI themes → Control::add_theme_*_override and the Theme resource flow. The default editor theme is compiled by editor/themes/.
• Multiplayer behaviour on nodes → Node::set_multiplayer_authority + the multiplayer module.