unity-cinemachine

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

触发条件

• 创建或调校 Cinemachine 相机
• 配置跟随/注视/噪声
• 构建电影级运镜效果
• 创建或调校 Cinemachine 相机、设置跟随/注视/噪声、构建运镜效果

Cinemachine 技能

控制 Cinemachine 虚拟相机和 brain 设置。通过运行时反射适配器（CinemachineAdapter / CinemachineSkills）兼容 2.x 和 3.x 版 Cinemachine。

运行模式

• Approval：查询类 skill（cinemachine_inspect_vcam / cinemachine_list_components / cinemachine_get_brain_info，源码标记为 SkillMode.SemiAuto）直接执行；其余配置/创建类（cinemachine_create_vcam / cinemachine_set_targets / cinemachine_set_lens / cinemachine_configure_body / cinemachine_configure_aim 等，标记为 SkillMode.FullAuto）需要用户授权，授权后由服务端一步执行并返回结果。
• Auto / Bypass：未被禁用列表拦截的 skill 直接执行。
• 本模块包含 Delete 类 skill：cinemachine_set_component（替换/移除 pipeline component）、cinemachine_target_group_remove_member、cinemachine_remove_extension 标记为 SkillOperation.Delete，会被 IsForbiddenInSemi 静态拦截——仅 Bypass 模式或加入 Allowlist 后才能调用。
• 包依赖：必须安装 com.unity.cinemachine 包（CM 2.x 或 3.x）。未安装时，所有 skill 都会返回 { error = "Cinemachine is not installed. Install Cinemachine 2.x or 3.x via Package Manager." } 的 stub——调用方应先使用 package_* 系列 skill 确认安装状态。
• 反射脆弱性：CM2 与 CM3 之间的 API 名称差异很大（CinemachineVirtualCamera → CinemachineCamera，CinemachineComponentBase 等也已改名）。本模块通过 CinemachineAdapter 进行反射桥接；如果遇到 CM 早期预览版（< 3.0.0-pre.5），可能会因 API 变动而返回失败——请优先使用 cinemachine_inspect_vcam 探测当前可用字段，再决定 propertyName。

请勿（常见幻觉）：

• cinemachine_create 不存在 → 虚拟相机请使用 cinemachine_create_vcam
• cinemachine_set_target / cinemachine_set_follow / cinemachine_set_lookat 不存在 → 请使用 cinemachine_set_targets（一次调用即可同时设置 Follow 和 LookAt）
• cinemachine_add_brain 不存在 → 首次创建 VCam 时，会自动将 CinemachineBrain 添加到 Main Camera
• Cinemachine 2.x 使用 CinemachineVirtualCamera；Cinemachine 3.x 使用 CinemachineCamera——技能会自动处理

其他兼容性说明：

• 编写兼容代码时，CM3 的 priority 应使用 Priority.Value，这是最通用的 API。
• 3.0.0-pre.5 之前的 CM3 早期预览版对核心相机 API 做了重大更改，不在当前支持范围内。

路由：

• 基本的 Game Camera 操作 → 使用 camera 模块
• Scene View 相机 → 使用 camera 模块的 camera_set_transform / camera_look_at
• 相机动画序列 → 使用带有 Cinemachine 轨道的 timeline 模块

技能

cinemachine_create_vcam

创建新的虚拟相机。 参数：

• name（字符串）：VCam GameObject 的名称。
• folder（字符串）：父文件夹路径（默认值："Assets/Settings"）。

cinemachine_inspect_vcam

深入检查 VCam，返回字段和工具提示。 参数：

• vcamName（字符串，可选）：VCam GameObject 的名称。
• instanceId（整数，可选）：VCam 实例 ID。
• path（字符串，可选）：VCam 层级路径。

cinemachine_set_vcam_property

设置 VCam 或其管线组件上的任意属性。 参数：

• vcamName（string）：VCam 的名称。
• instanceId（int，可选）：VCam 实例 ID。
• path（string，可选）：VCam 层级路径。
• componentType（string）："Main"（VCam 本身）、"Lens" 或组件名称（例如 "OrbitalFollow"）。
• propertyName（string）：字段或属性名称。
• value（object）：新值。
• fov（float，可选）：Lens FOV 快捷参数。若未提供 propertyName，则会转交给 cinemachine_set_lens。
• nearClip（float，可选）：Lens 近裁剪面快捷参数。
• farClip（float，可选）：Lens 远裁剪面快捷参数。
• orthoSize（float，可选）：Lens 正交尺寸快捷参数。

cinemachine_set_targets

