unity-cinemachine
Unity 6 Cinemachine camera system guide. Use when working with virtual cameras, camera blending, follow cameras, FreeLook, camera shake, or state-driven cameras. Covers Cinemachine 3.x API. Based on Unity 6.3 LTS documentation.
Nice-Wolf-Studio · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Nice-Wolf-Studio/unity-claude-skills --skill unity-cinemachineAbout this skill
name: unity-cinemachine description: > Unity 6 Cinemachine camera system guide. Use when working with virtual cameras, camera blending, follow cameras, FreeLook, camera shake, or state-driven cameras. Covers Cinemachine 3.x API. Based on Unity 6.3 LTS documentation.
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
- CinemachineBrain -- On Main Camera; drives the Unity Camera from the highest-priority active CinemachineCamera
- CinemachineCamera -- Lightweight virtual camera describing desired position, rotation, and lens (replaces CinemachineVirtualCamera from v2)
- Priority System -- Highest-priority enabled CinemachineCamera wins
- 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
- Add
CinemachineBrainto Main Camera - Create GameObject with
CinemachineCamera - Set Follow target and optionally LookAt target
- 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.
| Property | Description |
|---|---|
ShoulderOffset | Offset from follow target in local space |
CameraDistance | Distance from shoulder point |
CameraSide | 0=left, 0.5=center, 1=right |
CameraRadius | Collision detection radius |
DampingIntoCollision | Damping when moving closer due to collision |
DampingFromCollision | Damping when returning after collision |
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.
| Component | Use Case |
|---|---|
CinemachineFollow | Simple offset follow with damping |
CinemachineThirdPersonFollow | Collision-aware third-person |
CinemachineOrbitalFollow | Orbit around target (FreeLook style) |
CinemachinePositionComposer | Screen-space framing with dead zones |
CinemachineHardLockToTarget | Snap position exactly to target (no damping) |
CinemachineTrackedDolly | Follow a SplineContainer path |
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.
| Component | Use Case |
|---|---|
CinemachineRotationComposer | Soft-zone aim with dead zones and damping |
CinemachineHardLookAt | Always face target exactly (no damping) |
CinemachinePanTilt | Manual pan/tilt via input axes (first-person) |
CinemachineGroupFraming | Auto-frame a CinemachineTargetGroup |
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
| Style | Description |
|---|---|
Cut | Instant switch |
EaseInOut | Smooth acceleration/deceleration (most common) |
EaseIn / EaseOut | One-sided easing |
HardIn / HardOut | Hard start or end |
Linear | Constant speed |
Custom | User-defined AnimationCurve |
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.Se
Read the complete source ↗