Class CinemachineBrain

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

The CinemachineBrain is also the place where rules for blending between virtual cameras are defined. Camera blending is an interpolation over time of one virtual camera position and state to another. If you think of virtual cameras 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
Inherited Members
Namespace: Cinemachine
Syntax
[DocumentationSorting(DocumentationSortingAttribute.Level.UserRef)]
[DisallowMultipleComponent]
[ExecuteAlways]
[AddComponentMenu("Cinemachine/CinemachineBrain")]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.cinemachine@2.9/manual/CinemachineBrainProperties.html")]
public class CinemachineBrain : MonoBehaviour, ICameraOverrideStack

Fields

m_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")]
public CinemachineBrain.BrainUpdateMethod m_BlendUpdateMethod
Field Value
Type Description
CinemachineBrain.BrainUpdateMethod

m_CameraActivatedEvent

This event will fire whenever a virtual camera goes live. If a blend is involved, then the event will fire on the first frame of the blend.

The Parameters are (incoming_vcam, outgoing_vcam), in that order.

Declaration
[Tooltip("This event will fire whenever a virtual camera goes live.  If a blend is involved, then the event will fire on the first frame of the blend.")]
public CinemachineBrain.VcamActivatedEvent m_CameraActivatedEvent
Field Value
Type Description
CinemachineBrain.VcamActivatedEvent

m_CameraCutEvent

This event will fire whenever a virtual camera goes live and there is no blend

Declaration
[Tooltip("This event will fire whenever a virtual camera goes live and there is no blend")]
public CinemachineBrain.BrainEvent m_CameraCutEvent
Field Value
Type Description
CinemachineBrain.BrainEvent

m_CustomBlends

This is the asset which contains custom settings for specific blends.

Declaration
[Tooltip("This is the asset that contains custom settings for blends between specific virtual cameras in your scene")]
public CinemachineBlenderSettings m_CustomBlends
Field Value
Type Description
CinemachineBlenderSettings

m_DefaultBlend

The blend which is used if you don't explicitly define a blend between two Virtual Cameras.

Declaration
[Tooltip("The blend that is used in cases where you haven't explicitly defined a blend between two Virtual Cameras")]
public CinemachineBlendDefinition m_DefaultBlend
Field Value
Type Description
CinemachineBlendDefinition

m_IgnoreTimeScale

When enabled, the cameras will 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 will always respond in real-time to user input and damping, even if the game is running in slow motion")]
public bool m_IgnoreTimeScale
Field Value
Type Description
Boolean

m_ShowCameraFrustum

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

Declaration
[Tooltip("When enabled, the camera's frustum will be shown at all times in the scene view")]
public bool m_ShowCameraFrustum
Field Value
Type Description
Boolean

m_ShowDebugText

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

Declaration
[Tooltip("When enabled, the current camera and blend will be indicated in the game window, for debugging")]
public bool m_ShowDebugText
Field Value
Type Description
Boolean

m_UpdateMethod

Depending on how the target objects are animated, adjust the update method to minimize the potential jitter. Use FixedUpdate if all your targets are animated with for RigidBody animation. SmartUpdate will choose the best method for each virtual camera, depending on how the target is animated.

Declaration
[Tooltip("The update time for the vcams.  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")]
public CinemachineBrain.UpdateMethod m_UpdateMethod
Field Value
Type Description
CinemachineBrain.UpdateMethod

m_WorldUpOverride

If set, this object's Y axis will define the worldspace Up vector for all the virtual cameras. This is useful in top-down game environments. If not set, Up is worldspace Y.

Declaration
[Tooltip("If set, this object's Y axis will define the worldspace Up vector for all the virtual cameras.  This is useful for instance in top-down game environments.  If not set, Up is worldspace Y.  Setting this appropriately is important, because Virtual Cameras don't like looking straight up or straight down.")]
public Transform m_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.

Declaration
public CinemachineBlend ActiveBlend { get; set; }
Property Value
Type Description
CinemachineBlend

ActiveVirtualCamera

