Class CinemachineVirtualCameraBase

Base class for a Monobehaviour that represents a Virtual Camera within the Unity scene.

This is intended to be attached to an empty Transform GameObject. Inherited classes can be either standalone virtual cameras such as CinemachineCamera, or meta-cameras such as CinemachineClearShot or CinemachineBlendListCamera.

A CinemachineVirtualCameraBase exposes an OutputChannel property. When the behaviour is enabled in the game, the Virtual Camera is automatically placed in a queue maintained by the static CinemachineCore singleton. The queue is sorted by priority. When a Unity camera is equipped with a CinemachineBrain behaviour, the brain will choose the camera at the head of the queue. If you have multiple Unity cameras with CinemachineBrain behaviours (say in a split-screen context), then you can filter the queue by setting the culling flags on the virtual cameras. The culling mask of the Unity Camera will then act as a filter for the brain. Apart from this, there is nothing that prevents a virtual camera from controlling multiple Unity cameras simultaneously.

Inheritance
object
Object
Component
Behaviour
MonoBehaviour
CinemachineVirtualCameraBase
CinemachineCamera
CinemachineCameraManagerBase
CinemachineExternalCamera
CinemachineFreeLook
CinemachineVirtualCamera
Implements
Inherited Members
Object.InstantiateAsync<T>(T)
Object.InstantiateAsync<T>(T, Transform)
Object.InstantiateAsync<T>(T, Vector3, Quaternion)
Object.InstantiateAsync<T>(T, Transform, Vector3, Quaternion)
Object.InstantiateAsync<T>(T, InstantiateParameters)
Object.InstantiateAsync<T>(T, Vector3, Quaternion, InstantiateParameters)
Object.Instantiate<T>(T, InstantiateParameters)
Object.Instantiate<T>(T, Vector3, Quaternion, InstantiateParameters)
Object.FindObjectsByType<T>(FindObjectsSortMode)
Object.FindObjectsByType<T>(FindObjectsInactive, FindObjectsSortMode)
Object.FindFirstObjectByType<T>()
Object.FindAnyObjectByType<T>()
Object.FindFirstObjectByType<T>(FindObjectsInactive)
Object.FindAnyObjectByType<T>(FindObjectsInactive)
Namespace: Unity.Cinemachine
Assembly: Unity.Cinemachine.dll
Syntax
public abstract class CinemachineVirtualCameraBase : MonoBehaviour, ICinemachineCamera

Fields

FollowTargetAttachment

This must be set every frame at the start of the pipeline to relax the virtual camera's attachment to the target. Range is 0...1.
1 is full attachment, and is the normal state. 0 is no attachment, and virtual camera will behave as if no Follow targets are set.

Declaration
[NonSerialized]
public float FollowTargetAttachment
Field Value
Type Description
float

LookAtTargetAttachment

This must be set every frame at the start of the pipeline to relax the virtual camera's attachment to the target. Range is 0...1.
1 is full attachment, and is the normal state. 0 is no attachment, and virtual camera will behave as if no LookAt targets are set.

Declaration
[NonSerialized]
public float LookAtTargetAttachment
Field Value
Type Description
float

OutputChannel

The output channel functions like Unity layers. Use it to filter the output of CinemachineCameras to different CinemachineBrains, for instance in a multi-screen environemnt.

Declaration
[Tooltip("The output channel functions like Unity layers.  Use it to filter the output of CinemachineCameras to different CinemachineBrains, for instance in a multi-screen environemnt.")]
public OutputChannels OutputChannel
Field Value
Type Description
OutputChannels

Priority

Priority can be used to control which Cm Camera is live when multiple CM Cameras are active simultaneously. The most-recently-activated CinemachineCamera will take control, unless there is another Cm Camera active with a higher priority. In general, the most-recently-activated highest-priority CinemachineCamera will control the main camera.

The default priority value is 0. Often it is sufficient to leave the default setting.
In special cases where you want a CinemachineCamera to have a higher or lower priority value than 0, you can set it here.

Example of setting priority value directly: 

cam.Priority.Value = 5;

Example of using the implicit operator to set priority value: 

cam.Priority = 5;
Declaration
[Tooltip("Priority can be used to control which Cm Camera is live when multiple CM Cameras are active simultaneously.  The most-recently-activated CinemachineCamera will take control, unless there is another Cm Camera active with a higher priority.  In general, the most-recently-activated highest-priority CinemachineCamera will control the main camera. \n\nThe default priority is value 0.  Often it is sufficient to leave the default setting.  In special cases where you want a CinemachineCamera to have a higher or lower priority value than 0, you can set it here.")]
[EnabledProperty("Enabled", "(using default)")]
public PrioritySettings Priority
Field Value
Type Description
PrioritySettings

