unity-camera

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

触发条件

• 取景 Scene View
• 创建或调整相机
• 调整 FOV 或裁剪面
• 取景 Scene View、创建或调整相机、修改 FOV 或裁剪面

相机技能

控制 Scene View 相机和游戏相机（创建、变换、属性、截图、剔除、正交模式切换）。

运行模式

• Approval（默认）：修改型技能（camera_set_transform、camera_create、camera_set_properties、camera_set_culling_mask、camera_screenshot、camera_sceneview_screenshot、camera_set_orthographic、camera_align_view_to_object、camera_look_at）需要用户授权；授权后会触发一次服务器端执行并返回结果。
• Auto / Bypass：这些技能会直接执行。
• 查询技能（camera_get_info、camera_get_properties、camera_list）属于 SkillMode.SemiAuto——在三种模式下都无需授权即可运行。
• 此模块不包含任何 Delete / PlayMode / Reload / 高风险技能（没有 NeverInSemi）。

防护规则

请勿（常见幻觉）：

• 不存在 camera_move / camera_rotate → 使用 camera_set_transform（Scene View）或 gameobject_set_transform（游戏相机）
• 不存在 camera_set_fov → 使用带有 fieldOfView 参数的 camera_set_properties
• camera_* 技能控制两种不同的相机：camera_set_transform / camera_look_at / camera_align_view_to_object 控制 Scene View 相机；camera_create / camera_set_properties / camera_screenshot 控制游戏相机
• 不存在 camera_delete → 对相机 GameObject 使用 gameobject_delete

路由：

• 对于 Cinemachine 虚拟相机 → 使用 cinemachine 模块
• 对于游戏相机组件属性 → 使用 camera_set_properties / camera_get_properties（此模块）
• 对于截图 → 有三种选择：scene_screenshot（scene 模块）= Game View 的最终合成画面（包含所有相机和 UI；Play 模式下为实时运行帧）；camera_screenshot（此模块）= 单个游戏相机的离屏渲染；camera_sceneview_screenshot（此模块）= 编辑器 Scene View（开发者视口，包含网格和 Gizmo）

技能

camera_align_view_to_object

将 Scene View 相机对齐到某个对象。 参数：

• name（string，可选）：目标 GameObject 名称。
• instanceId（int，可选）：目标 GameObject 实例 ID。
• path（string，可选）：目标 GameObject 层级路径。

camera_get_info

获取编辑器 Scene View 视口相机的位置和旋转——即开发者的视口相机，不是场景中的 Camera 组件。正因如此，此技能不接受任何目标参数。要获取游戏相机的状态，请使用 camera_get_properties（或使用 camera_list 查找相机）；如果你刚通过 camera_create 创建了相机并想确认其变换，camera_get_info 不会显示该相机。 **参数：**无。

camera_set_transform

通过枢轴点（取景的世界坐标点，而非观察点位置）、旋转和大小设置 Scene View 相机。 参数：

• posX、posY、posZ（float）：枢轴点——取景的世界坐标点，而非观察点位置。
• rotX、rotY、rotZ（float）：旋转（欧拉角）。
• size（float，可选）：Scene View 大小（缩放）（默认值为 5）。
• instant（bool，可选）：true：立即应用并读取结果；false：以动画方式应用（默认值为 true）。

返回：{ success, message, pivot, rotation, size, orthographic }；当 instant=true 时还包含 cameraPosition（观察点位置），当 instant=false 时还包含 animating: true。

camera_look_at

将 Scene View 相机聚焦到世界空间中的一个点。立即生效。 参数：

• x、y、z（float）：目标点。
• 不支持 targetName 或 GameObject 查找。若要聚焦对象，请使用 camera_align_view_to_object。

返回： { success, pivot, rotation, size }。

camera_create

创建一个新的 Game Camera。

参数	类型	必填	默认值	描述
name	string	否	"New Camera"	新相机 GameObject 的名称
x	float	否	0	位置 X
y	float	否	1	位置 Y
z	float	否	-10	位置 Z
addAudioListener	bool	否	false	同时附加一个 AudioListener 组件

返回： { success, name, instanceId }

camera_get_properties

获取 Game Camera 的属性（支持 name/instanceId/path）。

参数	类型	必填	默认值	描述
name	string	否	null	相机 GameObject 的名称
instanceId	int	否	0	相机 GameObject 的实例 ID
path	string	否	null	相机 GameObject 的层级路径

返回： { success, name, fieldOfView, nearClipPlane, farClipPlane, orthographic, orthographicSize, depth, cullingMask, clearFlags, backgroundColor, rect }

camera_set_properties

设置 Game Camera 的属性（视野、裁剪面、清除标志、背景颜色、深度）。

参数	类型	必填	默认值	描述
name	string	否	null	相机 GameObject 的名称
instanceId	int	否	0	相机 GameObject 的实例 ID
path	string	否	null	相机 GameObject 的层级路径
fieldOfView	float?	否	null	相机视野
nearClipPlane	float?	否	null	近裁剪面距离
farClipPlane	float?	否	null	远裁剪面距离
depth	float?	否	null	相机渲染深度
clearFlags	string	否	null	清除标志：Skybox、Color、SolidColor、Depth、Nothing。Color 和 SolidColor 是同一个底层 CameraClearFlags 值的两种名称，因此两者都可接受，响应始终会将其回显为 Color——不要因此认为写入被忽略了
bgR	float?	否	null	背景颜色的红色分量（0-1）
bgG	float?	否	null	背景颜色的绿色分量（0-1）
bgB	float?	否	null	背景颜色的蓝色分量（0-1）
bgA	float?	否	null	背景颜色的 alpha 值（0-1）

