unity-scene

**调用本模块中的任何技能前：**如果你准备根据技能名称或描述猜测参数来调用技能，请先停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获取参数定义，则可直接进行 dryRun。

触发条件

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

Unity 场景技能

控制 Unity 场景——场景是容纳所有 GameObject 的容器。

运行模式

• 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（已加载的场景），或使用 asset_find 和 t:Scene（所有场景资源）
• scene_find_objects 是简单的名称/标签/组件筛选器；若要进行正则表达式/图层/路径搜索，请使用 gameobject_find（SkillMode.SemiAuto，只读，任何模式下都可直接调用）

路由：

• 如需详细的层级树 → 使用 perception 模块的 hierarchy_describe
• 如需场景统计信息 → 使用 perception 模块的 scene_summarize
• 如需截图 → scene_screenshot（本模块）捕获 Game View 的最终合成图像（所有摄像机 + UI；在 Play 模式下，这是实时运行帧）；camera_screenshot（camera 模块，SkillMode.FullAuto）则在屏幕外渲染单个 Game Camera

技能概览

技能	描述
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	按名称/标签/组件搜索对象

---

技能

scene_create

创建新场景。

参数	类型	必填	描述
scenePath	string	是	新场景的路径（例如："Assets/Scenes/MyScene.unity"）

scene_load

加载场景。

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

scene_save

保存当前场景。

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

scene_get_info

获取当前场景信息。

无参数。

返回值：{sceneName, scenePath, isDirty, rootObjectCount, rootObjects: [{name, entityId, instanceId, childCount}]} — 根对象条目包含 childCount，因此在调用层级查询前，你可以判断哪些根对象值得进一步展开。

scene_get_hierarchy

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

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

返回值：{sceneName, hierarchy: [node, ...]}，其中每个节点为 {name, scene, entityId, instanceId, components: [type, ...], childCount, children}。scene 是该节点所属场景的名称。

DontDestroyOnLoad：在 Play 模式下，DontDestroyOnLoad 伪场景的根节点会追加到活动场景节点之后，并标记为 scene: "DontDestroyOnLoad"。当该伪场景中有根节点时，scene_get_loaded 也会将其列为 {name: "DontDestroyOnLoad", isPseudoScene: true}。与其他对象一样，可以通过 gameobject_find 找到这些对象；但无法卸载或激活该场景本身。

childCount 与 children：如何区分叶节点和被截断的节点。 无论 maxDepth 如何设置，childCount 始终是节点的实际子节点数；达到深度限制后，children 则为 null。因此：

childCount	children	含义
0	null	真正的叶节点——没有子节点。
> 0	null	被 maxDepth 截断——还有未显示的子节点。
> 0	数组	此层级已完整展开。

切勿将 children: null 理解为“空”。如果看到 childCount > 0 且 children: null，并且需要查看其下级内容，请使用更大的 maxDepth 再次调用——默认值只有 3，因此默认情况下深层层级会被截断——或者直接查询该子树（使用 perception 模块中的 gameobject_find、hierarchy_describe）。

scene_screenshot

截取 Game View 的屏幕截图——由所有摄像机和 UI 合成的最终画面。在 Play 模式下，这是实时运行画面，而非 Scene/编辑器视图。若要截取单个 Game Camera 的渲染画面，请改用 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 模式）还是静态的 Edit 模式画面。当 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，并在 PNG 写入后直接读取 path 中的文件——这样更省 token。对于无法访问 Unity 项目文件系统的远程/MCP 客户端，请使用 returnImage=true。

scene_get_loaded

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

无参数。

返回值：{success, count, scenes: [{name, path, isLoaded, isDirty, isActive, rootCount, isPseudoScene}]}。在运行模式下，如果 DontDestroyOnLoad 伪场景中有根对象，则会将其追加到列表中（isPseudoScene:true，path 为空）。

scene_unload

卸载已加载的场景（附加加载）。

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

scene_set_active

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

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

scene_find_objects

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

参数	类型	必填	默认值	描述
namePattern	string	否	-	要匹配的名称子字符串（不区分大小写）
tag	string	否	-	按标签筛选；未在 Tags & Layers 中定义的标签会被拒绝
componentType	string	否	-	按组件类型名称筛选；未知类型会被拒绝
limit	int	否	50	返回结果的最大数量

返回值：{success, count, objects: [{name, path, instanceId, active, tag}]}

---

使用示例

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)

最佳实践

1. 加载新场景前务必先保存
2. 为 UI 覆盖层使用附加加载
3. 使用空父对象保持场景层级结构清晰
4. 使用 scene_get_info 验证场景状态
5. 截图保存在 Assets/Screenshots/ 下（文件名不带路径；所有路径分隔符都会被移除）

精确签名

确切的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非此文件。

常见错误

完整的传输层错误代码（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	状态限制阻止了操作，例如尝试卸载唯一已加载的场景。	将请求调整为有效的编辑器状态（例如，至少保留一个已加载的场景）。