StandbyUpdate

When the virtual camera is not live, this is how often the virtual camera will be updated. Set this to tune for performance. Most of the time Never is fine, unless the virtual camera is doing shot evaluation.

Declaration
[Tooltip("When the virtual camera is not live, this is how often the virtual camera will be updated.  Set this to tune for performance. Most of the time Never is fine, unless the virtual camera is doing shot evaluation.")]
[FormerlySerializedAs("m_StandbyUpdate")]
public CinemachineVirtualCameraBase.StandbyUpdateMode StandbyUpdate
Field Value
Type Description
CinemachineVirtualCameraBase.StandbyUpdateMode

Properties

Description

Gets a brief debug description of this virtual camera, for use when displaying debug info

Declaration
public virtual string Description { get; }
Property Value
Type Description
string

Follow

Get the Follow target for the Body component in the Cinemachine pipeline.

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

FollowTargetAsGroup

Get Follow target as ICinemachineTargetGroup, or null if target is not a ICinemachineTargetGroup

Declaration
public ICinemachineTargetGroup FollowTargetAsGroup { get; }
Property Value
Type Description
ICinemachineTargetGroup

FollowTargetAsVcam

Get Follow target as CinemachineVirtualCameraBase, or null if target is not a CinemachineVirtualCameraBase

Declaration
public CinemachineVirtualCameraBase FollowTargetAsVcam { get; }
Property Value
Type Description
CinemachineVirtualCameraBase

FollowTargetChanged

This property is true if the Follow target was changed this frame.

Declaration
public bool FollowTargetChanged { get; }
Property Value
Type Description
bool

IsDprecated

Helper for upgrading from CM2

Declaration
protected virtual bool IsDprecated { get; }
Property Value
Type Description
bool

IsLive

Returns true if this camera is currently live for some CinemachineBrain.

Declaration
public bool IsLive { get; }
Property Value
Type Description
bool

IsValid

Returns false if the object has been deleted

Declaration
public bool IsValid { get; }
Property Value
Type Description
bool

LookAt

Get the LookAt target for the Aim component in the Cinemachine pipeline.

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

LookAtTargetAsGroup

Get LookAt target as ICinemachineTargetGroup, or null if target is not a ICinemachineTargetGroup

Declaration
public ICinemachineTargetGroup LookAtTargetAsGroup { get; }
Property Value
Type Description
ICinemachineTargetGroup

LookAtTargetAsVcam

Get LookAt target as CinemachineVirtualCameraBase, or null if target is not a CinemachineVirtualCameraBase

Declaration
public CinemachineVirtualCameraBase LookAtTargetAsVcam { get; }
Property Value
Type Description
CinemachineVirtualCameraBase

LookAtTargetChanged

This property is true if the LookAtTarget was changed this frame.

Declaration
public bool LookAtTargetChanged { get; }
Property Value
Type Description
bool

Name

Get the name of the Virtual Camera. Base implementation returns a cache of the owner GameObject's name.

Declaration
public string Name { get; }
Property Value
Type Description
string

ParentCamera

Support for meta-virtual-cameras. This is the situation where a virtual camera is in fact the public face of a private army of virtual cameras, which it manages on its own. This method gets the VirtualCamera owner, if any. Private armies are implemented as Transform children of the parent vcam.

Declaration
public ICinemachineMixer ParentCamera { get; }
Property Value
Type Description
ICinemachineMixer

PreviousStateIsValid

Set this to force the next update to ignore state from the previous frame.
This is useful, for example, if you want to cancel damping or other time-based processing.

Declaration
public virtual bool PreviousStateIsValid { get; set; }
Property Value
Type Description
bool

State

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

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

Methods

CancelDamping(bool)

Temporarily cancel damping for this frame. The camera will sanp to its target position when it is updated.

Declaration
public void CancelDamping(bool updateNow = false)
Parameters
Type Name Description
bool updateNow

If true, snap the camera to its target immediately, otherwise wait until the end of the frame when cameras are normally updated.

DetachedFollowTargetDamp(float, float, float)

Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

Declaration
public float DetachedFollowTargetDamp(float initial, float dampTime, float deltaTime)
Parameters
Type Name Description
float initial

The amount that will be damped
float dampTime

The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage
float deltaTime

The time over which to damp
Returns
Type Description
float

The damped amount. This will be the original amount scaled by a value between 0 and 1.

DetachedFollowTargetDamp(Vector3, float, float)

Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

Declaration
public Vector3 DetachedFollowTargetDamp(Vector3 initial, float dampTime, float deltaTime)
Parameters
Type Name Description
Vector3 initial

