Class CinemachineVirtualCamera

This behaviour is intended to be attached to an empty Transform GameObject, and it represents a Virtual Camera within the Unity scene.

The Virtual Camera will animate its Transform according to the rules contained in its CinemachineComponent pipeline (Aim, Body, and Noise). When the virtual camera is Live, the Unity camera will assume the position and orientation of the virtual camera.

A virtual camera is not a camera. Instead, it can be thought of as a camera controller, not unlike a cameraman. It can drive the Unity Camera and control its position, orientation, lens settings, and PostProcessing effects. Each Virtual Camera owns its own Cinemachine Component Pipeline, through which you provide the instructions for dynamically tracking specific game objects.

A virtual camera is very lightweight, and does no rendering of its own. It merely tracks interesting GameObjects, and positions itself accordingly. A typical game can have dozens of virtual cameras, each set up to follow a particular character or capture a particular event.

A Virtual Camera can be in any of three states:

  • Live: The virtual camera is actively controlling the Unity Camera. The virtual camera is tracking its targets and being updated every frame.
  • Standby: The virtual camera is tracking its targets and being updated every frame, but no Unity Camera is actively being controlled by it. This is the state of a virtual camera that is enabled in the scene but perhaps at a lower priority than the Live virtual camera.
  • Disabled: The virtual camera is present but disabled in the scene. It is not actively tracking its targets and so consumes no processing power. However, the virtual camera can be made live from the Timeline.

The Unity Camera can be driven by any virtual camera in the scene. The game logic can choose the virtual camera to make live by manipulating the virtual cameras' enabled flags and their priorities, based on game logic.

In order to be driven by a virtual camera, the Unity Camera must have a CinemachineBrain behaviour, which will select the most eligible virtual camera based on its priority or on other criteria, and will manage blending.

Inheritance
Object
Object
Component
Behaviour
MonoBehaviour
CinemachineVirtualCameraBase
CinemachineVirtualCamera
Inherited Members
Namespace: Cinemachine
Syntax
[DocumentationSorting(DocumentationSortingAttribute.Level.UserRef)]
[DisallowMultipleComponent]
[ExecuteAlways]
[ExcludeFromPreset]
[AddComponentMenu("Cinemachine/CinemachineVirtualCamera")]
[HelpURL("https://docs.unity.cn/Packages/com.unity.cinemachine@2.8/manual/CinemachineVirtualCamera.html")]
public class CinemachineVirtualCamera : CinemachineVirtualCameraBase, ICinemachineCamera, ISerializationCallbackReceiver

Fields

CreatePipelineOverride

Override component pipeline creation. This needs to be done by the editor to support Undo. The override must do exactly the same thing as the CreatePipeline method in this class.

Declaration
public static CinemachineVirtualCamera.CreatePipelineDelegate CreatePipelineOverride
Field Value
Type Description
CinemachineVirtualCamera.CreatePipelineDelegate

DestroyPipelineOverride

Override component pipeline destruction. This needs to be done by the editor to support Undo.

Declaration
public static CinemachineVirtualCamera.DestroyPipelineDelegate DestroyPipelineOverride
Field Value
Type Description
CinemachineVirtualCamera.DestroyPipelineDelegate

m_Follow

The object that the camera wants to move with (the Body target). The Body component of the CinemachineComponent pipeline will refer to this target and position the vcam in accordance with rules and settings that are provided to it. If this is null, then the vcam's Transform position will be used.

Declaration
[Tooltip("The object that the camera wants to move with (the Body target).  If this is null, then the vcam's Transform position will define the camera's position.")]
public Transform m_Follow
Field Value
Type Description
Transform

m_Lens

Specifies the LensSettings of this Virtual Camera. These settings will be transferred to the Unity camera when the vcam is live.

Declaration
[FormerlySerializedAs("m_LensAttributes")]
[Tooltip("Specifies the lens properties of this Virtual Camera.  This generally mirrors the Unity Camera's lens settings, and will be used to drive the Unity camera when the vcam is active.")]
public LensSettings m_Lens
Field Value
Type Description
LensSettings

m_LookAt

The object that the camera wants to look at (the Aim target). The Aim component of the CinemachineComponent pipeline will refer to this target and orient the vcam in accordance with rules and settings that are provided to it. If this is null, then the vcam's Transform orientation will be used.

Declaration
[Tooltip("The object that the camera wants to look at (the Aim target).  If this is null, then the vcam's Transform orientation will define the camera's orientation.")]
public Transform m_LookAt
Field Value
Type Description
Transform

m_Transitions

Collection of parameters that influence how this virtual camera transitions from other virtual cameras

Declaration
public CinemachineVirtualCameraBase.TransitionParams m_Transitions
Field Value
Type Description
CinemachineVirtualCameraBase.TransitionParams

PipelineName

This is the name of the hidden GameObject that will be created as a child object of the virtual camera. This hidden game object acts as a container for the polymorphic CinemachineComponent pipeline. The Inspector UI for the Virtual Camera provides access to this pipleline, as do the CinemachineComponent-family of public methods in this class. The lifecycle of the pipeline GameObject is managed automatically.

