Class CinemachineBrain

CinemachineBrain is the link between the Unity Camera and the CinemachineCameras in the Scene. It monitors the priority stack to choose the current Cinemachine Camera, and blend with another if necessary. Finally and most importantly, it applies the CinemachineCamera state to the attached Unity Camera.

The CinemachineBrain is also the place where rules for blending between Cinemachine Cameras are defined. Camera blending is an interpolation over time of one Cinemachine Camera position and state to another. If you think of CinemachineCameras as cameramen, then blending is a little like one cameraman smoothly passing the camera to another cameraman. You can specify the time over which to blend, as well as the blend curve shape. Note that a camera cut is just a zero-time blend.

Inheritance

object

Object

Component

Behaviour

MonoBehaviour

CinemachineBrain

Implements

ICameraOverrideStack

ICinemachineMixer

ICinemachineCamera

Inherited Members

MonoBehaviour.IsInvoking()

MonoBehaviour.CancelInvoke()

MonoBehaviour.Invoke(string, float)

MonoBehaviour.InvokeRepeating(string, float, float)

MonoBehaviour.CancelInvoke(string)

MonoBehaviour.IsInvoking(string)

MonoBehaviour.StartCoroutine(string)

MonoBehaviour.StartCoroutine(string, object)

MonoBehaviour.StartCoroutine(IEnumerator)

MonoBehaviour.StartCoroutine_Auto(IEnumerator)

MonoBehaviour.StopCoroutine(IEnumerator)

MonoBehaviour.StopCoroutine(Coroutine)

MonoBehaviour.StopCoroutine(string)

MonoBehaviour.StopAllCoroutines()

MonoBehaviour.print(object)

MonoBehaviour.destroyCancellationToken

MonoBehaviour.useGUILayout

MonoBehaviour.runInEditMode

Behaviour.enabled

Behaviour.isActiveAndEnabled

Component.GetComponent(Type)

Component.GetComponent<T>()

Component.TryGetComponent(Type, out Component)

Component.TryGetComponent<T>(out T)

Component.GetComponent(string)

Component.GetComponentInChildren(Type, bool)

Component.GetComponentInChildren(Type)

Component.GetComponentInChildren<T>(bool)

Component.GetComponentInChildren<T>()

Component.GetComponentsInChildren(Type, bool)

Component.GetComponentsInChildren(Type)

Component.GetComponentsInChildren<T>(bool)

Component.GetComponentsInChildren<T>(bool, List<T>)

Component.GetComponentsInChildren<T>()

Component.GetComponentsInChildren<T>(List<T>)

Component.GetComponentInParent(Type, bool)

Component.GetComponentInParent(Type)

Component.GetComponentInParent<T>(bool)

Component.GetComponentInParent<T>()

Component.GetComponentsInParent(Type, bool)

Component.GetComponentsInParent(Type)

Component.GetComponentsInParent<T>(bool)

Component.GetComponentsInParent<T>(bool, List<T>)

Component.GetComponentsInParent<T>()

Component.GetComponents(Type)

Component.GetComponents(Type, List<Component>)

Component.GetComponents<T>(List<T>)

Component.GetComponents<T>()

Component.GetComponentIndex()

Component.CompareTag(string)

Component.SendMessageUpwards(string, object, SendMessageOptions)

Component.SendMessageUpwards(string, object)

Component.SendMessageUpwards(string)

Component.SendMessageUpwards(string, SendMessageOptions)

Component.SendMessage(string, object)

Component.SendMessage(string)

Component.SendMessage(string, object, SendMessageOptions)

Component.SendMessage(string, SendMessageOptions)

Component.BroadcastMessage(string, object, SendMessageOptions)

Component.BroadcastMessage(string, object)

Component.BroadcastMessage(string)

Component.BroadcastMessage(string, SendMessageOptions)

Component.transform

Component.gameObject

Component.tag

