# Scene Composition

> Use when building or organizing scenes in Godot — node hierarchy conventions, when to extract sub-scenes, reusable prefab patterns, instance vs add-node decisions. Trigger on "scene", "sub-scene", "instance", "prefab", "node hierarchy", "scene structure", "PackedScene".

- **Type:** Skill
- **Install:** `agentstack add skill-summerengine-summer-engine-agent-scene-composition`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SummerEngine](https://agentstack.voostack.com/s/summerengine)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SummerEngine](https://github.com/SummerEngine)
- **Source:** https://github.com/SummerEngine/summer-engine-agent/tree/main/skills/scene-and-project/scene-composition
- **Website:** https://summerengine.com/

## Install

```sh
agentstack add skill-summerengine-summer-engine-agent-scene-composition
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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(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 `summer_instantiate_scene(parent="./World", scene="res://scenes/player.tscn", name="Player")`

**Practical approach:** Create reusable scenes (player.tscn, enemy.tscn) as separate scene files, then instantiate them into levels.

## InstantiateScene vs AddNode

| Use | Tool | Example |
|-----|------|---------|
| Built-in mesh (Box, Sphere) | AddNode + SetProp | `summer_add_node` type=MeshInstance3D, then `summer_set_prop` mesh=BoxMesh |
| Existing .tscn prefab | InstantiateScene | `summer_instantiate_scene` scene=res://player.tscn |
| Imported .glb model | ImportFromUrl then InstantiateScene | Import first, then instantiate |

**Do not** use `summer_set_prop` with `mesh` for a .glb path. Use `summer_instantiate_scene` for .tscn and .glb files.

## Save Conventions

- Always call `summer_save_scene` after changes you want to keep
- For new scenes: `summer_save_scene(path="res://scenes/level1.tscn")`
- For existing scenes: `summer_save_scene` (no path, uses current scene path)

## Common Mistakes

1. **Wrong parent path:** `./NonExistent` fails. Ensure the parent exists before adding children.
2. **Unnamed scene:** Saving without a path fails if the scene was never saved. Use `path` for new scenes.
3. **Duplicate names:** Godot auto-renames (Node, Node2, etc.). Use descriptive unique names.
4. **Mixing 2D and 3D:** Don't put Node2D under Node3D or vice versa in the same hierarchy.

## Fallback

No fallback for this — Summer MCP required. Handwriting `.tscn` files for hierarchy mutations is error-prone (UID collisions, wrong format version, broken sub_resource refs). If MCP isn't connected, open the scene in the Godot editor and use the SceneTree dock.

## Trap — Cross-scene transform leak when copying a scene as a template

When you duplicate a scene to spawn a sibling level (for example, `level_1.tscn` → `level_2.tscn`), every child instance carries its transform offset baked at the original level's coordinate system. If the source level places its player at world `(223, 108, -1833)` and instances a kill-volume scene at offset `(512, -3, 512)`, those numbers are anchored to the source level's terrain origin. Drop the same kill-volume instance into a level whose player spawns at world `(0, 1, 0)` and the volume's wall colliders may end up slicing the new arena at world `x = 0`. The user sees a "glitching invisible line through the middle of the map" they can't pass through. The colliders are invisible under the floor, so visual diagnosis is hard. Only collision-walking through them reveals the problem.

Rule when copying a scene as a template:

1. Audit every child instance for hardcoded `transform = Transform3D(...)` lines.
2. Decide for each: keep, re-zero (origin = `(0,0,0)`), or drop entirely.
3. The bigger the original level's world-space coordinates, the more dangerous the copy. Re-zero by default; you can move things back if needed.
4. Levels that spawn the player at world origin (for example flat arenas centered on `(0,0,0)`) should drop ALL transform overrides from carry-over instances. Only re-add transforms relative to the new origin.

## Trap — Third-person camera collision when foliage shouldn't block

Godot's `SpringArm3D` shortens the camera boom when it raycasts into geometry on the configured `collision_mask`. If your trees, bushes, or grass have collision so the player physically bumps them, on the same layer the SpringArm queries, the camera shortens for foliage too. Players see the camera awkwardly snap forward whenever they walk near a tree.

The pattern that works:

1. Foliage gets its own physics layer. Conventionally layer 9 ("Foliage").
   - Foliage `StaticBody3D`: `collision_layer = 256` (which is 2^8, layer 9).
2. Player still bumps into foliage by including that layer in its `collision_mask`.
   - Player `CharacterBody3D`: `collision_mask = 259` (which is 1 + 2 + 256, Entities + Level + Foliage).
3. SpringArm uses a mask that catches solid level geometry but excludes foliage.
   - SpringArm: `collision_mask = 3` (which is 1 + 2, Entities + Level only).
4. For the visual fade the user expects when the camera is "behind" a tree, add the foliage mesh to the `camera_fade` group. An existing camera-occlusion fade system can ghost the mesh by AABB intersection with the camera-to-player segment without touching collision.

Why per-layer split: there's no clean way to exclude a single body type from `SpringArm3D`'s collision check via `add_excluded_object` for dynamically-spawned foliage. You'd have to register every tree at spawn time and re-register on level change. Layer-level filtering is set-and-forget.

Don't skip the player mask update. If you only move foliage to layer 9 without adding it to the player's mask, the player walks straight through trees.

## Collaborative protocol

This skill creates and mutates scene files. Always ask before applying: "May I create `res://scenes/player.tscn` and instantiate it under `./World`?". See `../../references/collaborative-protocol.md`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SummerEngine](https://github.com/SummerEngine)
- **Source:** [SummerEngine/summer-engine-agent](https://github.com/SummerEngine/summer-engine-agent)
- **License:** MIT
- **Homepage:** https://summerengine.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-summerengine-summer-engine-agent-scene-composition
- Seller: https://agentstack.voostack.com/s/summerengine
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.