Declaration
public const string PipelineName = "cm"
Field Value
Type Description
String

Properties

Follow

Get the Follow target for the Body component in the Cinemachine pipeline. If this vcam is a part of a meta-camera collection, then the owner's target will be used if the local target is null.

Declaration
public override Transform Follow { get; set; }
Property Value
Type Description
Transform
Overrides

LookAt

Get the LookAt target for the Aim component in the Cinemachine pipeline. If this vcam is a part of a meta-camera collection, then the owner's target will be used if the local target is null.

Declaration
public override Transform LookAt { get; set; }
Property Value
Type Description
Transform
Overrides

State

The CameraState object holds all of the information necessary to position the Unity camera. It is the output of this class.

Declaration
public override CameraState State { get; }
Property Value
Type Description
CameraState
Overrides

Methods

AddCinemachineComponent<T>()

Add a component to the cinemachine pipeline.
Existing components at the new component's stage are removed

Declaration
public T AddCinemachineComponent<T>()
    where T : CinemachineComponentBase
Returns
Type Description
T

The new component
Type Parameters
Name Description
T

The type of component to add

DestroyCinemachineComponent<T>()

Remove a component from the cinemachine pipeline if it's present.

Declaration
public void DestroyCinemachineComponent<T>()
    where T : CinemachineComponentBase
Type Parameters
Name Description
T

The type of component to remove

ForceCameraPosition(Vector3, Quaternion)

Force the virtual camera to assume a given position and orientation

Declaration
public override void ForceCameraPosition(Vector3 pos, Quaternion rot)
Parameters
Type Name Description
Vector3 pos

Worldspace pposition to take
Quaternion rot

Worldspace orientation to take
Overrides

GetCinemachineComponent(CinemachineCore.Stage)

Get the component set for a specific stage.

Declaration
public CinemachineComponentBase GetCinemachineComponent(CinemachineCore.Stage stage)
Parameters
Type Name Description
CinemachineCore.Stage stage

The stage for which we want the component
Returns
Type Description
CinemachineComponentBase

The Cinemachine component for that stage, or null if not defined

GetCinemachineComponent<T>()

Get an existing component of a specific type from the cinemachine pipeline.

Declaration
public T GetCinemachineComponent<T>()
    where T : CinemachineComponentBase
Returns
Type Description
T

The component if it's present, or null
Type Parameters
Name Description
T

The type of component to get

GetComponentOwner()

Get the hidden CinemachinePipeline child object.

Declaration
public Transform GetComponentOwner()
Returns
Type Description
Transform

The hidden CinemachinePipeline child object

GetComponentPipeline()

Get the component pipeline owned by the hidden child pipline container. For most purposes, it is preferable to use the GetCinemachineComponent method.

Declaration
public CinemachineComponentBase[] GetComponentPipeline()
Returns
Type Description
CinemachineComponentBase[]

The component pipeline

GetMaxDampTime()

Query components and extensions for the maximum damping time.

Declaration
public override float GetMaxDampTime()
Returns
Type Description
Single

Highest damping setting in this vcam
Overrides

InternalUpdateCameraState(Vector3, Single)

Internal use only. Do not call this method. Called by CinemachineCore at the appropriate Update time so the vcam can position itself and track its targets. This class will invoke its pipeline and generate a CameraState for this frame.

Declaration
public override void InternalUpdateCameraState(Vector3 worldUp, float deltaTime)
Parameters
Type Name Description
Vector3 worldUp

Effective world up
Single deltaTime

Effective deltaTime
Overrides

InvalidateComponentPipeline()

Editor API: Call this when changing the pipeline from the editor. Will force a rebuild of the pipeline cache.

Declaration
public void InvalidateComponentPipeline()

OnDestroy()

Calls the DestroyPipelineDelegate for destroying the hidden child object, to support undo.

Declaration
protected override void OnDestroy()
Overrides

OnEnable()

Make sure that the pipeline cache is up-to-date.

Declaration
protected override void OnEnable()
Overrides

OnTargetObjectWarped(Transform, Vector3)

This is called to notify the vcam that a target got warped, so that the vcam can update its internal state to make the camera also warp seamlessy.

Declaration
public override void OnTargetObjectWarped(Transform target, Vector3 positionDelta)
Parameters
Type Name Description
Transform target

The object that was warped
Vector3 positionDelta

The amount the target's position changed
Overrides

OnTransitionFromCamera(ICinemachineCamera, Vector3, Single)

If we are transitioning from another vcam, grab the position from it.

Declaration
public override void OnTransitionFromCamera(ICinemachineCamera fromCam, Vector3 worldUp, float deltaTime)
Parameters
Type Name Description
ICinemachineCamera fromCam

The camera being deactivated. May be null.
Vector3 worldUp

Default world Up, set by the CinemachineBrain
Single deltaTime

Delta time for time-based effects (ignore if less than or equal to 0)
Overrides

OnValidate()

Enforce bounds for fields, when changed in inspector.

Declaration
protected override void OnValidate()
Overrides

See Also