unity-scene

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

在调用本模块中的任何技能之前：如果你打算根据技能名称或描述猜测参数来调用技能，请停止——先阅读本文档（或通过
GET /skills/recommend?includeSchema=true
获取其 schema）。如果你已经从推荐/schema中获取了参数定义，可以直接进行dryRun。

Triggers

触发场景

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

打开或保存场景
叠加加载场景
切换活动场景
查询场景内容
打开或保存场景、叠加加载、切换活动场景、查询场景内容

Unity Scene Skills

Unity场景技能

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

控制Unity场景——承载所有GameObject的容器。

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

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高危技能：
```
scene_create
```
/
```
scene_load
```
/
```
scene_save
```
（标记
```
RiskLevel="high"
```
，因为切换/覆盖整个场景文件影响范围极大）。这些技能在Approval/Auto模式下返回
```
MODE_FORBIDDEN
```
，仅在Bypass或Allowlist命中时可调用。

请勿执行以下操作（常见错误幻觉）：

```
scene_delete
```
/
```
scene_rename
```
不存在→请通过
```
asset_delete
```
删除场景文件，通过
```
asset_move
```
重命名
```
scene_list
```
不存在→请使用
```
scene_get_loaded
```
（已加载场景）或带
```
t:Scene
```
参数的
```
asset_find
```
（所有场景资源）
```
scene_find_objects
```
是简单的名称/标签/组件过滤器；如需正则表达式/层/路径搜索，请使用
```
gameobject_find
```
（SkillMode.SemiAuto，只读模式，任何模式下均可直接调用）

路由说明:

如需详细层级树→使用
```
perception
```
模块的
```
hierarchy_describe
```
如需场景统计→使用
```
perception
```
模块的
```
scene_summarize
```
如需截图→本模块的
```
scene_screenshot
```
捕获Game View的最终合成图像（所有相机+UI；在Play模式下为实时运行帧）；
```
camera_screenshot
```
（camera模块，SkillMode.FullAuto）渲染单个游戏相机的离线画面

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

技能	描述
`scene_create`	创建新场景
`scene_load`	加载场景
`scene_save`	保存当前场景
`scene_get_info`	获取场景信息
`scene_get_hierarchy`	获取层级树
`scene_screenshot`	捕获屏幕截图
`scene_get_loaded`	获取所有已加载场景
`scene_unload`	卸载叠加场景
`scene_set_active`	设置活动场景
`scene_find_objects`	按名称/标签/组件搜索对象

Skills

技能详情

scene_create

Create a new scene.

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

创建新场景。

参数	类型	必填	描述
`scenePath`	string	是	新场景的路径（例如："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)

加载场景。

参数	类型	必填	默认值	描述
`scenePath`	string	是	-	场景资源路径
`additive`	bool	否	false	叠加加载（保留当前场景）

scene_save

Save the current scene.

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

保存当前场景。

参数	类型	必填	描述
`scenePath`	string	否	保存路径（null表示保存当前场景）

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.

获取当前场景信息。

无参数。

返回结果:

{sceneName, scenePath, isDirty, rootObjectCount, rootObjects: [{name, entityId, instanceId, childCount}]}

—— 根条目包含

childCount

，因此你可以在调用层级接口前判断哪些根节点值得展开。

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, entityId, instanceId, components: [type, ...], childCount, children}

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

