unity-scene

> Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Opening or saving scenes
• Loading additively
• Switching active scene
• Querying scene contents
• 打开或保存场景、叠加加载、切换活动场景、查询场景内容

Unity Scene Skills

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

Operating Mode

• Approval：本模块 Mixed —— scene_get_info / scene_get_hierarchy / scene_get_loaded / scene_find_objects 标 SkillMode.SemiAuto，可直接执行；scene_screenshot / scene_unload / scene_set_active 未设 Mode 字段（默认 FullAuto），Approval 模式下需 grant。
• Auto / Bypass：FullAuto 直接执行。
• 含 NeverInSemi 高危 skill：scene_create / scene_load / scene_save（标 RiskLevel="high"，因为切换/覆盖整个场景文件影响范围极大）。这些在 Approval/Auto 下返 MODE_FORBIDDEN，仅 Bypass 或 Allowlist 命中可调。

DO NOT (common hallucinations):

• scene_delete / scene_rename do not exist → delete scene files via asset_delete, rename via asset_move
• scene_list does not exist → use scene_get_loaded (loaded scenes) or asset_find with t:Scene (all scene assets)
• scene_find_objects is a simple name/tag/component filter; for regex/layer/path search use gameobject_find (SkillMode.SemiAuto, 只读，任何模式可直接调用)

Routing:

• For detailed hierarchy tree → use perception module's hierarchy_describe
• For scene statistics → use perception module's scene_summarize
• For screenshot → scene_screenshot (this module) captures the Game View final composited image (all cameras + UI; in Play mode this is the live runtime frame); camera_screenshot (camera module, SkillMode.FullAuto) renders a single Game Camera off-screen

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 |

| scene_get_loaded | Get all loaded scenes |

| scene_unload | Unload an additive scene |

| scene_set_active | Set active scene |

| scene_find_objects | Search objects by name/tag/component |

---

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: {sceneName, scenePath, isDirty, rootObjectCount, rootObjects: [{name, entityId, instanceId, childCount}]} — root entries carry childCount, so you can tell which roots are worth descending into before paying for a hierarchy call.

scene_get_hierarchy

Get the scene hierarchy tree, depth-limited.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| maxDepth | int | No | 3 | Maximum hierarchy depth to expand |

Returns: {sceneName, hierarchy: [node, ...]} where each node is {name, scene, entityId, instanceId, components: [type, ...], childCount, children}. scene is the node's owning scene name.

> DontDestroyOnLoad: in Play mode, roots of the DontDestroyOnLoad pseudo-scene are appended after the active-scene nodes, marked with scene: "DontDestroyOnLoad". scene_get_loaded also lists it as {name: "DontDestroyOnLoad", isPseudoScene: true} when it has roots. These objects are found by gameobject_find like any other; the scene itself cannot be unloaded or activated.

> childCount vs children — how to tell a leaf from a truncation. childCount is always the node's real number of children, independent of maxDepth; children is null once the depth limit is reached. So:

>

> | childCount | children | Meaning |

> |---|---|---|

> | 0 | null | Genuine leaf — nothing below it. |

> | > 0 | null | Clipped by maxDepth — there are children you have not been shown. |

> | > 0 | array | Fully expanded at this level. |

>

> Never read children: null as "empty". When you see childCount > 0 with children: null and you need what is below it, re-call with a larger maxDepth — the default is only 3, so deep hierarchies are truncated by default — or query that subtree directly (gameobject_find, hierarchy_describe in the perception module).

scene_screenshot

Capture a screenshot of the Game View — the final composited frame of all cameras + UI. In Play mode this is the live runtime image, not the Scene/editor view. For a single Game Camera's render use camera_screenshot instead.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| filename | string | No | "screenshot.png" | Bare filename only (no path separators); saved under Assets/Screenshots/ |

| width | int | No | 1920 | Image width |

| height | int | No | 1080 | Image height |

| returnImage | bool | No | false | Also return a PNG as base64 in the response (imageBase64), for clients without filesystem access |

| maxDimension | int | No | 1280 | Only used when returnImage=true; downscales the returned image (not the saved file) so its longer edge is ≤ this value. Clamped to 256–4096 |

Returns: {success, path, width, height, isPlaying, note}. isPlaying indicates whether the frame is a live runtime image (Play mode) or a static Edit-mode frame. Adds {imageBase64, imageWidth, imageHeight, imageBytes} when returnImage=true. If the base64 payload would exceed 8MB, the skill returns an error asking for a smaller maxDimension — the file at path is still saved.

Async: ScreenCapture.CaptureScreenshot writes the PNG ~1 frame later. If reading path immediately fails, wait ~200ms and retry. returnImage does not read that file back — since it isn't written yet — it instead does a separate synchronous capture of the Game View's current backbuffer (ScreenCapture.CaptureScreenshotAsTexture), so the returned image may be a moment older than the file eventually written to path.

returnImage usage tip: a local agent that can read files (e.g. Claude Code against a local Unity Editor) should generally omit returnImage and just read the PNG at path once it's written — it's cheaper on tokens. Use returnImage=true for remote/MCP clients that have no filesystem access to the Unity project.

scene_get_loaded

Get list of all currently loaded scenes.

No parameters.

Returns: {success, scenes: [{name, path, isActive, isDirty}]}

scene_unload

Unload a loaded scene (additive).

| Parameter | Type | Required | Description |

|-----------|------|----------|-------------|

| sceneName | string | Yes | Scene name to unload |

scene_set_active

Set the active scene (for multi-scene editing).

| Parameter | Type | Required | Description |

|-----------|------|----------|-------------|

| sceneName | string | Yes | Scene name to set active |

scene_find_objects

Search GameObjects by name pattern, tag, or component type. For advanced search (regex, layer, path) use gameobject_find.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| namePattern | string | No | - | Name substring to match (case-insensitive) |

| tag | string | No | - | Filter by tag |

| componentType | string | No | - | Filter by component type name |

| limit | int | No | 50 | Max results to return |

Returns: {success, count, objects: [{name, path, instanceId, active, tag}]}

---

Example Usage

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 under Assets/Screenshots/ (filename is a bare name; any path separators are stripped)

Exact Signatures

Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.

Common Errors

Full transport-level codes (COMPILING/RATE_LIMIT etc.) → ../../references/protocol-error-codes.md

| Error | Trigger | Fix |

|---|---|---|

| TARGET_NOT_FOUND | The requested scene is not found or not currently loaded (e.g., Scene not found, Scene is not loaded). | Verify the scene path with asset_find or list loaded scenes with scene_get_loaded, then retry. |

| MISSING_PARAM | A required parameter is missing, such as scenePath for scene_create, or the current scene has no save path. | Provide scenePath or save the scene once before the operation. |

| SEMANTIC_INVALID | An invalid tag or component type was passed to scene_find_objects. | Use a valid tag or component type name, and consider gameobject_find for more complex filters. |

| SKILL_ERROR | A state constraint blocked the operation, such as attempting to unload the only loaded scene. | Adjust the request to a valid editor state (e.g., keep at least one scene loaded). |