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