t1k:unity:rendering:cinemachine

Field	Value
Module	`rendering`
Version	`3.1.7`
Effort	`high`
Tools	—

Keywords: camera, Cinemachine, cinematics, unity

How to invoke

/t1k:unity:rendering:cinemachine

Unity Cinemachine 3.x

com.unity.cinemachine v3.x (Unity 6). Namespace: Unity.Cinemachine (NOT Cinemachine).

Architecture

CinemachineBrain (on Main Camera)
  └── Evaluates all CinemachineCamera components → blends → drives Unity Camera

CinemachineCamera (empty GameObject — NOT the rendering camera)
  ├── Body → CinemachineFollow | CinemachineOrbitalFollow | CinemachineSplineDolly
  ├── Aim  → CinemachineRotationComposer | HardLookAt
  └── Noise → CinemachineBasicMultiChannelPerlin

v2 → v3 Migration

v2	v3
`CinemachineVirtualCamera`	`CinemachineCamera`
`CinemachineFreeLook`	`CinemachineCamera` + `CinemachineOrbitalFollow`
`Transposer`	`CinemachineFollow`
`Composer`	`CinemachineRotationComposer`
`TrackedDolly`	`CinemachineSplineDolly`
`CinemachinePath`	`SplineContainer` (Unity Splines)
`using Cinemachine;`	`using Unity.Cinemachine;`

Basic Follow Camera

CinemachineCamera  (Follow: target, LookAt: target, Priority: 10)
+ CinemachineFollow  (Offset: 0,5,-10 | Damping: 1,1,1 | BindingMode: LockToTarget)
+ CinemachineRotationComposer  (TrackedPoint: 0,1,0 | Damping: 0.5,0.5)

Third-Person (OrbitalFollow / FreeLook replacement)

CinemachineCamera + CinemachineOrbitalFollow
  Radius: 5 | Orbits: Top(4h,2r) Center(5h,1r) Bottom(3h,0r)
  TargetOffset: (0,1,0)   ← v3.1+
+ CinemachineInputAxisController  (PlayerIndex: -1 for single-player)
+ CinemachineRotationComposer  (TrackedPoint: 0,1.5,0)

Blending

followCam.Priority = 10;
cutsceneCam.Priority = 20;   // higher = active; or enable/disable GameObjects

Custom blends: Brain → Custom Blends asset (CinemachineBlendDefinition per pair). Default: EaseInOut 2s. Cut = 0s.

Camera Shake

Noise (continuous) — CinemachineBasicMultiChannelPerlin on CinemachineCamera:

var perlin = cam.GetComponent<CinemachineBasicMultiChannelPerlin>();
perlin.AmplitudeGain = 2f;  perlin.FrequencyGain = 1f;
// Profiles: 6D Shake | Handheld_tele_mild | Wobble

Impulse (event-driven, preferred for hits/explosions):

impulseSource.GenerateImpulse(force);
impulseSource.GenerateImpulseWithVelocity(direction * force);
// Add CinemachineImpulseListener to camera; use Channels to filter

Dolly / Spline

1. Requires com.unity.splines — GameObject → Spline → Draw Spline
2. Add CinemachineCamera + CinemachineSplineDolly; assign SplineContainer
3. AutoDolly: ClosestPointOnPath (track target) or FixedSpeed

dolly.CameraPosition = 0.5f;  // 0–1 normalized along spline

State-Driven Camera

CinemachineStateDrivenCamera: AnimatedTarget=[Animator] · DefaultBlend=EaseInOut 0.5s · States: “Idle”→IdleCam | “Run”→RunCam | “Combat”→CombatCam. State names are case-sensitive.

DOTS / ECS Integration

Cinemachine needs managed Transform. Proxy pattern: sync ECS LocalTransform → proxy position → assign as CinemachineCamera.Follow in LateUpdate. → See dots-environment for setup.

DOTS Bridge Pattern

CinemachineCameraBridge (MonoBehaviour) reads DOTS singletons in LateUpdate:

CameraTarget → proxy Transform → CinemachineCamera.Follow
CameraTrauma → impulseSource.GenerateImpulse() when Trauma > threshold
HitStopEvent → Time.timeScale for hit-pause
CameraAccessibility.ReduceMotion → suppresses impulse

Namespace alias required: using CameraTarget = DOTSRPG.Core.CameraTarget;

Auto-Battle Camera Setup

CinemachinePositionComposer: DeadZone (0.3, 0.3) · HardLimits (0.95, 0.95) · Damping 0.5 · Lookahead 0.3s CinemachineConfiner2D: BoxCollider2D on arena bounds · main scene only (not SubScene) CinemachineBrain: DefaultBlend EaseInOut 1.5s CinemachineAutoZoom (MonoBehaviour): queries alive entities → XZ AABB → cam.orthographicSize

Gotchas

Namespace: using Unity.Cinemachine; — using Cinemachine; causes CS0246
CinemachineBrain missing: nothing works — must be on Main Camera
Equal priority: undefined behavior — use distinct integer values
SuppressInputWhileBlending: set true on OrbitalFollow to stop axis drift during blends
SplineDolly needs com.unity.splines installed separately
v2 tutorials: component names changed — always verify package version
CameraTarget ambiguity: Unity.Cinemachine.CameraTarget vs DOTSRPG.Core.CameraTarget — always alias the DOTS one

unity-animation — Timeline / Animator-driven cameras
unity-input-system — Input bindings for camera control
unity-urp — Post-processing volumes with cameras
dots-environment — Scene camera setup in DOTS projects

Reference	Contents
`references/camera-recipes.md`	Dolly cutscene, split-screen, minimap, Timeline, DOTS proxy, CinemachineCameraBridge, Confiner2D, trauma impulse, boss focus