unity-cinemachine

Unity Cinemachine（カメラシステム）

Unity 6.3 LTS -- Cinemachine 3.1 パッケージに基づいています 重要：Cinemachine 3.x では、CinemachineVirtualCamera が CinemachineCamera に名称変更されました

基本概念

Cinemachine は、実行時に Unity のカメラをプロシージャルに制御します。カスタムのカメラスクリプトを書く代わりに、再利用可能なコンポーネントを組み合わせてカメラの動作を構成します。

アーキテクチャ

1. CinemachineBrain -- メインカメラに追加します。最も優先度の高い有効な CinemachineCamera に基づいて Unity カメラを制御します
2. CinemachineCamera -- 希望する位置、回転、レンズを記述する軽量な仮想カメラです（v2 の CinemachineVirtualCamera に代わるものです）
3. 優先度システム -- 有効な CinemachineCamera のうち、最も優先度の高いものが選択されます
4. パイプラインステージ -- Body（位置）、Aim（回転）、Noise の各ステージで、最終的なカメラの状態を計算します

名前空間

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

最小限のセットアップ

1. メインカメラに CinemachineBrain を追加します
2. CinemachineCamera を含む GameObject を作成します
3. Follow ターゲットを設定し、必要に応じて LookAt ターゲットも設定します
4. 必要に応じて Body/Aim コンポーネントを追加します

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;
    }
}

カメラのセットアップパターン

基本的な追従カメラ

CinemachineCamera と CinemachineFollow を組み合わせます。Follow ターゲットにプレイヤーを設定します。

// 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);

三人称カメラ

衝突に対応する三人称カメラには CinemachineThirdPersonFollow を使用します。

プロパティ	説明
ShoulderOffset	ローカル空間での追従ターゲットからのオフセット
CameraDistance	ショルダーポイントからの距離
CameraSide	0＝左、0.5＝中央、1＝右
CameraRadius	衝突検出の半径
DampingIntoCollision	衝突によって近づくときのダンピング
DampingFromCollision	衝突後に元の位置へ戻るときのダンピング

オービタル／フリーカメラ

プレイヤー入力で制御する、ターゲットの周囲を回転するカメラには CinemachineOrbitalFollow を使用します。Cinemachine 3.x では、FreeLook は独立したコンポーネントではなくなりました。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 カメラ

スムーズな 2D 追従には、デッドゾーンとダンピングを設定した CinemachinePositionComposer を使用します。

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 コンポーネント（位置追跡）

Body コンポーネントは、カメラの位置がターゲットをどのように追従するかを制御します。各 CinemachineCamera に Body コンポーネントを 1 つ追加します。

コンポーネント	使用例
CinemachineFollow	ダンピングを伴うシンプルなオフセット追従
CinemachineThirdPersonFollow	衝突に対応する三人称カメラ
CinemachineOrbitalFollow	ターゲットの周囲を回転（FreeLook スタイル）
CinemachinePositionComposer	デッドゾーンを使ったスクリーンスペースでのフレーミング
CinemachineHardLockToTarget	ターゲットに位置を正確に固定（ダンピングなし）
CinemachineTrackedDolly	SplineContainer のパスに沿って追従

CinemachineTrackedDolly

カメラを SplineContainer のパスに沿って移動させます。カットシーン用のレール、レーシングゲーム、横スクロールゲームに便利です。

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 コンポーネント（回転）

Aim コンポーネントは、カメラが LookAt ターゲットを向くように回転する方法を制御します。各 CinemachineCamera に Aim コンポーネントを 1 つ追加します。

コンポーネント	使用例
CinemachineRotationComposer	デッドゾーンとダンピングを使ったソフトゾーンでの照準
CinemachineHardLookAt	常にターゲットを正確に向く（ダンピングなし）
CinemachinePanTilt	入力軸による手動のパン／チルト（一人称視点）
CinemachineGroupFraming	CinemachineTargetGroup を自動でフレーミング

CinemachinePanTilt

一人称視点または手動照準のカメラに使用します。

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

カメラブレンド

CinemachineBrain がスムーズな切り替えを自動で処理します。

ブレンドスタイル

スタイル	説明
Cut	即時切り替え
EaseInOut	滑らかな加速／減速（最も一般的）
EaseIn / EaseOut	片側のみのイージング
HardIn / HardOut	開始または終了時に急な変化
Linear	一定速度
Custom	ユーザー定義の AnimationCurve

カメラの切り替え

// 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);

カメラのペアごとにブレンドをカスタマイズするには、CinemachineBlenderSettings アセットを CinemachineBrain.CustomBlends に割り当てます。

状態駆動カメラ

CinemachineStateDrivenCamera は、Animator の状態を子 CinemachineCamera にマッピングします。Animator が遷移すると、対応するカメラが自動的に有効になります。

セットアップ

1. CinemachineStateDrivenCamera を持つ親 GameObject を作成します
2. それぞれに CinemachineCamera を持つ子 GameObject を追加します
3. 状態遷移を駆動する Animator を割り当てます
4. Inspector で各 Animator の状態を子カメラにマッピングします

ユースケース