设置 Follow 和 LookAt 目标。 参数：

• vcamName（string）：VCam 的名称。
• instanceId（int，可选）：VCam 实例 ID（优先使用，以提高精确度）。
• path（string，可选）：VCam 层级路径。
• followName（string，可选）：要跟随的 GameObject 名称。
• lookAtName（string，可选）：要注视的 GameObject 名称。

cinemachine_set_component

切换 VCam 管线组件（Body/Aim/Noise）。 参数：

• vcamName（string）：VCam 的名称。
• instanceId（int，可选）：VCam 实例 ID。
• path（string，可选）：VCam 层级路径。
• stage（string）："Body"、"Aim" 或 "Noise"。
• componentType（string）：类型名称（例如 "OrbitalFollow"、"Composer"），或使用 "None" 移除组件。

cinemachine_add_component

已弃用 — 请改用 cinemachine_set_component，以正确控制管线（Body/Aim/Noise 阶段）。 添加 Cinemachine 组件（旧版，支持 CM2 和 CM3）。 参数：

• vcamName（string）：VCam 的名称。
• instanceId（int，可选）：VCam 实例 ID。
• path（string，可选）：VCam 层级路径。
• componentType（string）：类型名称（例如 "OrbitalFollow"）。

cinemachine_set_lens

快速配置 Lens 设置（FOV、Near、Far、OrthoSize）和投影 ModeOverride。 参数：

• vcamName（string）：VCam 的名称。
• instanceId（int，可选）：VCam 实例 ID。
• path（string，可选）：VCam 层级路径。
• fov（float，可选）：视野。
• nearClip（float，可选）：近裁剪面。
• farClip（float，可选）：远裁剪面。
• orthoSize（float，可选）：正交尺寸。
• mode（string，可选）：写入镜头的 ModeOverride，即该 VCam 激活时应用于 Unity Camera 的投影模式。大小写不敏感；有效值为 None（保留 Camera 自身的投影设置）、Orthographic、Perspective 和 Physical。省略此参数会保留现有的 ModeOverride。

必须至少提供 fov / nearClip / farClip / orthoSize / mode 中的一项；如果均未提供，则返回 No values provided to update.。若 mode 无效，则会在写入任何内容前拒绝整个调用，并返回 SEMANTIC_INVALID + validValues，因此其他参数也不会应用。

cinemachine_list_components

列出所有可用的 Cinemachine 组件名称。 参数：

• 无。

cinemachine_impulse_generate

在指定位置或通过 Source 触发 Impulse。 参数：

• sourceParams（string，可选）：参数的 JSON 字符串，例如 {"velocity": {"x": 0, "y": -1, "z": 0}}。

cinemachine_get_brain_info

获取有关活动 Camera 和 Blend 的信息。 参数：

• 无。

cinemachine_create_target_group

创建 CinemachineTargetGroup。 参数：

• name（string）：新 TargetGroup GameObject 的名称。

cinemachine_target_group_add_member

在 TargetGroup 中添加或更新成员。 参数：

• groupName (string)：TargetGroup 的名称。
• groupInstanceId (int, optional)：TargetGroup 实例 ID。
• groupPath (string, optional)：TargetGroup 层级路径。
• targetName (string)：成员 GameObject 的名称。
• targetInstanceId (int, optional)：成员 GameObject 实例 ID。
• targetPath (string, optional)：成员 GameObject 层级路径。
• weight (float)：成员权重（默认值为 1）。
• radius (float)：成员半径（默认值为 1）。

cinemachine_target_group_remove_member

从 TargetGroup 中移除成员。 参数：

• groupName (string)：TargetGroup 的名称。
• groupInstanceId (int, optional)：TargetGroup 实例 ID。
• groupPath (string, optional)：TargetGroup 层级路径。
• targetName (string)：成员 GameObject 的名称。
• targetInstanceId (int, optional)：成员 GameObject 实例 ID。
• targetPath (string, optional)：成员 GameObject 层级路径。

cinemachine_set_spline

将 SplineContainer 分配给 VCam 的 SplineDolly 组件（Body 阶段）。 参数：

• vcamName (string)：VCam 的名称。
• vcamInstanceId (int, optional)：VCam 实例 ID。
• vcamPath (string, optional)：VCam 层级路径。
• splineName (string)：包含 SplineContainer 的 GameObject 的名称。
• splineInstanceId (int, optional)：SplineContainer GameObject 实例 ID。
• splinePath (string, optional)：SplineContainer GameObject 层级路径。

cinemachine_add_extension

向 VCam 添加 CinemachineExtension。 参数：