The amount that will be damped
float dampTime

The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage
float deltaTime

The time over which to damp
Returns
Type Description
Vector3

The damped amount. This will be the original amount scaled by a value between 0 and 1.

DetachedFollowTargetDamp(Vector3, Vector3, float)

Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

Declaration
public Vector3 DetachedFollowTargetDamp(Vector3 initial, Vector3 dampTime, float deltaTime)
Parameters
Type Name Description
Vector3 initial

The amount that will be damped
Vector3 dampTime

The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage
float deltaTime

The time over which to damp
Returns
Type Description
Vector3

The damped amount. This will be the original amount scaled by a value between 0 and 1.

DetachedLookAtTargetDamp(float, float, float)

Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

Declaration
public float DetachedLookAtTargetDamp(float initial, float dampTime, float deltaTime)
Parameters
Type Name Description
float initial

The amount that will be damped
float dampTime

The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage
float deltaTime

The time over which to damp
Returns
Type Description
float

The damped amount. This will be the original amount scaled by a value between 0 and 1.

DetachedLookAtTargetDamp(Vector3, float, float)

Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

Declaration
public Vector3 DetachedLookAtTargetDamp(Vector3 initial, float dampTime, float deltaTime)
Parameters
Type Name Description
Vector3 initial

The amount that will be damped
float dampTime

The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage
float deltaTime

The time over which to damp
Returns
Type Description
Vector3

The damped amount. This will be the original amount scaled by a value between 0 and 1.

DetachedLookAtTargetDamp(Vector3, Vector3, float)

Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

Declaration
public Vector3 DetachedLookAtTargetDamp(Vector3 initial, Vector3 dampTime, float deltaTime)
Parameters
Type Name Description
Vector3 initial

The amount that will be damped
Vector3 dampTime

The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage
float deltaTime

The time over which to damp
Returns
Type Description
Vector3

The damped amount. This will be the original amount scaled by a value between 0 and 1.

ForceCameraPosition(Vector3, Quaternion)

Force the virtual camera to assume a given position and orientation

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

World-space position to take
Quaternion rot

World-space orientation to take

GetCinemachineComponent(Stage)

Get the component set for a specific stage in the pipeline.

Declaration
public virtual 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 present.

GetMaxDampTime()

Query components and extensions for the maximum damping time. Base class implementation queries extensions. Only used in editor for timeline scrubbing.

Declaration
public virtual float GetMaxDampTime()
Returns
Type Description
float

Highest damping setting in this vcam

InternalUpdateCameraState(Vector3, float)

Internal use only.
Called by CinemachineCore at designated update time so the vcam can position itself and track its targets. Do not call this method. Let the framework do it at the appropriate time

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

Default world Up, set by the CinemachineBrain
float deltaTime

Delta time for time-based effects (ignore if less than 0)

InvokeOnTransitionInExtensions(ICinemachineCamera, Vector3, float)

Invokes the OnTransitionFromCamera for all extensions on this camera

