/cinemachine

name: unity-cinemachine
description: Set up Cinemachine Virtual Cameras. 配置 Cinemachine 虚拟相机。

Triggers

• Creating or tuning Cinemachine cameras
• Configuring follow/look-at/noise
• Building cinematic camera behavior
• 创建或调校 Cinemachine 相机、设置跟随/注视/噪声、构建运镜效果

Cinemachine Skills

Control Cinemachine Virtual Cameras and brain settings. Works with Cinemachine **2.x and 3.x** through a runtime reflection adapter (`CinemachineAdapter` / `CinemachineSkills`).

Operating Mode

• **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`）需用户 grant，grant 后服务端一步执行返结果。
• **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 未安装..." }` 的 stub —— 调用方应先用 `package_*` 系列 skill 确认安装状态。
• **反射脆弱性**：CM2 ↔ CM3 之间 API 名变化大（`CinemachineVirtualCamera` → `CinemachineCamera`，`CinemachineComponentBase` 改名等）。本模块通过 `CinemachineAdapter` 反射桥接，遇 CM 早期预览版（< `3.0.0-pre.5`）可能因 API 漂移返回失败 —— 优先用 `cinemachine_inspect_vcam` 探测当前可用字段，再决定 `propertyName`。

**DO NOT** (common hallucinations):

• `cinemachine_create` does not exist → use `cinemachine_create_vcam` for virtual cameras
• `cinemachine_set_target` / `cinemachine_set_follow` / `cinemachine_set_lookat` do not exist → use `cinemachine_set_targets` (sets both Follow and LookAt in one call)
• `cinemachine_add_brain` does not exist → CinemachineBrain is auto-added to Main Camera on first VCam creation
• Cinemachine 2.x uses `CinemachineVirtualCamera`; Cinemachine 3.x uses `CinemachineCamera` — skills handle this automatically

Additional compatibility notes:

• CM3 priority access should use `Priority.Value` as the lowest common API when writing compatibility code.
• Early CM3 previews before `3.0.0-pre.5` changed core camera APIs significantly and are outside the current support baseline.

**Routing**:

• For basic Game Camera operations → use `camera` module
• For Scene View camera → use `camera` module's `camera_set_transform`/`camera_look_at`
• For camera animation sequences → use `timeline` module with Cinemachine track

Skills

`cinemachine_create_vcam`

Create a new Virtual Camera. **Parameters:**

• `name` (string): Name of the VCam GameObject.
• `folder` (string): Parent folder path (default: "Assets/Settings").

`cinemachine_inspect_vcam`

Deeply inspect a VCam, returning fields and tooltips. **Parameters:**

• `vcamName` (string, optional): Name of the VCam GameObject.
• `instanceId` (int, optional): VCam instance ID.
• `path` (string, optional): VCam hierarchy path.

`cinemachine_set_vcam_property`

Set any property on VCam or its pipeline components. **Parameters:**

• `vcamName` (string): Name of the VCam.
• `instanceId` (int, optional): VCam Instance ID.
• `path` (string, optional): VCam hierarchy path.
• `componentType` (string): "Main" (VCam itself), "Lens", or Component name (e.g. "OrbitalFollow").
• `propertyName` (string): Field or property name.
• `value` (object): New value.
• `fov` (float, optional): Lens FOV shortcut. When supplied without `propertyName`, routes to `cinemachine_set_lens`.
• `nearClip` (float, optional): Lens near clip shortcut.
• `farClip` (float, optional): Lens far clip shortcut.
• `orthoSize` (float, optional): Lens orthographic size shortcut.

`cinemachine_set_targets`

Set Follow and LookAt targets. **Parameters:**

• `vcamName` (string): Name of the VCam.
• `instanceId` (int, optional): VCam Instance ID (preferred for precision).
• `path` (string, optional): VCam hierarchy path.
• `followName` (string, optional): GameObject name to follow.
• `lookAtName` (string, optional): GameObject name to look at.

`cinemachine_set_component`

Switch VCam pipeline component (Body/Aim/Noise). **Parameters:**

• `vcamName` (string): Name of the VCam.
• `stage` (string): "Body", "Aim", or "Noise".
• `componentType` (string): Type name (e.g. "OrbitalFollow", "Composer") or "None" to remove.

`cinemachine_add_component`

> **DEPRECATED** — Use `cinemachine_set_component` instead for proper pipeline control (Body/Aim/Noise stages). Add a Cinemachine component (legacy, supports CM2 and CM3). **Parameters:**

• `vcamName` (string): Name of the VCam.
• `instanceId` (int, optional): VCam Instance ID.
• `path` (string, optional): VCam hierarchy path.
• `componentType` (string): Type name (e.g., "OrbitalFollow").

`cinemachine_set_lens`

Quickly configure Lens settings (FOV, Near, Far, OrthoSize). **Parameters:**

• `vcamName` (string): Name of the VCam.
• `fov` (float, optional): Field of View.
• `nearClip` (float, optional): Near Clip Plane.
• `farClip` (float, optional): Far Clip Plane.
• `orthoSize` (float, optional): Orthographic Size.

`cinemachine_list_components`

List all available Cinemachine component names. **Parameters:**

• None.

`cinemachine_impulse_generate`

Trigger an Impulse at location or via Source. **Parameters:**

• `sourceParams` (string, optional): JSON string for parameters, e.g., `{"velocity": {"x": 0, "y": -1, "z": 0}}`.

`cinemachine_get_brain_info`

Get info about the Active Camera and Blend. **Parameters:**

• None.

`cinemachine_create_target_group`

Create a CinemachineTargetGroup. **Parameters:**

• `name` (string): Name of the new TargetGroup GameObject.

`cinemachine_target_group_add_member`

Add or update a member in a TargetGroup. **Parameters:**

• `groupName` (string): Name of the TargetGroup.
• `targetName` (string): Name of the member GameObject.
• `weight` (float): Member weight (default 1).

-