unity-cinemachine（Unity cinemachine 搜索）

Unity Cinemachine (Camera System)

Based on Unity 6.3 LTS -- Cinemachine 3.1 package IMPORTANT: Cinemachine 3.x renamed CinemachineVirtualCamera to CinemachineCamera

Core Concepts

Cinemachine procedurally controls the Unity camera at runtime. Compose camera behaviors from reusable components instead of writing custom camera scripts.

Architecture

1. CinemachineBrain -- On Main Camera; drives the Unity Camera from the highest-priority active CinemachineCamera
2. CinemachineCamera -- Lightweight virtual camera describing desired position, rotation, and lens (replaces CinemachineVirtualCamera from v2)
3. Priority System -- Highest-priority enabled CinemachineCamera wins
4. Pipeline Stages -- Body (position), Aim (rotation), Noise stages compute the final camera state

Namespace

using Unity.Cinemachine;  // Cinemachine 3.x (NOT "using Cinemachine;")

Minimal Setup

1. Add CinemachineBrain to Main Camera
2. Create GameObject with CinemachineCamera
3. Set Follow target and optionally LookAt target
4. Add Body/Aim components as needed

using UnityEngine;
using Unity.Cinemachine;

public class CameraSetup : MonoBehaviour
{
    [SerializeField] Transform playerTransform;

    void Start()
    {
        var vcam = gameObject.AddComponent<CinemachineCamera>();
        vcam.Follow = playerTransform;
        vcam.LookAt = playerTransform;
        vcam.Priority.Value = 10;
    }
}

Camera Setup Patterns

Basic Follow Camera

CinemachineCamera + CinemachineFollow. Set Follow target to player.

// CinemachineFollow provides a simple offset-based follow
var follow = gameObject.AddComponent<CinemachineFollow>();
follow.FollowOffset = new Vector3(0f, 5f, -10f);
follow.Damping = new Vector3(1f, 1f, 1f);

Third-Person Camera

CinemachineThirdPersonFollow for collision-aware third-person cameras.

Orbital / FreeLook Camera

CinemachineOrbitalFollow for orbit-around-target cameras controlled by player input. In Cinemachine 3.x, FreeLook is no longer a separate component -- use CinemachineCamera + CinemachineOrbitalFollow + CinemachineInputAxisController.

var orbital = gameObject.AddComponent<CinemachineOrbitalFollow>();
orbital.OrbitStyle = CinemachineOrbitalFollow.OrbitStyles.ThreeRing;
orbital.Radius = 5f;
// Add CinemachineInputAxisController to wire Input System actions
gameObject.AddComponent<CinemachineInputAxisController>();

2D Camera

CinemachinePositionComposer with dead zones and damping for smooth 2D tracking.

var composer = gameObject.AddComponent<CinemachinePositionComposer>();
composer.Damping = new Vector3(1f, 0.5f, 0f);
composer.DeadZoneWidth = 0.1f;
composer.DeadZoneHeight = 0.1f;
composer.ScreenPosition = new Vector2(0.5f, 0.5f);
composer.CameraDistance = 10f;  // orthographic distance

Body Components (Position Tracking)

Body components control how the camera position follows the target. Add one Body component per CinemachineCamera.

CinemachineTrackedDolly

Moves the camera along a SplineContainer path. Useful for cutscene rails, racing games, or side-scrollers.

var dolly = gameObject.AddComponent<CinemachineTrackedDolly>();
dolly.SplinePath = splineContainer;
dolly.AutoDolly.Enabled = true;      // auto-position along spline
dolly.CameraPosition = 0.5f;        // 0..1 position on spline
dolly.Damping = new Vector3(1f, 1f, 1f);

Aim Components (Rotation)

Aim components control how the camera rotates toward its LookAt target. Add one Aim component per CinemachineCamera.

CinemachinePanTilt

For first-person or manual-aim cameras:

var panTilt = gameObject.AddComponent<CinemachinePanTilt>();
panTilt.TiltAxis.Range = new Vector2(-70f, 70f); // clamp vertical look

Camera Blending

CinemachineBrain handles smooth transitions automatically.

Blend Styles

Switching Cameras

// Priority-based: Brain blends to highest priority
closeUpCamera.Priority.Value = 20;
wideCamera.Priority.Value = 10;

// Or enable/disable GameObjects -- Brain blends automatically
closeUpCamera.gameObject.SetActive(true);
wideCamera.gameObject.SetActive(false);

Custom per-camera-pair blends use a CinemachineBlenderSettings asset assigned to CinemachineBrain.CustomBlends.

State-Driven Cameras

CinemachineStateDrivenCamera maps Animator states to child CinemachineCameras. When the Animator transitions, the corresponding camera activates automatically.

Setup

1. Create a parent GameObject with CinemachineStateDrivenCamera
2. Add child GameObjects, each with CinemachineCamera
3. Assign the Animator that drives the state transitions
4. Map each Animator state to a child camera in the Inspector

Use Cases

• Combat -- Switch to over-shoulder cam when entering Combat Animator state
• Vehicles -- Different cameras for driving vs. reversing
• Stealth -- Wider FOV when in Crouch state
• Dialogue -- Close-up camera for conversation states