省略的任何 bg* 通道都会保留相机的当前值，因此你可以只设置 alpha 值。

返回： { success, name, applied, fieldOfView, nearClipPlane, farClipPlane, orthographic, orthographicSize, depth, cullingMask, clearFlags, backgroundColor, rect }——响应会回显写入后的相机状态，applied 列出实际更改的参数，名称与传入的完全一致（背景通道会分别显示为 bgR、bgG、bgB、bgA，而不会合并到 backgroundColor 下），因此，未出现在 applied 中的参数表示未提供。该回显就是验证结果：无需再次调用 camera_get_properties。如果 clearFlags 无法解析，则会在应用任何内容之前以 SEMANTIC_INVALID 和 validValues 拒绝整个调用，因此同一调用中的数值参数不会只写入一部分。

camera_set_culling_mask

按图层名称（逗号分隔）设置游戏摄像机的剔除蒙版。

参数	类型	必需	默认值	描述
layerNames	string	是	-	逗号分隔的图层名称
name	string	否	null	摄像机 GameObject 的名称
instanceId	int	否	0	摄像机 GameObject 的实例 ID
path	string	否	null	摄像机 GameObject 的层级路径

返回： { success, cullingMask, layers } — layers 列出结果蒙版包含的图层名称。

camera_screenshot

将游戏摄像机的截图保存到文件。

参数	类型	必需	默认值	描述
savePath	string	否	"Assets/screenshot.png"	保存截图的文件路径
width	int	否	1920	截图宽度（像素）
height	int	否	1080	截图高度（像素）
name	string	否	null	摄像机 GameObject 的名称
instanceId	int	否	0	摄像机 GameObject 的实例 ID
path	string	否	null	摄像机 GameObject 的层级路径
returnImage	bool	否	false	同时在响应中以 base64 格式返回 PNG（imageBase64），供无法访问文件系统的客户端使用
maxDimension	int	否	1280	仅在 returnImage=true 时使用；缩小返回图像（不影响保存的文件），使其较长边 ≤ 此值。限制在 256–4096 之间

返回： { success, path, width, height }；当 returnImage=true 时，还会返回 { imageBase64, imageWidth, imageHeight, imageBytes }。如果 base64 载荷超过 8MB，技能会报错并要求使用更小的 maxDimension — path 处的文件仍会保存。

camera_sceneview_screenshot

捕获编辑器 Scene View（开发者的编辑视口 — 可俯瞰整个场景，包括摄像机视野外的对象）。这不同于 scene_screenshot（Game View / 玩家摄像机）和 camera_screenshot（单个游戏摄像机）。默认捕获完整的 Scene View，包括网格/辅助图标/选中状态（屏幕读取）；如果编辑器版本不支持内部 API，则自动回退到干净的离屏渲染。进行叠加层捕获时，Scene View 窗口必须打开且可见。

参数	类型	必需	默认值	描述
filename	string	否	"sceneview.png"	仅限文件名（不得包含路径分隔符）；保存到 Assets/Screenshots/ 下
includeOverlays	bool	否	true	true = 完整的 Scene View，包含网格/辅助图标/选中状态（不支持时回退到干净渲染）；false = 仅进行干净的离屏场景渲染
returnImage	bool	否	false	同时在响应中以 base64 格式返回 PNG（imageBase64），供无法访问文件系统的客户端使用
maxDimension	int	否	1280	仅在 returnImage=true 时使用；缩小返回图像（不影响保存的文件），使其较长边 ≤ 此值。限制在 256–4096 之间

返回： { success, path, width, height, mode, note } — mode 为 "screen_with_overlays" 或 "offscreen_clean" — 当 returnImage=true 时，还会返回 { imageBase64, imageWidth, imageHeight, imageBytes }。如果 base64 载荷超过 8MB，技能会报错并要求使用更小的 maxDimension — path 处的文件仍会保存。

**returnImage 使用提示：**能够读取文件的本地 Agent（例如通过本地 Unity Editor 使用 Claude Code）通常应省略 returnImage，直接读取 path 处的 PNG — 这样更节省 token。对于无法访问 Unity 项目文件系统的远程/MCP 客户端，请使用 returnImage=true。

camera_set_orthographic

在正交模式和透视模式之间切换游戏摄像机。

参数	类型	必填	默认值	描述
orthographic	bool	是	-	正交模式为 True，透视模式为 false
orthographicSize	float?	否	null	正交尺寸（仅适用于正交模式）
name	string	否	null	摄像机 GameObject 的名称
instanceId	int	否	0	摄像机 GameObject 的实例 ID
path	string	否	null	摄像机 GameObject 的层级路径

返回： { success, orthographic, orthographicSize }

camera_list

列出场景中的所有摄像机。

参数	类型	必填	默认值	描述

返回： { count, cameras: [{ name, instanceId, path, depth, orthographic, enabled }] }

---

精确签名

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