Object.GetInstanceID()

Object.GetHashCode()

Object.Equals(object)

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, int)

Object.InstantiateAsync<T>(T, int, Transform)

Object.InstantiateAsync<T>(T, int, Vector3, Quaternion)

Object.InstantiateAsync<T>(T, int, ReadOnlySpan<Vector3>, ReadOnlySpan<Quaternion>)

Object.InstantiateAsync<T>(T, int, Transform, Vector3, Quaternion)

Object.InstantiateAsync<T>(T, int, Transform, ReadOnlySpan<Vector3>, ReadOnlySpan<Quaternion>)

Object.InstantiateAsync<T>(T, InstantiateParameters)

Object.InstantiateAsync<T>(T, int, InstantiateParameters)

Object.InstantiateAsync<T>(T, Vector3, Quaternion, InstantiateParameters)

Object.InstantiateAsync<T>(T, int, Vector3, Quaternion, InstantiateParameters)

Object.InstantiateAsync<T>(T, int, ReadOnlySpan<Vector3>, ReadOnlySpan<Quaternion>, InstantiateParameters)

Object.Instantiate(Object, Vector3, Quaternion)

Object.Instantiate(Object, Vector3, Quaternion, Transform)

Object.Instantiate(Object)

Object.Instantiate(Object, Scene)

Object.Instantiate<T>(T, InstantiateParameters)

Object.Instantiate<T>(T, Vector3, Quaternion, InstantiateParameters)

Object.Instantiate(Object, Transform)

Object.Instantiate(Object, Transform, bool)

Object.Instantiate<T>(T)

Object.Instantiate<T>(T, Vector3, Quaternion)

Object.Instantiate<T>(T, Vector3, Quaternion, Transform)

Object.Instantiate<T>(T, Transform)

Object.Instantiate<T>(T, Transform, bool)

Object.Destroy(Object, float)

Object.Destroy(Object)

Object.DestroyImmediate(Object, bool)

Object.DestroyImmediate(Object)

Object.FindObjectsOfType(Type)

Object.FindObjectsOfType(Type, bool)

Object.FindObjectsByType(Type, FindObjectsSortMode)

Object.FindObjectsByType(Type, FindObjectsInactive, FindObjectsSortMode)

Object.DontDestroyOnLoad(Object)

Object.DestroyObject(Object, float)

Object.DestroyObject(Object)

Object.FindSceneObjectsOfType(Type)

Object.FindObjectsOfTypeIncludingAssets(Type)

Object.FindObjectsOfType<T>()

Object.FindObjectsByType<T>(FindObjectsSortMode)

Object.FindObjectsOfType<T>(bool)

Object.FindObjectsByType<T>(FindObjectsInactive, FindObjectsSortMode)

Object.FindObjectOfType<T>()

Object.FindObjectOfType<T>(bool)

Object.FindFirstObjectByType<T>()

Object.FindAnyObjectByType<T>()

Object.FindFirstObjectByType<T>(FindObjectsInactive)

Object.FindAnyObjectByType<T>(FindObjectsInactive)

Object.FindObjectsOfTypeAll(Type)

Object.FindObjectOfType(Type)

Object.FindFirstObjectByType(Type)

Object.FindAnyObjectByType(Type)

Object.FindObjectOfType(Type, bool)

Object.FindFirstObjectByType(Type, FindObjectsInactive)

Object.FindAnyObjectByType(Type, FindObjectsInactive)

Object.ToString()

Object.name

Object.hideFlags

object.Equals(object, object)

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Namespace: Unity.Cinemachine

Assembly: Unity.Cinemachine.dll

Syntax

[DisallowMultipleComponent]
[ExecuteAlways]
[AddComponentMenu("Cinemachine/Cinemachine Brain")]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.cinemachine@3.1/manual/CinemachineBrain.html")]
public class CinemachineBrain : MonoBehaviour, ICameraOverrideStack, ICinemachineMixer, ICinemachineCamera