• 戦闘 -- Animator が Combat 状態に入ったとき、肩越しカメラに切り替えます
• 乗り物 -- 運転時と後退時で異なるカメラを使用します
• ステルス -- Crouch 状態のときに FOV を広くします
• 会話 -- 会話状態用のクローズアップカメラ

カメラシェイク（インパルスシステム）

コンポーネント	役割
CinemachineImpulseSource	位置に応じたインパルス信号を生成します
CinemachineImpulseListener	CinemachineCamera でインパルスを受信します

インパルスの生成

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
    }
}

リスナーのプロパティ

プロパティ	説明
Gain	インパルスの倍率（0＝無視、1＝最大）
Use2DDistance	距離減衰に 2D 距離を使用します
ChannelMask	受信するインパルスチャンネル

ノイズ（プロシージャルシェイク）

CinemachineBasicMultiChannelPerlin は、継続的なプロシージャルノイズ（手持ち撮影のような揺れ、アイドル時の呼吸）を追加します。

プロファイル	ユースケース
6D Shake	位置と回転の全方向
Handheld_normal_mild	控えめな手持ち撮影のような揺れ
Handheld_normal_strong	強めの手持ち撮影のような揺れ

CinemachineTargetGroup

単一のカメラで複数のターゲットをフレームに収めます。

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

入力処理

Cinemachine 3.x は、カメラ制御入力に InputAxis を使用します。Unity の Input System パッケージと連携します。

CinemachineInputAxisController

このコンポーネントを CinemachineOrbitalFollow または CinemachinePanTilt と一緒に追加します。兄弟コンポーネントの軸を自動検出し、Input System のアクションに接続します。

カスタム入力プロバイダー

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"
        });
    }
}

よくあるパターン

衝突回避機能付き三人称カメラ

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);

トリガーゾーンでのカメラ切り替え

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;
    }
}

カットシーンのカメラシーケンス

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]);
        }
    }
}

画面分割のセットアップ

// 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;

爆発時のカメラシェイク

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

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

アンチパターン

アンチパターン	代わりにこちらを使用
CinemachineVirtualCamera（v2）を使用する	CinemachineCamera
using Cinemachine; 名前空間	using Unity.Cinemachine;
Camera.main.transform を直接変更する	CinemachineCamera を変更します。Camera は Brain が駆動します
すべてのカメラで同じ優先度を設定する	優先度をそれぞれ異なる値にします
Main Camera に CinemachineBrain がない	必ず CinemachineBrain を追加します
カメラ遷移に手動で Lerp を使用する	優先度を切り替えます。ブレンドは Brain が処理します
CinemachineTransposer（v2）	CinemachineFollow
CinemachineComposer（v2）	CinemachineRotationComposer
CinemachineFramingTransposer（v2）	CinemachinePositionComposer

API クイックリファレンス

クラス	目的
CinemachineCamera	仮想カメラ（以前は CinemachineVirtualCamera）
CinemachineBrain	アクティブな仮想カメラに基づいて Unity Camera を制御
CinemachineFollow	オフセットボディ（以前は CinemachineTransposer）
CinemachineThirdPersonFollow	衝突を考慮する三人称ボディ
CinemachineOrbitalFollow	FreeLook 用のオービットボディ
CinemachinePositionComposer	スクリーンスペースのフレーミング（以前は FramingTransposer）
CinemachineTrackedDolly	Spline パスに沿って追従
CinemachineRotationComposer	ソフトゾーンのエイム（以前は CinemachineComposer）
CinemachineHardLookAt	ターゲットにエイムを固定
CinemachinePanTilt	手動のパン／チルトエイム
CinemachineGroupFraming	ターゲットグループを自動でフレーミング
CinemachineImpulseSource	カメラシェイクを生成
CinemachineImpulseListener	カメラでシェイクを受信
CinemachineBasicMultiChannelPerlin	継続的なプロシージャルノイズ
CinemachineStateDrivenCamera	Animator の状態をカメラに割り当て
CinemachineTargetGroup	複数のターゲットをグループ化
CinemachineBlenderSettings	カスタムブレンドの定義
CinemachineInputAxisController	Input System を軸に接続
ICinemachineCamera	仮想カメラのインターフェース

v2 から v3 への移行リファレンス

Cinemachine 2.x	Cinemachine 3.x
CinemachineVirtualCamera	CinemachineCamera
CinemachineFreeLook	CinemachineCamera + CinemachineOrbitalFollow
CinemachineTransposer	CinemachineFollow
CinemachineComposer	CinemachineRotationComposer
CinemachineFramingTransposer	CinemachinePositionComposer
CinemachinePOV	CinemachinePanTilt
CinemachineGroupComposer	CinemachineGroupFraming
using Cinemachine	using Unity.Cinemachine
m_Follow / m_LookAt	Follow / LookAt
m_Priority	Priority.Value

関連スキル

• アニメーションステートマシンについては、unity-animation を参照してください
• レンダリング／カメラについては、unity-graphics を参照してください
• Timeline については、unity-animation の references/timeline.md を参照してください
• 入力システムとの統合については、unity-input を参照してください

追加リソース

• references/cinemachine-api.md を参照してください