Unity Cinemachine

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.

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 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。

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.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.
• 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) and the projection ModeOverride. Parameters:

• vcamName (string): Name of the VCam.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.
• fov (float, optional): Field of View.
• nearClip (float, optional): Near Clip Plane.
• farClip (float, optional): Far Clip Plane.
• orthoSize (float, optional): Orthographic Size.
• mode (string, optional): Writes the lens ModeOverride, i.e. the projection mode this VCam pushes to the Unity Camera when it goes live. Case-insensitive; valid values are None (leave the Camera's own projection alone), Orthographic, Perspective and Physical. Omitting it leaves the existing ModeOverride untouched.

At least one of fov / nearClip / farClip / orthoSize / mode must be supplied; passing none returns No values provided to update. An invalid mode rejects the whole call with SEMANTIC_INVALID + validValues before anything is written, so the other parameters are not applied either.

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.
• groupInstanceId (int, optional): TargetGroup instance ID.
• groupPath (string, optional): TargetGroup hierarchy path.
• targetName (string): Name of the member GameObject.
• targetInstanceId (int, optional): Member GameObject instance ID.
• targetPath (string, optional): Member GameObject hierarchy path.
• weight (float): Member weight (default 1).
• radius (float): Member radius (default 1).

cinemachine_target_group_remove_member

Remove a member from a TargetGroup. Parameters:

• groupName (string): Name of the TargetGroup.
• groupInstanceId (int, optional): TargetGroup instance ID.
• groupPath (string, optional): TargetGroup hierarchy path.
• targetName (string): Name of the member GameObject.
• targetInstanceId (int, optional): Member GameObject instance ID.
• targetPath (string, optional): Member GameObject hierarchy path.

cinemachine_set_spline

Assign a SplineContainer to a VCam's SplineDolly component (Body stage). Parameters:

• vcamName (string): Name of the VCam.
• vcamInstanceId (int, optional): VCam instance ID.
• vcamPath (string, optional): VCam hierarchy path.
• splineName (string): Name of the GameObject with SplineContainer.
• splineInstanceId (int, optional): SplineContainer GameObject instance ID.
• splinePath (string, optional): SplineContainer GameObject hierarchy path.

cinemachine_add_extension

Add a CinemachineExtension to a VCam. Parameters:

• vcamName (string): Name of the VCam.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.
• extensionName (string): Type name of the extension (e.g., "CinemachineStoryboard", "CinemachineImpulseListener").

cinemachine_remove_extension

Remove a CinemachineExtension from a VCam. Parameters:

• vcamName (string): Name of the VCam.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.
• extensionName (string): Type name of the extension.

cinemachine_set_active

Force activation of a VCam (SOLO) by setting highest priority. Parameters:

• vcamName (string): Name of the VCam to activate.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.

cinemachine_create_mixing_camera

Create a Cinemachine Mixing Camera. Parameters:

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

cinemachine_mixing_camera_set_weight

Set the weight of a child camera within a Mixing Camera. Parameters:

• mixerName (string, optional): Name of the Mixing Camera.
• mixerInstanceId (int, optional): Mixing Camera instance ID.
• mixerPath (string, optional): Mixing Camera hierarchy path.
• mixerEntityId (string, optional): Mixing Camera entity ID (Unity 6000.4+, preferred).
• childName (string, optional): Name of the child VCam.
• childInstanceId (int, optional): Child VCam instance ID.
• childPath (string, optional): Child VCam hierarchy path.
• childEntityId (string, optional): Child VCam entity ID (Unity 6000.4+, preferred).
• weight (float): Weight value, usually 0.0–1.0 (default 1).

cinemachine_create_clear_shot

Create a Cinemachine Clear Shot Camera. Parameters:

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

cinemachine_create_state_driven_camera

Create a Cinemachine State Driven Camera. Parameters:

• name (string): Name of the new GameObject.
• targetAnimatorName (string, optional): Name of the GameObject with the Animator to bind.

cinemachine_state_driven_camera_add_instruction

Add a state mapping instruction to a State Driven Camera. Parameters:

• cameraName (string, optional): Name of the State Driven Camera.
• cameraInstanceId (int, optional): State Driven Camera instance ID.
• cameraPath (string, optional): State Driven Camera hierarchy path.
• cameraEntityId (string, optional): State Driven Camera entity ID (Unity 6000.4+, preferred).
• stateName (string): Name of the animation state (e.g., "Run").
• childCameraName (string, optional): Name of the child VCam to activate for this state.
• childInstanceId (int, optional): Child VCam instance ID.
• childPath (string, optional): Child VCam hierarchy path.
• childEntityId (string, optional): Child VCam entity ID (Unity 6000.4+, preferred).
• minDuration (float, optional): Minimum duration in seconds (default 0).
• activateAfter (float, optional): Delay in seconds before activation (default 0).

cinemachine_set_noise

Configure Noise settings (Basic Multi Channel Perlin). Parameters:

• vcamName (string): Name of the VCam.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.
• amplitudeGain (float): Noise Amplitude.
• frequencyGain (float): Noise Frequency.

cinemachine_set_priority

Set explicit priority value for a Virtual Camera. Higher priority wins activation. Parameters:

• vcamName (string, optional): VCam name. Provide one of name/instanceId/path.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.
• priority (int): Priority value (default 10).

cinemachine_set_blend

Set default blend or per-camera-pair blend on the CinemachineBrain. Leave fromCamera/toCamera empty for default blend. Parameters:

• style (string): Blend style — Cut/EaseInOut/EaseIn/EaseOut/HardIn/HardOut/Linear (default EaseInOut).
• time (float): Blend duration in seconds (default 2).
• fromCamera (string, optional): Source VCam name for per-pair blend.
• toCamera (string, optional): Destination VCam name for per-pair blend.