Fields

BlendUpdateMethod

The update time for the Brain, i.e. when the blends are evaluated and the brain's transform is updated.

Declaration

[Tooltip("The update time for the Brain, i.e. when the blends are evaluated and the brain's transform is updated")]
[FormerlySerializedAs("m_BlendUpdateMethod")]
public CinemachineBrain.BrainUpdateMethods BlendUpdateMethod

Field Value

Type	Description
CinemachineBrain.BrainUpdateMethods

ChannelMask

The CinemachineBrain finds the highest-priority CinemachineCamera that outputs to any of the channels selected. CinemachineCameras that do not output to one of these channels are ignored. Use this in situations where multiple CinemachineBrains are needed (for example, Split-screen).

Declaration

[Tooltip("The CinemachineBrain finds the highest-priority CinemachineCamera that outputs to any of the channels selected.  CinemachineCameras that do not output to one of these channels are ignored.  Use this in situations where multiple CinemachineBrains are needed (for example, Split-screen).")]
public OutputChannels ChannelMask

Field Value

Type	Description
OutputChannels

CustomBlends

This is the asset that contains custom settings for blends between specific CinemachineCameras in your Scene.

Declaration

[Tooltip("This is the asset that contains custom settings for blends between specific CinemachineCameras in your Scene")]
[FormerlySerializedAs("m_CustomBlends")]
public CinemachineBlenderSettings CustomBlends

Field Value

Type	Description
CinemachineBlenderSettings

DefaultBlend

The blend that is used if you don't explicitly define a blend between two CinemachineCameras.

Declaration

[Tooltip("The blend that is used in cases where you haven't explicitly defined a blend between two CinemachineCameras")]
[FormerlySerializedAs("m_DefaultBlend")]
public CinemachineBlendDefinition DefaultBlend

Field Value

Type	Description
CinemachineBlendDefinition

IgnoreTimeScale

When enabled, the cameras always respond in real-time to user input and damping, even if the game is running in slow motion.

Declaration

[Tooltip("When enabled, the cameras always respond in real-time to user input and damping, even if the game is running in slow motion")]
[FormerlySerializedAs("m_IgnoreTimeScale")]
public bool IgnoreTimeScale

Field Value

Type	Description
bool

LensModeOverride

Controls whether CinemachineCameras can change the lens mode.

Declaration

[FoldoutWithEnabledButton("Enabled")]
public CinemachineBrain.LensModeOverrideSettings LensModeOverride

Field Value

Type	Description
CinemachineBrain.LensModeOverrideSettings

ShowCameraFrustum

When enabled, shows the camera's frustum in the Scene view.

Declaration

[Tooltip("When enabled, shows the camera's frustum at all times in the Scene view")]
[FormerlySerializedAs("m_ShowCameraFrustum")]
public bool ShowCameraFrustum

Field Value

Type	Description
bool

ShowDebugText

When enabled, the current camera and blend are indicated in the game window, for debugging.

Declaration

[Tooltip("When enabled, the current camera and blend are indicated in the game window, for debugging")]
[FormerlySerializedAs("m_ShowDebugText")]
public bool ShowDebugText

Field Value

Type	Description
bool

UpdateMethod

Depending on how the target GameObjects are animated, adjust the update method to minimize the potential jitter. Use FixedUpdate if all your targets are animated with for RigidBody animation. SmartUpdate chooses the best method for each CinemachineCamera, depending on how the target is animated.

Declaration

[Tooltip("The update time for the CinemachineCameras.  Use FixedUpdate if all your targets are animated during FixedUpdate (e.g. RigidBodies), LateUpdate if all your targets are animated during the normal Update loop, and SmartUpdate if you want Cinemachine to do the appropriate thing on a per-target basis.  SmartUpdate is the recommended setting")]
[FormerlySerializedAs("m_UpdateMethod")]
public CinemachineBrain.UpdateMethods UpdateMethod