Declaration
protected bool InvokeOnTransitionInExtensions(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
float deltaTime

Delta time for time-based effects (ignore if less than or equal to 0)
Returns
Type Description
bool

True to request a vcam update of internal state

InvokePostPipelineStageCallback(CinemachineVirtualCameraBase, Stage, ref CameraState, float)

Invokes the PostPipelineStageDelegate for this camera, and up the hierarchy for all parent cameras (if any). Implementation must be sure to call this after each pipeline stage, to allow other services to hook into the pipeline. See CinemachineCore.Stage.

Declaration
protected void InvokePostPipelineStageCallback(CinemachineVirtualCameraBase vcam, CinemachineCore.Stage stage, ref CameraState newState, float deltaTime)
Parameters
Type Name Description
CinemachineVirtualCameraBase vcam

The virtual camera being processed
CinemachineCore.Stage stage

The current pipeline stage
CameraState newState

The current virtual camera state
float deltaTime

The current applicable deltaTime

InvokePrePipelineMutateCameraStateCallback(CinemachineVirtualCameraBase, ref CameraState, float)

Invokes the PrePipelineMutateCameraStateCallback for this camera, and up the hierarchy for all parent cameras (if any). Implementation must be sure to call this after each pipeline stage, to allow other services to hook into the pipeline. See CinemachineCore.Stage.

Declaration
protected void InvokePrePipelineMutateCameraStateCallback(CinemachineVirtualCameraBase vcam, ref CameraState newState, float deltaTime)
Parameters
Type Name Description
CinemachineVirtualCameraBase vcam

The virtual camera being processed
CameraState newState

The current virtual camera state
float deltaTime

The current applicable deltaTime

IsParticipatingInBlend()

Check to see whether this camera is currently participating in a blend within its parent manager or in a CinemacineBrain

Declaration
public bool IsParticipatingInBlend()
Returns
Type Description
bool

True if the camera is participating in a blend

MoveToTopOfPrioritySubqueue()

When multiple virtual cameras have the highest priority, there is sometimes the need to push one to the top, making it the current Live camera if it shares the highest priority in the queue with its peers.

 This happens automatically when a
 new vcam is enabled: the most recent one goes to the top of the priority sub-queue.
 Use this method to push a vcam to the top of its priority peers.
 If it and its peers share the highest priority, then this vcam will become Live.
Declaration
[Obsolete("Please use Prioritize()")]
public void MoveToTopOfPrioritySubqueue()

OnCameraActivated(ActivationEventParams)

Notification that this camera is being activated. This is sent to the newly activated camera.
Multiple camera may be active simultaneously for a while, if blending. evt.IncomingCamera will always be "this".

Declaration
public virtual void OnCameraActivated(ICinemachineCamera.ActivationEventParams evt)
Parameters
Type Name Description
ICinemachineCamera.ActivationEventParams evt

Context for the camera activation.

OnDestroy()

Maintains the global vcam registry. Always call the base class implementation.

Declaration
protected virtual void OnDestroy()

OnDisable()

Base class implementation makes sure the priority queue remains up-to-date.

Declaration
protected virtual void OnDisable()

OnEnable()

Base class implementation adds the virtual camera from the priority queue.

Declaration
protected virtual void OnEnable()

OnTargetObjectWarped(Transform, Vector3)

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

Declaration
public virtual 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

OnTransformParentChanged()

Base class implementation makes sure the priority queue remains up-to-date.

Declaration
protected virtual void OnTransformParentChanged()

OnTransitionFromCamera(ICinemachineCamera, Vector3, float)

Notification that this virtual camera is going live. Base class implementation must be called by any overridden method.

Declaration
public virtual 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
float deltaTime

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

PerformLegacyUpgrade(int)

Override this to handle any upgrades necessitated by a streaming version change. Note that since this method is not called from the main thread, there are many things it cannot do, including checking a unity object for null.

Declaration
protected virtual void PerformLegacyUpgrade(int streamedVersion)
Parameters
Type Name Description
int streamedVersion

The version that was streamed

Prioritize()

When multiple Cm Cameras have the highest priority, there is sometimes the need to push one to the top, making it the current Live camera if it shares the highest priority in the queue with its peers.

 This happens automatically when a
 new CinemachineCamera is enabled: the most recent one goes to the top of the priority sub-queue.
 Use this method to push a camera to the top of its priority peers.
 If it and its peers share the highest priority, then this vcam will become Live.
Declaration
public void Prioritize()

PullStateFromVirtualCamera(Vector3, ref LensSettings)

Create a camera state based on the current transform of this vcam

Declaration
protected CameraState PullStateFromVirtualCamera(Vector3 worldUp, ref LensSettings lens)
Parameters
Type Name Description
Vector3 worldUp

Current World Up direction, as provided by the brain
LensSettings lens

Lens settings to serve as base, will be combined with lens from brain, if any
Returns
Type Description
CameraState

ResolveFollow(Transform)

Returns this vcam's Follow target, or if that is null, will retrun the parent vcam's Follow target.

Declaration
public Transform ResolveFollow(Transform localFollow)
Parameters
Type Name Description
Transform localFollow

This vcam's Follow value.
Returns
Type Description
Transform

The same value, or the parent's if null and a parent exists.

ResolveLookAt(Transform)

Returns this vcam's LookAt target, or if that is null, will return the parent vcam's LookAt target.

Declaration
public Transform ResolveLookAt(Transform localLookAt)
Parameters
Type Name Description
Transform localLookAt

This vcam's LookAt value.
Returns
Type Description
Transform

The same value, or the parent's if null and a parent exists.

Start()

Derived classes should call base class implementation.

Declaration
protected virtual void Start()

Update()

Base class implementation makes sure the priority queue remains up-to-date.

Declaration
protected virtual void Update()

UpdateCameraState(Vector3, float)

Update the camera's state. The implementation must guarantee against multiple calls per frame, and should use CinemachineCore.UpdateVirtualCamera(ICinemachineCamera, Vector3, float), which has protection against multiple calls per frame.

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

Default world Up, set by the CinemachineBrain
float deltaTime

Delta time for time-based effects (ignore if less than 0)

UpdateTargetCache()

Call this from InternalUpdateCameraState() to check for changed targets and update the target cache. This is needed for tracking when a target object changes.

Declaration
public void UpdateTargetCache()

Implements

Extension Methods