• vcamName (string)：VCam 的名称。
• instanceId (int, optional)：VCam 实例 ID。
• path (string, optional)：VCam 层级路径。
• extensionName (string)：扩展的类型名称（例如，“CinemachineStoryboard”、“CinemachineImpulseListener”）。

cinemachine_remove_extension

从 VCam 移除 CinemachineExtension。 参数：

• vcamName (string)：VCam 的名称。
• instanceId (int, optional)：VCam 实例 ID。
• path (string, optional)：VCam 层级路径。
• extensionName (string)：扩展的类型名称。

cinemachine_set_active

通过设置最高优先级，强制激活 VCam（SOLO）。 参数：

• vcamName (string)：要激活的 VCam 的名称。
• instanceId (int, optional)：VCam 实例 ID。
• path (string, optional)：VCam 层级路径。

cinemachine_create_mixing_camera

创建 Cinemachine Mixing Camera。 参数：

• name (string)：新 GameObject 的名称。

cinemachine_mixing_camera_set_weight

设置 Mixing Camera 中子摄像机的权重。 参数：

• mixerName (string, optional)：Mixing Camera 的名称。
• mixerInstanceId (int, optional)：Mixing Camera 实例 ID。
• mixerPath (string, optional)：Mixing Camera 层级路径。
• mixerEntityId (string, optional)：Mixing Camera 实体 ID（Unity 6000.4+，优先使用）。
• childName (string, optional)：子 VCam 的名称。
• childInstanceId (int, optional)：子 VCam 实例 ID。
• childPath (string, optional)：子 VCam 层级路径。
• childEntityId (string, optional)：子 VCam 实体 ID（Unity 6000.4+，优先使用）。
• weight (float)：权重值，通常为 0.0–1.0（默认值为 1）。

cinemachine_create_clear_shot

创建 Cinemachine Clear Shot Camera。 参数：

• name (string)：新 GameObject 的名称。

cinemachine_create_state_driven_camera

创建 Cinemachine State Driven Camera。 参数：

• name (string)：新 GameObject 的名称。
• targetAnimatorName (string, optional)：要绑定的 Animator 所在 GameObject 的名称。

cinemachine_state_driven_camera_add_instruction

向 State Driven Camera 添加状态映射指令。 参数：

• cameraName（string，可选）：State Driven Camera 的名称。
• cameraInstanceId（int，可选）：State Driven Camera 实例 ID。
• cameraPath（string，可选）：State Driven Camera 层级路径。
• cameraEntityId（string，可选）：State Driven Camera 实体 ID（Unity 6000.4+，优先使用）。
• stateName（string）：动画状态的名称（例如，“Run”）。
• childCameraName（string，可选）：此状态下要激活的子 VCam 名称。
• childInstanceId（int，可选）：子 VCam 实例 ID。
• childPath（string，可选）：子 VCam 层级路径。
• childEntityId（string，可选）：子 VCam 实体 ID（Unity 6000.4+，优先使用）。
• minDuration（float，可选）：最短持续时间，单位为秒（默认值为 0）。
• activateAfter（float，可选）：激活前的延迟时间，单位为秒（默认值为 0）。

cinemachine_set_noise

配置 Noise 设置（Basic Multi Channel Perlin）。 参数：

• vcamName（string）：VCam 的名称。
• instanceId（int，可选）：VCam 实例 ID。
• path（string，可选）：VCam 层级路径。
• amplitudeGain（float）：Noise 振幅。
• frequencyGain（float）：Noise 频率。

cinemachine_set_priority

为 Virtual Camera 设置明确的优先级。优先级越高，越先激活。 参数：

• vcamName（string，可选）：VCam 名称。请提供 name、instanceId 或 path 之一。
• instanceId（int，可选）：VCam 实例 ID。
• path（string，可选）：VCam 层级路径。
• priority（int）：优先级值（默认值为 10）。

cinemachine_set_blend

在 CinemachineBrain 上设置默认混合，或设置特定摄像机对的混合。将 fromCamera/toCamera 留空可设置默认混合。 参数：

• style（string）：混合样式 — Cut/EaseInOut/EaseIn/EaseOut/HardIn/HardOut/Linear（默认值为 EaseInOut）。
• time（float）：混合时长，单位为秒（默认值为 2）。
• fromCamera（string，可选）：特定摄像机对混合的源 VCam 名称。
• toCamera（string，可选）：特定摄像机对混合的目标 VCam 名称。

cinemachine_set_brain

配置 CinemachineBrain 属性：更新方法、默认混合和调试显示。 参数：

