Scene Organization

A guide for structuring Godot 4.3+ scene trees: when to split, when to compose, and how nodes should communicate.

Related skills: component-system for composition patterns, event-bus for decoupled communication, godot-brainstorming for scene tree planning, 2d-essentials for TileMapLayer and CanvasLayer organization.

---

1. Core Principle

Scenes are building blocks. Each scene encapsulates exactly one concept, a player, an enemy, a health bar, a weapon. A scene should be understandable in isolation, reusable without modification, and replaceable without breaking its neighbors.

One scene = one responsibility. If you struggle to name a scene in two words or fewer, it is probably doing too much.

---

2. Composition Over Inheritance

Player Scene, Composed from Reusable Parts

Player (CharacterBody2D)
├── Sprite2D
├── CollisionShape2D
├── HealthComponent
├── HitboxComponent
├── StateMachine
└── AnimationPlayer

HealthComponent, HitboxComponent, and StateMachine are separate .tscn files instantiated as child scenes. Any entity that needs health, enemy, destructible crate, boss, can include HealthComponent without duplicating logic.

HealthComponent, Full Example

GDScript

# health_component.gd
class_name HealthComponent
extends Node

signal health_changed(old_value: int, new_value: int)
signal died

@export var max_health: int = 100

var current_health: int

func _ready() -> void:
    current_health = max_health

func take_damage(amount: int) -> void:
    if amount <= 0:
        return
    var old_health := current_health
    current_health = max(0, current_health - amount)
    health_changed.emit(old_health, current_health)
    if current_health == 0:
        died.emit()