/scene

name: unity-scene
description: Manage Unity scenes. 管理 Unity 场景。

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.FullAuto)

**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**: `{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 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 adv