Field Value

Type	Description
CinemachineBrain.UpdateMethods

WorldUpOverride

If set, this GameObject's Y axis defines the world-space Up vector for all the CinemachineCameras. This is useful in top-down game environments. If not set, Up is world-space Y.

Declaration

[Tooltip("If set, this GameObject's Y axis defines the world-space Up vector for all the CinemachineCameras.  This is useful for instance in top-down game environments.  If not set, Up is world-space Y.  Setting this appropriately is important, because CinemachineCameras don't like looking straight up or straight down.")]
[FormerlySerializedAs("m_WorldUpOverride")]
public Transform WorldUpOverride

Field Value

Type	Description
Transform

Properties

ActiveBlend

Get the current blend in progress. Returns null if none. It is also possible to set the current blend, but this is not a recommended usage unless it is to set the active blend to null, which forces the completion of the blend.

Declaration

public CinemachineBlend ActiveBlend { get; set; }

Property Value

Type	Description
CinemachineBlend

ActiveBrainCount

Access the array of active CinemachineBrains in the Scene

Declaration

public static int ActiveBrainCount { get; }

Property Value

Type	Description
int

ActiveVirtualCamera

Get the current active CinemachineCamera.

Declaration

public ICinemachineCamera ActiveVirtualCamera { get; }

Property Value

Type	Description
ICinemachineCamera

ControlledObject

CinemachineBrain controls this GameObject. Normally, this is the GameObject to which the CinemachineBrain component is attached. However, it is possible to override this by setting this property to another GameObject. If a Camera component is attached to the Controlled GameObject, then that Camera component's lens settings is also driven by the CinemachineBrain. If this property is set to null, then CinemachineBrain is controlling the GameObject to which it is attached. The value of this property always reports as non-null.

Declaration

public GameObject ControlledObject { get; set; }

Property Value

Type	Description
GameObject

DefaultWorldUp

Get the default world up for the CinemachineCameras.

Declaration

public Vector3 DefaultWorldUp { get; }

Property Value

Type	Description
Vector3

Description

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

Declaration

public string Description { get; }

Property Value

Type	Description
string

IsBlending

Indicates if there is a blend in progress.

Declaration

public bool IsBlending { get; }

Property Value

Type	Description
bool

IsValid

Will return false if this references a deleted object

Declaration

public bool IsValid { get; }

Property Value

Type	Description
bool

Name

Gets the name of this virtual camera. For use when deciding how to blend to or from this camera

Declaration

public string Name { get; }

Property Value

Type	Description
string

OutputCamera

Get the Unity Camera that is attached to this GameObject. This is the camera that is controlled by the CinemachineBrain.

Declaration

public Camera OutputCamera { get; }

Property Value

Type	Description
Camera

ParentCamera

Returns the ICinemachineMixer within which this Camera is nested, or null.

Declaration

public ICinemachineMixer ParentCamera { get; }

Property Value

Type	Description
ICinemachineMixer

State

Camera state at the current time.

Declaration

public CameraState State { get; }

Property Value

Type	Description
CameraState

Methods

GetActiveBrain(int)

Access the array of active CinemachineBrains in the Scene without generating garbage.

Declaration

public static CinemachineBrain GetActiveBrain(int index)

Parameters

Type	Name	Description
int	index	Index of the brain to access, range 0-ActiveBrainCount.

Returns

Type	Description
CinemachineBrain	The brain at the specified index.

IsLiveChild(ICinemachineCamera, bool)

Check whether the cam is a live child of this camera.

Declaration

public bool IsLiveChild(ICinemachineCamera cam, bool dominantChildOnly = false)

Parameters

Type	Name	Description
ICinemachineCamera	cam
bool	dominantChildOnly	If true, will only return true if this vcam is the dominant live child

Returns

