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 CinemachineVirtualCamera, or meta-cameras such as CinemachineClearShot or CinemachineFreeLook.
A CinemachineVirtualCameraBase exposes a Priority 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.
Inherited Members
Namespace: Cinemachine
Syntax
public abstract class CinemachineVirtualCameraBase : MonoBehaviour, ICinemachineCamera, ISerializationCallbackReceiver
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 |
---|---|
Single |
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 |
---|---|
Single |
m_ExcludedPropertiesInInspector
Inspector control - Use for hiding sections of the Inspector UI.
Declaration
[HideInInspector]
[SerializeField]
public string[] m_ExcludedPropertiesInInspector
Field Value
Type | Description |
---|---|
String[] |
m_LockStageInInspector
Inspector control - Use for enabling sections of the Inspector UI.
Declaration
[HideInInspector]
[SerializeField]
public CinemachineCore.Stage[] m_LockStageInInspector
Field Value
Type | Description |
---|---|
CinemachineCore.Stage[] |
m_Priority
The priority will determine which camera becomes active based on the state of other cameras and this camera. Higher numbers have greater priority.
Declaration
[Tooltip("The priority will determine which camera becomes active based on the state of other cameras and this camera. Higher numbers have greater priority.")]
public int m_Priority
Field Value
Type | Description |
---|---|
Int32 |
m_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.")]
public CinemachineVirtualCameraBase.StandbyUpdateMode m_StandbyUpdate
Field Value
Type | Description |
---|---|
CinemachineVirtualCameraBase.StandbyUpdateMode |
Properties
AbstractFollowTargetGroup
Get Follow target as ICinemachineTargetGroup, or null if target is not a ICinemachineTargetGroup
Declaration
public ICinemachineTargetGroup AbstractFollowTargetGroup { get; }
Property Value
Type | Description |
---|---|
ICinemachineTargetGroup |
AbstractLookAtTargetGroup
Get LookAt target as ICinemachineTargetGroup, or null if target is not a ICinemachineTargetGroup
Declaration
public ICinemachineTargetGroup AbstractLookAtTargetGroup { get; }
Property Value
Type | Description |
---|---|
ICinemachineTargetGroup |
Description
Gets a brief debug description of this virtual camera, for use when displayiong debug info
Declaration
public virtual string Description { get; }
Property Value
Type | Description |
---|---|
String |
Implements
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 |
Implements
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 |
---|---|
Boolean |
IsValid
Returns false if the object has been deleted
Declaration
public bool IsValid { get; }
Property Value
Type | Description |
---|---|
Boolean |
Implements
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 |
Implements
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 |
---|---|
Boolean |
Name
Get the name of the Virtual Camera. Base implementation returns the owner GameObject's name.
Declaration
public string Name { get; }
Property Value
Type | Description |
---|---|
String |
Implements
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 ICinemachineCamera ParentCamera { get; }
Property Value
Type | Description |
---|---|
ICinemachineCamera |
Implements
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 |
---|---|
Boolean |
Priority
Get the Priority of the virtual camera. This determines its placement in the CinemachineCore's queue of eligible shots.
Declaration
public int Priority { get; set; }
Property Value
Type | Description |
---|---|
Int32 |
Implements
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 |
Implements
ValidatingStreamVersion
Version that was last streamed, for upgrading legacy
Declaration
public int ValidatingStreamVersion { get; }
Property Value
Type | Description |
---|---|
Int32 |
VirtualCameraGameObject
The GameObject owner of the Virtual Camera behaviour.
Declaration
public GameObject VirtualCameraGameObject { get; }
Property Value
Type | Description |
---|---|
GameObject |
Implements
Methods
AddExtension(CinemachineExtension)
A delegate to hook into the state calculation pipeline. This will be called after each pipeline stage, to allow others to hook into the pipeline. See CinemachineCore.Stage.
Declaration
public virtual void AddExtension(CinemachineExtension extension)
Parameters
Type | Name | Description |
---|---|---|
CinemachineExtension | extension | The extension to add. |
ApplyPositionBlendMethod(ref CameraState, CinemachineVirtualCameraBase.BlendHint)
Applies a position blend hint to a camera state
Declaration
protected void ApplyPositionBlendMethod(ref CameraState state, CinemachineVirtualCameraBase.BlendHint hint)
Parameters
Type | Name | Description |
---|---|---|
CameraState | state | The state to apply the hint to |
CinemachineVirtualCameraBase.BlendHint | hint | The hint to apply |
CreateBlend(ICinemachineCamera, ICinemachineCamera, CinemachineBlendDefinition, CinemachineBlend)
Create a blend between 2 virtual cameras, taking into account any existing active blend, with special case handling if the new blend is effectively an undo of the current blend
Declaration
protected CinemachineBlend CreateBlend(ICinemachineCamera camA, ICinemachineCamera camB, CinemachineBlendDefinition blendDef, CinemachineBlend activeBlend)
Parameters
Type | Name | Description |
---|---|---|
ICinemachineCamera | camA | Outgoing virtual camera |
ICinemachineCamera | camB | Incoming virtual camera |
CinemachineBlendDefinition | blendDef | Definition of the blend to create |
CinemachineBlend | activeBlend | The current active blend |
Returns
Type | Description |
---|---|
CinemachineBlend | The new blend |
DetachedFollowTargetDamp(Single, Single, Single)
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 |
---|---|---|
Single | initial | The amount that will be damped |
Single | dampTime | The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage |
Single | deltaTime | The time over which to damp |
Returns
Type | Description |
---|---|
Single | The damped amount. This will be the original amount scaled by a value between 0 and 1. |
DetachedFollowTargetDamp(Vector3, Single, Single)
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 |
Single | dampTime | The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage |
Single | 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, Single)
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 |
Single | 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(Single, Single, Single)
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 |
---|---|---|
Single | initial | The amount that will be damped |
Single | dampTime | The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage |
Single | deltaTime | The time over which to damp |
Returns
Type | Description |
---|---|
Single | The damped amount. This will be the original amount scaled by a value between 0 and 1. |
DetachedLookAtTargetDamp(Vector3, Single, Single)
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 |
Single | dampTime | The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage |
Single | 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, Single)
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 |
Single | 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 | Worldspace pposition to take |
Quaternion | rot | Worldspace orientation to take |
GetInputAxisProvider()
Locate the first component that implements AxisState.IInputAxisProvider.
Declaration
public AxisState.IInputAxisProvider GetInputAxisProvider()
Returns
Type | Description |
---|---|
AxisState.IInputAxisProvider | The first AxisState.IInputAxisProvider or null if none |
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 |
---|---|
Single | Highest damping setting in this vcam |
InternalUpdateCameraState(Vector3, Single)
Internal use only. Do not call this method. 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 |
Single | deltaTime | Delta time for time-based effects (ignore if less than 0) |
Implements
InvokeOnTransitionInExtensions(ICinemachineCamera, Vector3, Single)
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 |
Single | deltaTime | Delta time for time-based effects (ignore if less than or equal to 0) |
Returns
Type | Description |
---|---|
Boolean | True to request a vcam update of internal state |
InvokePostPipelineStageCallback(CinemachineVirtualCameraBase, CinemachineCore.Stage, ref CameraState, Single)
Invokes the PostPipelineStageDelegate for this camera, and up the hierarchy for all parent cameras (if any). Implementaion 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 |
Single | deltaTime | The current applicable deltaTime |
InvokePrePipelineMutateCameraStateCallback(CinemachineVirtualCameraBase, ref CameraState, Single)
Invokes the PrePipelineMutateCameraStateCallback for this camera, and up the hierarchy for all parent cameras (if any). Implementaion 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 |
Single | deltaTime | The current applicable deltaTime |
IsLiveChild(ICinemachineCamera, Boolean)
Check whether the vcam a live child of this camera. This base class implementation always returns false.
Declaration
public virtual bool IsLiveChild(ICinemachineCamera vcam, bool dominantChildOnly = false)
Parameters
Type | Name | Description |
---|---|---|
ICinemachineCamera | vcam | The Virtual Camera to check |
Boolean | dominantChildOnly | If truw, will only return true if this vcam is the dominat live child |
Returns
Type | Description |
---|---|
Boolean | True if the vcam is currently actively influencing the state of this vcam |
Implements
LegacyUpgrade(Int32)
Override this to handle any upgrades necessitated by a streaming version change
Declaration
protected virtual void LegacyUpgrade(int streamedVersion)
Parameters
Type | Name | Description |
---|---|---|
Int32 | streamedVersion | The version that was streamed |
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 subqueue. 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
public void MoveToTopOfPrioritySubqueue()
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 seamlessy.
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 |
Implements
OnTransformParentChanged()
Base class implementation makes sure the priority queue remains up-to-date.
Declaration
protected virtual void OnTransformParentChanged()
OnTransitionFromCamera(ICinemachineCamera, Vector3, Single)
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 |
Single | deltaTime | Delta time for time-based effects (ignore if less than or equal to 0) |
Implements
OnValidate()
Enforce bounds for fields, when changed in inspector. Call base class implementation at the beginning of overridden method. After base method is called, ValidatingStreamVersion will be valid.
Declaration
protected virtual void OnValidate()
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 |
RemoveExtension(CinemachineExtension)
Remove a Pipeline stage hook callback.
Declaration
public virtual void RemoveExtension(CinemachineExtension extension)
Parameters
Type | Name | Description |
---|---|---|
CinemachineExtension | extension | The extension to remove. |
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 retrun 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, Single)
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 |
Single | deltaTime | Delta time for time-based effects (ignore if less than 0) |
Implements
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
protected void UpdateTargetCache()
Explicit Interface Implementations
ISerializationCallbackReceiver.OnAfterDeserialize()
Post-Serialization handler - performs legacy upgrade
Declaration
void ISerializationCallbackReceiver.OnAfterDeserialize()
Implements
ISerializationCallbackReceiver.OnBeforeSerialize()
Pre-Serialization handler - delegates to derived classes
Declaration
void ISerializationCallbackReceiver.OnBeforeSerialize()