/scene

name: unity-scene
description: Manage Unity scenes

> **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 ed