Class CinemachineFreeLook

A Cinemachine Camera geared towards a 3rd person camera experience. The camera orbits around its subject with three separate camera rigs defining rings around the target. Each rig has its own radius, height offset, composer, and lens settings. Depending on the camera's position along the spline connecting these three rigs, these settings are interpolated to give the final camera position and state.

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

Fields

CreateRigOverride

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 CinemachineFreeLook.CreateRigDelegate CreateRigOverride
Field Value
Type Description
CinemachineFreeLook.CreateRigDelegate

DestroyRigOverride

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

Declaration
public static CinemachineFreeLook.DestroyRigDelegate DestroyRigOverride
Field Value
Type Description
CinemachineFreeLook.DestroyRigDelegate

m_BindingMode

The coordinate space to use when interpreting the offset from the target

Declaration
[Header("Orbits")]
[Tooltip("The coordinate space to use when interpreting the offset from the target.  This is also used to set the camera's Up vector, which will be maintained when aiming the camera.")]
public CinemachineTransposer.BindingMode m_BindingMode
Field Value
Type Description
CinemachineTransposer.BindingMode

m_CommonLens

If enabled, this lens setting will apply to all three child rigs, otherwise the child rig lens settings will be used

Declaration
[Tooltip("If enabled, this lens setting will apply to all three child rigs, otherwise the child rig lens settings will be used")]
[FormerlySerializedAs("m_UseCommonLensSetting")]
public bool m_CommonLens
Field Value
Type Description
Boolean

m_Follow

Object for the camera children wants to move with (the body target)

Declaration
[Tooltip("Object for the camera children wants to move with (the body target).")]
public Transform m_Follow
Field Value
Type Description
Transform

m_Heading

The definition of Forward. Camera will follow behind

Declaration
[Tooltip("The definition of Forward.  Camera will follow behind.")]
public CinemachineOrbitalTransposer.Heading m_Heading
Field Value
Type Description
CinemachineOrbitalTransposer.Heading

m_Lens

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

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

Object for the camera children to look at (the aim target)

Declaration
[Tooltip("Object for the camera children to look at (the aim target).")]
public Transform m_LookAt
Field Value
Type Description
Transform

m_Orbits

The radius and height of the three orbiting rigs

Declaration
[Tooltip("The radius and height of the three orbiting rigs.")]
public CinemachineFreeLook.Orbit[] m_Orbits
Field Value
Type Description
CinemachineFreeLook.Orbit[]

m_RecenterToTargetHeading

Controls how automatic recentering of the X axis is accomplished

Declaration
[Tooltip("Controls how automatic recentering of the X axis is accomplished")]
public AxisState.Recentering m_RecenterToTargetHeading
Field Value
Type Description
AxisState.Recentering

m_SplineCurvature

Declaration
[Tooltip("Controls how taut is the line that connects the rigs' orbits, which determines final placement on the Y axis")]
[Range(0F, 1F)]
[FormerlySerializedAs("m_SplineTension")]
public float m_SplineCurvature
Field Value
Type Description
Single

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

m_XAxis

The Horizontal axis. Value is -180...180. This is passed on to the rigs' OrbitalTransposer component

Declaration
[Tooltip("The Horizontal axis.  Value is -180...180.  This is passed on to the rigs' OrbitalTransposer component")]
public AxisState m_XAxis
Field Value
Type Description
AxisState

m_YAxis

The Vertical axis. Value is 0..1. Chooses how to blend the child rigs

Declaration
[Header("Axis Control")]
[Tooltip("The Vertical axis.  Value is 0..1.  Chooses how to blend the child rigs")]
public AxisState m_YAxis
Field Value
Type Description
AxisState

m_YAxisRecentering

Controls how automatic recentering of the Y axis is accomplished

Declaration
[Tooltip("Controls how automatic recentering of the Y axis is accomplished")]
public AxisState.Recentering m_YAxisRecentering
Field Value
Type Description
AxisState.Recentering

Properties

Follow

Get the current Follow target. Returns parent's Follow if parent is non-null and no specific Follow defined for this camera

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

LookAt

Get the current LookAt target. Returns parent's LookAt if parent is non-null and no specific LookAt defined for this camera

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

PreviousStateIsValid

Set this to force the next update to ignore deltaTime and reset itself

Declaration
public override bool PreviousStateIsValid { get; set; }
Property Value
Type Description
Boolean
Overrides

RigNames

Names of the 3 child rigs

Declaration
public static string[] RigNames { get; }
Property Value
Type Description
String[]

State

The cacmera state, which will be a blend of the child rig states

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

Methods

ForceCameraPosition(Vector3, Quaternion)

Force the virtual camera to assume a given position and orientation.
Procedural placement then takes over

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

GetLocalPositionForCameraFromInput(Single)

Returns the local position of the camera along the spline used to connect the three camera rigs. Does not take into account the current heading of the camera (or its target)

Declaration
public Vector3 GetLocalPositionForCameraFromInput(float t)
Parameters
Type Name Description
Single t

The t-value for the camera on its spline. Internally clamped to the value [0,1]
Returns
Type Description
Vector3

The local offset (back + up) of the camera WRT its target based on the supplied t-value

GetRig(Int32)

Get a child rig

Declaration
public CinemachineVirtualCamera GetRig(int i)
Parameters
Type Name Description
Int32 i

Rig index. Can be 0, 1, or 2
Returns
Type Description
CinemachineVirtualCamera

The rig, or null if index is bad.

InternalUpdateCameraState(Vector3, Single)

Internal use only. Called by CinemachineCore at designated update time so the vcam can position itself and track its targets. All 3 child rigs are updated, and a blend calculated, depending on the value of the Y axis.

Declaration
public override 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)
Overrides

IsLiveChild(ICinemachineCamera, Boolean)

Check whether the vcam a live child of this camera. Returns true if the child is currently contributing actively to the camera state.

Declaration
public override 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
Overrides

OnDestroy()

Makes sure that the child rigs get destroyed in an undo-firndly manner. Invalidates the rig cache.

Declaration
protected override void OnDestroy()
Overrides

OnEnable()

Updates the child rig cache

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 FreeLook, grab the axis values 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

UpdateInputAxisProvider()

API for the inspector. Internal use only

Declaration
public void UpdateInputAxisProvider()