/cinemachine

name: cinemachine
description: "Cinemachine camera system — virtual cameras, FreeLook, blending, noise profiles, state-driven cameras, confiner, follow/aim behaviors."
globs: ["**/*Cinemachine*", "**/*Camera*.cs", "**/*Cam*.cs"]

Cinemachine

Setup

1. Add `CinemachineBrain` component to Main Camera 2. Create Virtual Cameras — Brain auto-blends to highest priority

Virtual Camera Components

**Body (follow):**

• `Transposer` — 3D offset follow (configurable damping)
• `Framing Transposer` — 2D/screen-space follow (dead zone, soft zone)
• `Orbital Transposer` — orbit around target (user input rotates)
• `Tracked Dolly` — follow a path

**Aim (look at):**

• `Composer` — keep target in frame with dead/soft zones
• `Group Composer` — frame a group of targets
• `Hard Look At` — no damping, instant look
• `POV` — player-controlled rotation (FPS)

Common Setups

2D Platformer Camera

Virtual Camera:
  Body: Framing Transposer
    - Screen X/Y: 0.5 (center)
    - Dead Zone Width: 0.1, Height: 0.1
    - Damping: X=1, Y=0.5
  Follow: Player Transform
  Add Extension: CinemachineConfiner2D
    - Bounding Shape: PolygonCollider2D (room bounds)

3D Third-Person Camera

FreeLook Camera:
  Follow: Player Transform
  Look At: Player Head/Chest
  Top/Middle/Bottom Rig:
    - Height, Radius per rig
    - Composer aim in each rig
  X Axis: Input from mouse/stick (orbiting)
  Y Axis: Input from mouse/stick (elevation)

State-Driven Camera (Animator)

State-Driven Camera:
  Animated Target: Player Animator
  States:
    Idle → VCam_Idle (wide shot)
    Run → VCam_Run (further back)
    Combat → VCam_Combat (over shoulder)

Camera Blending

• Default blend: 2 seconds, EaseInOut
• Custom blends per transition (from VCam A to VCam B)
• Cut (0 seconds) for instant switches

Cinemachine Impulse (Screen Shake)

// Source: generates impulse
[SerializeField] private CinemachineImpulseSource _impulseSource;

public void OnExplosion()
{
    _impulseSource.GenerateImpulse();
}

Add `CinemachineImpulseListener` extension to virtual cameras that should respond.

Noise (Handheld Feel)

Add `CinemachineBasicMultiChannelPerlin` to virtual camera:

• Profile: `6D Shake` or `Handheld_normal_mild`
• Amplitude/Frequency for intensity

Code Control

// Switch cameras by priority
_combatCamera.Priority = 20; // Higher = active
_exploreCamera.Priority = 10;

// Change follow target
_virtualCamera.Follow = newTarget;
_virtualCamera.LookAt = newTarget;

Confiner

• **2D:** `CinemachineConfiner2D` + `PolygonCollider2D` (set collider to trigger, non-physics layer)
• **3D:** `CinemachineConfiner` + `BoxCollider` or `MeshCollider` volume