Get the current active virtual camera.

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 Object, then that Camera component's lens settings will also be 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 will always report as non-null.

Declaration
public GameObject ControlledObject { get; set; }
Property Value
Type Description
GameObject

CurrentCameraState

The current state applied to the unity camera (may be the result of a blend)

Declaration
public CameraState CurrentCameraState { get; }
Property Value
Type Description
CameraState

DefaultWorldUp

Get the default world up for the virtual cameras.

Declaration
public Vector3 DefaultWorldUp { get; }
Property Value
Type Description
Vector3
Implements

IsBlending

Is there a blend in progress?

Declaration
public bool IsBlending { get; }
Property Value
Type Description
Boolean

OutputCamera

Get the Unity Camera that is attached to this GameObject. This is the camera that will be controlled by the brain.

Declaration
public Camera OutputCamera { get; }
Property Value
Type Description
Camera

SoloCamera

API for the Unity Editor. Show this camera no matter what. This is static, and so affects all Cinemachine brains.

Declaration
public static ICinemachineCamera SoloCamera { get; set; }
Property Value
Type Description
ICinemachineCamera

Methods

ComputeCurrentBlend(ref CinemachineBlend, Int32)

Used internally to compute the currrent blend, taking into account the in-game camera and all the active overrides. Caller may optionally exclude n topmost overrides.

Declaration
public void ComputeCurrentBlend(ref CinemachineBlend outputBlend, int numTopLayersToExclude)
Parameters
Type Name Description
CinemachineBlend outputBlend

Receives the nested blend
Int32 numTopLayersToExclude

Optionaly exclude the last number of overrides from the blend

GetSoloGUIColor()

API for the Unity Editor.

Declaration
public static Color GetSoloGUIColor()
Returns
Type Description
Color

Color used to indicate that a camera is in Solo mode.

IsLive(ICinemachineCamera, Boolean)

True if the ICinemachineCamera the current active camera, or part of a current blend, either directly or indirectly because its parents are live.

Declaration
public bool IsLive(ICinemachineCamera vcam, bool dominantChildOnly = false)
Parameters
Type Name Description
ICinemachineCamera vcam

The camera to test whether it is live
Boolean dominantChildOnly

If true, will only return true if this vcam is the dominat live child
Returns
Type Description
Boolean

True if the camera is live (directly or indirectly) or part of a blend in progress.

IsLiveInBlend(ICinemachineCamera)

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

Declaration
public bool IsLiveInBlend(ICinemachineCamera vcam)
Parameters
Type Name Description
ICinemachineCamera vcam

The virtual camera to check
Returns
Type Description
Boolean

True if the virtual camera is part of a live outgoing blend, false otherwise

ManualUpdate()

Call this method explicitly from an external script to update the virtual cameras 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()

ReleaseCameraOverride(Int32)

This API is specifically for Timeline. Do not use it. Release the resources used for a camera override client. See SetCameraOverride.

Declaration
public void ReleaseCameraOverride(int overrideId)
Parameters
Type Name Description
Int32 overrideId

The ID to released. This is the value that was returned by SetCameraOverride
Implements

SetCameraOverride(Int32, ICinemachineCamera, ICinemachineCamera, Single, Single)

This API is specifically for Timeline. Do not use it. 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, ICinemachineCamera camA, ICinemachineCamera camB, float weightB, float deltaTime)
Parameters
Type Name Description
Int32 overrideId

Id to represent a specific client. An internal stack is maintained, with the most recent non-empty override taking precenence. 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 OverideStack resources.
ICinemachineCamera camA

The camera to set, corresponding to weight=0
ICinemachineCamera camB

The camera to set, corresponding to weight=1
Single weightB

The blend weight. 0=camA, 1=camB
Single deltaTime

override for deltaTime. Should be Time.FixedDelta for time-based calculations to be included, -1 otherwise
Returns
Type Description
Int32

The oiverride ID. Don't forget to call ReleaseCameraOverride after all overriding is finished, to free the OverideStack resources.
Implements