• updateMethod（string，可选）：FixedUpdate/LateUpdate/SmartUpdate/ManualUpdate。
• blendUpdateMethod（string，可选）：FixedUpdate/LateUpdate。
• defaultBlendStyle（string，可选）：混合样式名称（参见 cinemachine_set_blend）。
• defaultBlendTime（float，可选）：默认混合时长，单位为秒。
• showDebugText（bool，可选）：显示 Cinemachine 调试文本叠加层。
• showCameraFrustum（bool，可选）：绘制活动摄像机视锥 Gizmo。
• ignoreTimeScale（bool，可选）：混合时忽略 Time.timeScale。

cinemachine_create_sequencer

创建 Sequencer 摄像机（CM3）或 BlendList 摄像机（CM2），按顺序播放子摄像机。 参数：

• name（string）：新 GameObject 的名称。
• loop（bool）：是否循环播放序列（默认值为 false）。

cinemachine_sequencer_add_instruction

向 Sequencer/BlendList 摄像机添加子摄像机指令。 参数：

• sequencerName (string, optional)：Sequencer 摄像机名称。
• sequencerInstanceId (int, optional)：Sequencer 实例 ID。
• sequencerPath (string, optional)：Sequencer 层级路径。
• sequencerEntityId (string, optional)：Sequencer 实体 ID（Unity 6000.4+，优先使用）。
• childCameraName (string, optional)：子 VCam 名称。
• childInstanceId (int, optional)：子 VCam 实例 ID。
• childPath (string, optional)：子 VCam 层级路径。
• childEntityId (string, optional)：子 VCam 实体 ID（Unity 6000.4+，优先使用）。
• hold (float)：保持此子摄像机的时长，单位为秒（默认值为 2）。
• blendStyle (string)：进入此子摄像机时使用的混合样式（默认值为 EaseInOut）。
• blendTime (float)：混合时长，单位为秒（默认值为 2）。

Sequencer 和子摄像机各至少提供一个标识符。

cinemachine_create_freelook

创建 FreeLook 摄像机。CM2 使用 CinemachineFreeLook；CM3 使用 CinemachineCamera + OrbitalFollow(ThreeRing) + RotationComposer。 参数：

• name (string)：新 GameObject 的名称。
• followName (string, optional)：要跟随的 GameObject。
• lookAtName (string, optional)：要注视的 GameObject。

cinemachine_configure_camera_manager

通过一次调用配置 ClearShot/StateDriven/Sequencer 摄像机管理器属性。如果目标不支持某管理器类型的参数、无法解析 animatorName（或其对应对象没有 Animator），或混合样式未知，则会在写入任何内容前拒绝请求。 参数：

• cameraName (string, optional)：摄像机管理器名称。请提供 name/instanceId/path 中的一项。
• cameraInstanceId (int, optional)：摄像机管理器实例 ID。
• cameraPath (string, optional)：摄像机管理器层级路径。
• activateAfter (float, optional)：ClearShot — 激活前的延迟。
• minDuration (float, optional)：ClearShot — 镜头的最短持续时间。
• randomizeChoice (bool, optional)：ClearShot — 随机选择镜头。
• animatorName (string, optional)：StateDriven — 挂载 Animator 的 GameObject 名称。
• layerIndex (int, optional)：StateDriven — Animator 层索引。
• defaultBlendStyle (string, optional)：默认混合样式（ClearShot/StateDriven 共用）。
• defaultBlendTime (float, optional)：默认混合时长，单位为秒。
• loop (bool, optional)：Sequencer — 循环播放。

cinemachine_configure_body

一次调用即可配置 Body 阶段组件（Follow、OrbitalFollow、ThirdPersonFollow、PositionComposer、FramingTransposer 等）。仅应用与当前活动组件匹配的字段；如果没有匹配项，调用将失败，并由 warnings 列出无法写入的字段。 参数：

• vcamName（string，可选）：VCam 名称。请提供 name、instanceId 或 path 之一。
• instanceId（int，可选）：VCam 实例 ID。
• path（string，可选）：VCam 层级路径。

Follow / Transposer：

• offsetX / offsetY / offsetZ（float，可选）：Follow 偏移向量。
• bindingMode（string，可选）：绑定／目标附加模式（例如 LockToTarget、WorldSpace）。
• dampingX / dampingY / dampingZ（float，可选）：位置阻尼。

OrbitalFollow / OrbitalTransposer：

• orbitStyle（string，可选）：Sphere 或 ThreeRing。
• radius（float，可选）：球形轨道半径。
• topHeight / topRadius（float，可选）：顶部环参数。
• midHeight / midRadius（float，可选）：中间环参数。
• bottomHeight / bottomRadius（float，可选）：底部环参数。