Type	Description
bool	True if the vcam is currently actively influencing the state of this vcam

IsLiveInBlend(ICinemachineCamera)

Checks if the CinemachineCamera is live as part of an outgoing blend.
Does not check whether the CinemachineCamera is also the current active CinemachineCamera.

Declaration

public bool IsLiveInBlend(ICinemachineCamera cam)

Parameters

Type	Name	Description
ICinemachineCamera	cam	The CinemachineCamera to check.

Returns

Type	Description
bool	True if the CinemachineCamera is part of a live outgoing blend, false otherwise.

IsValidChannel(CinemachineVirtualCameraBase)

Returns true if the CinemachineCamera is on a channel that is handled by this CinemachineBrain.

Declaration

public bool IsValidChannel(CinemachineVirtualCameraBase vcam)

Parameters

Type	Name	Description
CinemachineVirtualCameraBase	vcam	The CinemachineCamera to check.

Returns

Type	Description
bool	True if the CinemachineCamera is on a channel that is handled by this Brain.

ManualUpdate()

Call this method explicitly from an external script to update the CinemachineCameras and position the main camera, if the UpdateMode is set to ManualUpdate. For other update modes, this method is called automatically, and should not be called from elsewhere.

Declaration

public void ManualUpdate()

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 void OnCameraActivated(ICinemachineCamera.ActivationEventParams evt)

Parameters

Type	Name	Description
ICinemachineCamera.ActivationEventParams	evt	Context for the camera activation.

ReleaseCameraOverride(int)

See SetCameraOverride. Call ReleaseCameraOverride after all overriding is finished, to free the OverrideStack resources.

Declaration

public void ReleaseCameraOverride(int overrideId)

Parameters

Type	Name	Description
int	overrideId	The ID to released. This is the value that was returned by SetCameraOverride

ResetState()

Call this to reset the current active camera, causing the brain to choose a new one without blending. It is useful, for example, when you want to restart a game level.

Declaration

public void ResetState()

SetCameraOverride(int, int, ICinemachineCamera, ICinemachineCamera, float, float)

Override the current camera and current blend. This setting will trump any in-game logic that sets virtual camera priorities and Enabled states. This is the main API for the timeline.

Declaration

public int SetCameraOverride(int overrideId, int priority, ICinemachineCamera camA, ICinemachineCamera camB, float weightB, float deltaTime)

Parameters

Type	Name	Description
int	overrideId	Id to represent a specific client. An internal stack is maintained, with the most recent non-empty override taking precedence. This id must be > 0. If you pass -1, a new id will be created, and returned. Use that id for subsequent calls. Don't forget to call ReleaseCameraOverride after all overriding is finished, to free the OverrideStack resources.
int	priority	The priority to assign to the override. Higher priorities take precedence over lower ones. This is not connected to the Priority field in the individual CinemachineCameras, but the function is analogous.
ICinemachineCamera	camA	The camera to set, corresponding to weight=0.
ICinemachineCamera	camB	The camera to set, corresponding to weight=1.
float	weightB	The blend weight. 0=camA, 1=camB.
float	deltaTime	Override for deltaTime. Should be Time.FixedDelta for time-based calculations to be included, -1 otherwise.

Returns

Type	Description
int	The override ID. Don't forget to call ReleaseCameraOverride after all overriding is finished, to free the OverrideStack resources.

TopCameraFromPriorityQueue()

Chooses the default active CinemachineCamera in the case there is no camera override.

Declaration

protected virtual ICinemachineCamera TopCameraFromPriorityQueue()

Returns

Type	Description
ICinemachineCamera	The highest-priority Enabled ICinemachineCamera that is in my Channel Mask.

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 up, float deltaTime)

Parameters

Type	Name	Description
Vector3	up
float	deltaTime	Delta time for time-based effects (ignore if less than 0)

Implements

ICameraOverrideStack

ICinemachineMixer

ICinemachineCamera