scene-composition

Scene Composition for Onyx 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: onyx_save_scene(path="res://scenes/player.tscn"). SaveScene saves the current open scene, so build reusable scenes in their own open scene and save them there. Do not handwrite .tscn files as the preferred path.
4. In the main scene, add it with onyx_instantiate_scene(parent="./World", scene="res://scenes/player.tscn", name="Player")