ThirdPersonFollow：

• shoulderX / shoulderY / shoulderZ（float，可选）：肩部偏移。
• verticalArmLength（float，可选）：垂直臂长。
• cameraSide（float，可选）：0 = 左，1 = 右。

PositionComposer / FramingTransposer：

• cameraDistance（float，可选）：相机与目标之间的距离。
• screenX / screenY（float，可选）：目标在屏幕上的位置（0–1）。
• deadZoneWidth / deadZoneHeight（float，可选）：死区大小（0–1）。

cinemachine_configure_aim

一次调用即可配置 Aim 阶段组件（RotationComposer、Composer、PanTilt、POV 等）。仅应用与当前活动组件匹配的字段；如果没有匹配项，调用将失败，并由 warnings 列出无法写入的字段。 参数：

• vcamName（string，可选）：VCam 名称。请提供 name、instanceId 或 path 之一。
• instanceId（int，可选）：VCam 实例 ID。
• path（string，可选）：VCam 层级路径。

Composer / RotationComposer：

• screenX / screenY（float，可选）：目标在屏幕上的位置。
• deadZoneWidth / deadZoneHeight（float，可选）：死区大小。
• softZoneWidth / softZoneHeight（float，可选）：软区大小。
• horizontalDamping / verticalDamping（float，可选）：构图阻尼。
• lookaheadTime / lookaheadSmoothing（float，可选）：目标前瞻调节参数。
• centerOnActivate（bool，可选）：激活时重新居中。

PanTilt / POV：

• referenceFrame（string，可选）：平移／倾斜轴的参考坐标系。
• panValue / tiltValue（float，可选）：明确指定的平移／倾斜值。

目标偏移：

• targetOffsetX / targetOffsetY / targetOffsetZ（float，可选）：相对于目标枢轴点的偏移。

cinemachine_configure_extension

配置 Cinemachine 扩展（CinemachineConfiner、CinemachineDeoccluder/Collider、CinemachineFollowZoom、CinemachineGroupFraming 等）。如果省略 extensionName，则使用 VCam 上的第一个扩展；如果 VCam 不包含指定的 extensionName，或无法解析 boundingShapeName，则会拒绝请求。无法写入的设置会列在 warnings 中。 参数：

• vcamName（string，可选）：VCam 名称。请提供名称、instanceId 或 path 中的一项。
• instanceId（int，可选）：VCam 实例 ID。
• path（string，可选）：VCam 层级路径。
• extensionName（string，可选）：扩展类型名称（例如 CinemachineConfiner）。

Confiner：

• boundingShapeName（string，可选）：边界形状 GameObject 的名称。
• damping（float，可选）：约束时应用的阻尼。
• slowingDistance（float，可选）：边界形状内的减速距离。

Deoccluder / Collider：

• cameraRadius（float，可选）：摄像机碰撞半径。
• strategy（string，可选）：去遮挡策略名称。
• maximumEffort（int，可选）：射线检测的最大迭代次数。
• smoothingTime（float，可选）：遮挡变化的平滑时间。

FollowZoom：

• width（float，可选）：以世界单位表示的目标宽度。
• fovMin / fovMax（float，可选）：FOV 限制范围。

GroupFraming：

• framingMode（string，可选）：构图模式名称。
• framingSize（float，可选）：所需的构图尺寸。
• sizeAdjustment（string，可选）：尺寸调整策略名称。

cinemachine_configure_impulse_source

配置 CinemachineImpulseSource 定义（形状、持续时间、增益）。如果未指定源，则使用场景中的第一个 CinemachineImpulseSource。 参数：

• sourceName（string，可选）：源名称。请提供名称、instanceId 或 path 中的一项；全部省略则选择第一个源。
• sourceInstanceId（string，可选）：源实例 ID。
• sourcePath（string，可选）：源层级路径。
• amplitudeGain（float，可选）：振幅增益乘数。
• frequencyGain（float，可选）：频率增益乘数。
• impactRadius（float，可选）：以世界单位表示的冲击半径。
• duration（float，可选）：信号持续时间，单位为秒。
• dissipationRate（float，可选）：随距离增加的耗散率。

---

最小示例

import unity_skills

# Create a vcam that follows and looks at the player
unity_skills.call_skill("cinemachine_create_vcam", name="PlayerCam")
unity_skills.call_skill("cinemachine_set_targets", vcamName="PlayerCam", followName="Player", lookAtName="Player")

精确签名

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