`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.

获取场景层级树，支持深度限制。

参数	类型	必填	默认值	描述
`maxDepth`	int	否	3	展开的最大层级深度

返回结果:

{sceneName, hierarchy: [node, ...]}

，其中每个节点为

{name, entityId, instanceId, components: [type, ...], childCount, children}

。

childCount
vs
children
—— 如何区分叶子节点与截断节点。
childCount
始终是节点的实际子节点数量，与
maxDepth
无关；当达到深度限制时，
children
为
null
。因此：
childCount
children
含义
0
null
真正的叶子节点——下方无任何内容。
> 0
null
被
maxDepth
截断——存在未展示的子节点。
> 0
数组
此层级已完全展开。
请勿将
children: null
视为“空”。当你看到
childCount > 0
且
children: null
，同时需要查看下方内容时，请使用更大的
maxDepth
重新调用——默认值仅为3，因此深层级结构默认会被截断——或直接查询该子树（
gameobject_find
、
perception
模块中的
hierarchy_describe
）。

`childCount`	`children`	含义
`0`	`null`	真正的叶子节点——下方无任何内容。
`> 0`	`null`	被 `maxDepth` 截断——存在未展示的子节点。
`> 0`	数组	此层级已完全展开。

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.

捕获Game View的屏幕截图——所有相机+UI的最终合成帧。在Play模式下为实时运行画面，而非Scene/编辑器视图。如需单个游戏相机的渲染画面，请使用

camera_screenshot

。

参数	类型	必填	默认值	描述
`filename`	string	否	"screenshot.png"	仅文件名（无路径分隔符）；保存至 `Assets/Screenshots/` 目录下
`width`	int	否	1920	图像宽度
`height`	int	否	1080	图像高度
`returnImage`	bool	否	false	在响应中同时返回Base64格式的PNG图片（ `imageBase64` ），适用于无文件系统访问权限的客户端
`maxDimension`	int	否	1280	仅在 `returnImage=true` 时使用；缩放返回的图像（不影响保存的文件），使其长边≤该值。取值范围为256–4096

返回结果:

{success, path, width, height, isPlaying, note}

。

isPlaying

表示帧是实时运行画面（Play模式）还是静态编辑模式画面。当

returnImage=true

时，会额外返回

{imageBase64, imageWidth, imageHeight, imageBytes}

。如果Base64负载超过8MB，技能会返回错误，要求设置更小的

maxDimension

——但

path

对应的文件仍会保存。

异步说明:

ScreenCapture.CaptureScreenshot

会在约1帧后写入PNG文件。如果立即读取

path

失败，请等待约200ms后重试。

returnImage

不会读取该文件——因为文件尚未写入——而是同步捕获Game View当前的后台缓冲区（

ScreenCapture.CaptureScreenshotAsTexture

），因此返回的图像可能比最终写入

path

的文件早一帧。

returnImage使用提示: 可读取文件的本地Agent（例如针对本地Unity Editor的Claude Code）通常应省略

returnImage

，待文件写入后直接读取

path

下的PNG文件——这样更节省Token。

returnImage=true

适用于无法访问Unity项目文件系统的远程/MCP客户端。

scene_get_loaded

Get list of all currently loaded scenes.

No parameters.

Returns:

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

获取所有当前已加载场景的列表。

无参数。

返回结果:

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

scene_unload

Unload a loaded scene (additive).

Parameter	Type	Required	Description
`sceneName`	string	Yes	Scene name to unload

卸载已加载的叠加场景。

参数	类型	必填	描述
`sceneName`	string	是	要卸载的场景名称

scene_set_active

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

Parameter	Type	Required	Description
`sceneName`	string	Yes	Scene name to set active

设置活动场景（用于多场景编辑）。

参数	类型	必填	描述
`sceneName`	string	是	要设置为活动状态的场景名称

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}]}

按名称模式、标签或组件类型搜索GameObject。如需高级搜索（正则表达式、层、路径），请使用gameobject_find。

参数	类型	必填	默认值	描述
`namePattern`	string	否	-	要匹配的名称子串（不区分大小写）
`tag`	string	否	-	按标签过滤
`componentType`	string	否	-	按组件类型名称过滤
`limit`	int	否	50	返回的最大结果数

返回结果:

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

Example Usage

使用示例

python

import unity_skills

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']}")

info = unity_skills.call_skill("scene_get_info") print(f"场景: {info['name']}, 对象数量: {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)

undefined

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

undefined

Best Practices

最佳实践

Always save before loading a new scene
Use additive loading for UI overlays
Keep scene hierarchy organized with empty parent objects
Use
```
scene_get_info
```
to verify scene state
Screenshots are saved under
```
Assets/Screenshots/
```
(filename is a bare name; any path separators are stripped)

加载新场景前务必保存当前场景
对UI叠加层使用叠加加载模式
使用空父对象保持场景层级结构有序
使用
```
scene_get_info
```
验证场景状态
截图保存于
```
Assets/Screenshots/
```
目录下（文件名仅为纯名称；任何路径分隔符都会被去除）

Exact Signatures

精确签名

Exact names, parameters, defaults, and returns are defined by

GET /skills/schema

unity_skills.get_skill_schema()

, not by this file.

精确的名称、参数、默认值和返回值由

GET /skills/schema

或

unity_skills.get_skill_schema()

定义，而非本文档。

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

完整的传输层错误代码（COMPILING/RATE_LIMIT等）→ ../../references/protocol-error-codes.md

错误	触发原因	修复方案
`TARGET_NOT_FOUND`	请求的场景未找到或当前未加载（例如： `Scene not found` 、 `Scene is not loaded` ）	使用 `asset_find` 验证场景路径，或使用 `scene_get_loaded` 列出已加载场景，然后重试。
`MISSING_PARAM`	缺少必填参数，例如 `scene_create` 的 `scenePath` ，或当前场景无保存路径	提供 `scenePath` ，或在操作前先保存场景一次。
`SEMANTIC_INVALID`	向 `scene_find_objects` 传入了无效的标签或组件类型	使用有效的标签或组件类型名称，如需更复杂的过滤器可考虑 `gameobject_find` 。
`SKILL_ERROR`	状态约束阻止了操作，例如尝试卸载唯一已加载的场景	调整请求至有效的编辑器状态（例如至少保留一个已加载场景）。