scene-composition

Scene Composition for Summer Engine

Organize scenes for clarity, reuse, and MCP compatibility. Follow these conventions when building levels, characters, and UI.

Node Hierarchy Conventions

3D Scenes

World (Node3D)                    # Root or main container
├── Camera3D                      # Main camera
├── DirectionalLight3D            # Sun / primary light
├── WorldEnvironment              # Sky, ambient, fog
├── Level (Node3D)                # Level geometry
│   ├── Ground
│   ├── Walls
│   └── Platforms
├── Props (Node3D)                # Placed objects (trees, crates)
├── Enemies (Node3D)              # Enemy instances
└── Player                        # Player instance (or instantiated)

2D Scenes

Level (Node2D)
├── TileMapLayer                  # Or TileMap
├── Characters
├── Props
└── Effects

UI Scenes

CanvasLayer or Control
├── MarginContainer
│   ├── VBoxContainer
│   │   ├── Label
│   │   ├── Button
│   │   └── Button

Parent Paths for MCP

Use ./ for paths relative to the scene root:

Path	Meaning
./	Scene root
./World	Child named "World" of root
./World/Player	Player under World
./World/Props/Tree1	Tree1 under Props under World

Never use /World (absolute) or World (missing ./). The engine expects ./ prefix.

When to Use Sub-Scenes

Use sub-scenes (separate .tscn files) when:

• The same setup appears in multiple places (player, enemy, pickup)
• The setup has many nodes and would clutter the main scene
• You want to edit a prefab in isolation

Use inline nodes when:

• The node is unique to this scene (main camera, level-specific light)
• It's a simple one-off (single MeshInstance3D)

Creating a Sub-Scene

1. Build the hierarchy in the main scene
2. Select the root of what you want to extract
3. Save as scene: summer_save_scene(scenePath="res://scenes/source.tscn", path="res://scenes/player.tscn"). scenePath names the scene being saved and is required; path is the optional save-as target. There is no "current scene" default.
4. In the main scene, add it with summer_instantiate_scene(scenePath="res://main.tscn", parent="./World", scene="res://scenes/player.tscn", name="Player")