Camera Shake (Impulse System)

Generating Impulse

using UnityEngine;
using Unity.Cinemachine;

public class ExplosionShake : MonoBehaviour
{
    [SerializeField] CinemachineImpulseSource impulseSource;

    public void Explode()
    {
        impulseSource.GenerateImpulse();           // default velocity
        impulseSource.GenerateImpulse(3f);         // scaled intensity
        impulseSource.GenerateImpulse(Vector3.up); // directional
    }
}

Listener Properties

Noise (Procedural Shake)

CinemachineBasicMultiChannelPerlin adds continuous procedural noise (handheld feel, idle breathing).

CinemachineTargetGroup

Frame multiple targets with a single camera.

var group = gameObject.AddComponent<CinemachineTargetGroup>();
group.Targets = new CinemachineTargetGroup.Target[]
{
    new() { Object = player.transform, Weight = 1f, Radius = 1f },
    new() { Object = enemy.transform, Weight = 0.5f, Radius = 1f }
};
// Add CinemachineGroupFraming to the camera for auto-framing

Input Handling

Cinemachine 3.x uses InputAxis for camera control input. It integrates with Unity's Input System package.

CinemachineInputAxisController

Add this component alongside CinemachineOrbitalFollow or CinemachinePanTilt. It auto-discovers axes on sibling components and connects Input System actions.

Custom Input Provider

using UnityEngine;
using Unity.Cinemachine;
using System.Collections.Generic;

public class CustomCameraInput : MonoBehaviour, IInputAxisOwner
{
    [SerializeField] InputAxis horizontalAxis;
    [SerializeField] InputAxis verticalAxis;

    public void GetInputAxes(List<IInputAxisOwner.AxisDescriptor> axes)
    {
        axes.Add(new IInputAxisOwner.AxisDescriptor
        {
            DrivenAxis = () => ref horizontalAxis,
            Name = "Horizontal"
        });
        axes.Add(new IInputAxisOwner.AxisDescriptor
        {
            DrivenAxis = () => ref verticalAxis,
            Name = "Vertical"
        });
    }
}

Common Patterns

Third-Person with Collision Avoidance

var vcam = gameObject.AddComponent<CinemachineCamera>();
vcam.Follow = player; vcam.LookAt = player;

var tpFollow = gameObject.AddComponent<CinemachineThirdPersonFollow>();
tpFollow.ShoulderOffset = new Vector3(0.5f, 0f, 0f);
tpFollow.CameraDistance = 4f;
tpFollow.CameraSide = 1f;
tpFollow.CameraRadius = 0.2f;

var rotComposer = gameObject.AddComponent<CinemachineRotationComposer>();
rotComposer.Damping = new Vector2(0.5f, 0.5f);

Switching Cameras on Trigger Zones

using UnityEngine;
using Unity.Cinemachine;

public class CameraTriggerZone : MonoBehaviour
{
    [SerializeField] CinemachineCamera zoneCamera;
    [SerializeField] int activePriority = 20;
    [SerializeField] int inactivePriority = 0;

    void Start() => zoneCamera.Priority.Value = inactivePriority;

    void OnTriggerEnter(Collider other)
    {
        if (other.CompareTag("Player"))
            zoneCamera.Priority.Value = activePriority;
    }

    void OnTriggerExit(Collider other)
    {
        if (other.CompareTag("Player"))
            zoneCamera.Priority.Value = inactivePriority;
    }
}

Cutscene Camera Sequence

using UnityEngine;
using Unity.Cinemachine;
using System.Collections;

public class CutsceneSequence : MonoBehaviour
{
    [SerializeField] CinemachineCamera[] cameras;
    [SerializeField] float[] durations;

    public IEnumerator PlayCutscene()
    {
        for (int i = 0; i < cameras.Length; i++)
        {
            foreach (var cam in cameras) cam.Priority.Value = 0;
            cameras[i].Priority.Value = 100;
            yield return new WaitForSeconds(durations[i]);
        }
    }
}

Split-Screen Setup

// Each player: separate Camera + CinemachineBrain + CinemachineCamera
// Camera 1: Viewport Rect (0, 0, 0.5, 1) -- left half
// Camera 2: Viewport Rect (0.5, 0, 0.5, 1) -- right half
brain1.ChannelMask = OutputChannels.Channel01;
brain2.ChannelMask = OutputChannels.Channel02;
player1Cam.OutputChannel = OutputChannels.Channel01;
player2Cam.OutputChannel = OutputChannels.Channel02;

Camera Shake on Explosion

[SerializeField] CinemachineImpulseSource impulseSource;
[SerializeField] float shakeForce = 5f;

public void Detonate()
{
    impulseSource.GenerateImpulse(shakeForce);
}

Anti-Patterns

Key API Quick Reference

v2 to v3 Migration Reference

Related Skills

• For animation state machines, see unity-animation
• For rendering/cameras, see unity-graphics
• For Timeline, see unity-animation references/timeline.md
• For input system integration, see unity-input

Additional Resources

• See references/cinemachine-api.md