home / skills / besty0728 / unity-skills / scene

scene skill

safe

/unity-skills/skills/scene

This skill helps you manage Unity scenes by creating, loading, saving, and querying scene info to streamline workflow.

npx playbooks add skill besty0728/unity-skills --skill scene

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.0 KB

---
name: unity-scene
description: "Manage Unity scenes - create, load, save, and query scene information."
---

# Unity Scene Skills

Control Unity scenes - the containers that hold all your GameObjects.

## Skills Overview

| Skill | Description |
|-------|-------------|
| `scene_create` | Create a new scene |
| `scene_load` | Load a scene |
| `scene_save` | Save current scene |
| `scene_get_info` | Get scene information |
| `scene_get_hierarchy` | Get hierarchy tree |
| `scene_screenshot` | Capture screenshot |

---

## Skills

### scene_create
Create a new scene.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scenePath` | string | Yes | Path for new scene (e.g., "Assets/Scenes/MyScene.unity") |

### scene_load
Load a scene.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `scenePath` | string | Yes | - | Scene asset path |
| `additive` | bool | No | false | Load additively (keep current scene) |

### scene_save
Save the current scene.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scenePath` | string | No | Save path (null = save current) |

### scene_get_info
Get current scene information.

No parameters.

**Returns**: `{success, name, path, isDirty, rootObjectCount, rootObjects: [name]}`

### scene_get_hierarchy
Get full scene hierarchy tree.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `maxDepth` | int | No | 10 | Maximum hierarchy depth |

**Returns**: `{success, hierarchy: [{name, instanceId, children: [...]}]}`

### scene_screenshot
Capture a screenshot.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `filename` | string | No | "screenshot.png" | Output filename |
| `width` | int | No | 1920 | Image width |
| `height` | int | No | 1080 | Image height |

---

## Example Usage

```python
import unity_skills

# Create a new scene
unity_skills.call_skill("scene_create", scenePath="Assets/Scenes/Level1.unity")

# Load an existing scene
unity_skills.call_skill("scene_load", scenePath="Assets/Scenes/MainMenu.unity")

# Load scene additively (multi-scene)
unity_skills.call_skill("scene_load", scenePath="Assets/Scenes/UI.unity", additive=True)

# Get current scene info
info = unity_skills.call_skill("scene_get_info")
print(f"Scene: {info['name']}, Objects: {info['rootObjectCount']}")

# Get full hierarchy (useful for understanding scene structure)
hierarchy = unity_skills.call_skill("scene_get_hierarchy", maxDepth=5)

# Save scene
unity_skills.call_skill("scene_save")

# Take screenshot
unity_skills.call_skill("scene_screenshot", filename="preview.png", width=1920, height=1080)
```

## Best Practices

1. Always save before loading a new scene
2. Use additive loading for UI overlays
3. Keep scene hierarchy organized with empty parent objects
4. Use `scene_get_info` to verify scene state
5. Screenshots are saved to project root by default

Overview

This skill manages Unity scenes with simple commands to create, load, save, inspect, and capture screenshots. It exposes operations to query scene metadata and traverse the hierarchy so you can automate scene workflows inside the Unity editor. Use it to script scene setup, validation, and visual previews.

How this skill works

The skill issues Unity editor actions to create or open scene assets, save current scene state, and return structured metadata about the active scene. It can enumerate root objects and build a nested hierarchy up to a configurable depth. For visual checks it captures a frame and writes a screenshot file to the project root.

When to use it

Automate scene creation during project setup or CI
Open scenes programmatically for batch processing or conversion
Save or checkpoint the current scene before major changes
Inspect scene metadata to validate build-ready state
Capture screenshots for previews or automated QA reports

Best practices

Always call scene_save before switching scenes to avoid data loss
Use additive loading for overlays, UI, or multi-scene workflows
Limit hierarchy traversal depth when scanning very large scenes to keep performance predictable
Organize GameObjects under empty parents to make hierarchy outputs easier to read
Use scene_get_info to confirm scene cleanliness (isDirty) before automated builds

Example use cases

Create a new level asset and populate it via automation after scene_create
Load multiple scenes additively to assemble a runtime test environment
Run a pre-commit check that uses scene_get_info to ensure no unsaved changes
Extract the hierarchy with scene_get_hierarchy for documentation or migration tooling
Produce an image preview of a scene with scene_screenshot for art or QA review

FAQ

What does scene_get_info return?

It returns a success flag plus name, path, isDirty, rootObjectCount and a list of root object names.

How do I capture a screenshot to a custom filename?

Pass filename plus optional width and height to scene_screenshot; the file is written to the project root by default.

Can I load a scene without unloading the current one?

Yes. Set additive=true when calling scene_load to keep the current scene and load the new one additively.