Class CinemachineTransposer

This is a CinemachineComponent in the Body section of the component pipeline. Its job is to position the camera in a fixed relationship to the vcam's Follow target object, with offsets and damping.

The Tansposer will only change the camera's position in space. It will not re-orient or otherwise aim the camera. To to that, you need to instruct the vcam in the Aim section of its pipeline.

Inheritance
Object
Object
Component
Behaviour
MonoBehaviour
CinemachineComponentBase
CinemachineTransposer
CinemachineOrbitalTransposer
Inherited Members
Namespace: Cinemachine
Syntax
[DocumentationSorting(DocumentationSortingAttribute.Level.UserRef)]
[AddComponentMenu("")]
public class CinemachineTransposer : CinemachineComponentBase

Fields

m_AngularDamping

How aggressively the camera tries to track the target's orientation. Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.

Declaration
[Range(0F, 20F)]
[Tooltip("How aggressively the camera tries to track the target's orientation.  Small numbers are more responsive.  Larger numbers give a more heavy slowly responding camera.")]
public float m_AngularDamping
Field Value
Type Description
Single

m_AngularDampingMode

How to calculate the angular damping for the target orientation. Use Quaternion if you expect the target to take on very steep pitches, which would be subject to gimbal lock if Eulers are used.

Declaration
public CinemachineTransposer.AngularDampingMode m_AngularDampingMode
Field Value
Type Description
CinemachineTransposer.AngularDampingMode

m_BindingMode

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

Declaration
[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_FollowOffset

The distance which the transposer will attempt to maintain from the transposer subject

Declaration
[Tooltip("The distance vector that the transposer will attempt to maintain from the Follow target")]
public Vector3 m_FollowOffset
Field Value
Type Description
Vector3

m_PitchDamping

How aggressively the camera tries to track the target rotation's X angle. Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.

Declaration
[Range(0F, 20F)]
[Tooltip("How aggressively the camera tries to track the target rotation's X angle.  Small numbers are more responsive.  Larger numbers give a more heavy slowly responding camera.")]
public float m_PitchDamping
Field Value
Type Description
Single

m_RollDamping

How aggressively the camera tries to track the target rotation's Z angle. Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.

Declaration
[Range(0F, 20F)]
[Tooltip("How aggressively the camera tries to track the target rotation's Z angle.  Small numbers are more responsive.  Larger numbers give a more heavy slowly responding camera.")]
public float m_RollDamping
Field Value
Type Description
Single

m_XDamping

How aggressively the camera tries to maintain the offset in the X-axis. Small numbers are more responsive, rapidly translating the camera to keep the target's x-axis offset. Larger numbers give a more heavy slowly responding camera. Using different settings per axis can yield a wide range of camera behaviors

Declaration
[Range(0F, 20F)]
[Tooltip("How aggressively the camera tries to maintain the offset in the X-axis.  Small numbers are more responsive, rapidly translating the camera to keep the target's x-axis offset.  Larger numbers give a more heavy slowly responding camera. Using different settings per axis can yield a wide range of camera behaviors.")]
public float m_XDamping
Field Value
Type Description
Single

m_YawDamping

How aggressively the camera tries to track the target rotation's Y angle. Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.

Declaration
[Range(0F, 20F)]
[Tooltip("How aggressively the camera tries to track the target rotation's Y angle.  Small numbers are more responsive.  Larger numbers give a more heavy slowly responding camera.")]
public float m_YawDamping
Field Value
Type Description
Single

m_YDamping

How aggressively the camera tries to maintain the offset in the Y-axis. Small numbers are more responsive, rapidly translating the camera to keep the target's y-axis offset. Larger numbers give a more heavy slowly responding camera. Using different settings per axis can yield a wide range of camera behaviors

Declaration
[Range(0F, 20F)]
[Tooltip("How aggressively the camera tries to maintain the offset in the Y-axis.  Small numbers are more responsive, rapidly translating the camera to keep the target's y-axis offset.  Larger numbers give a more heavy slowly responding camera. Using different settings per axis can yield a wide range of camera behaviors.")]
public float m_YDamping
Field Value
Type Description
Single

m_ZDamping

How aggressively the camera tries to maintain the offset in the Z-axis. Small numbers are more responsive, rapidly translating the camera to keep the target's z-axis offset. Larger numbers give a more heavy slowly responding camera. Using different settings per axis can yield a wide range of camera behaviors

Declaration
[Range(0F, 20F)]
[Tooltip("How aggressively the camera tries to maintain the offset in the Z-axis.  Small numbers are more responsive, rapidly translating the camera to keep the target's z-axis offset.  Larger numbers give a more heavy slowly responding camera. Using different settings per axis can yield a wide range of camera behaviors.")]
public float m_ZDamping
Field Value
Type Description
Single

Properties

AngularDamping

Damping speeds for each of the 3 axes of the target's rotation

Declaration
protected Vector3 AngularDamping { get; }
Property Value
Type Description
Vector3

Damping

Damping speeds for each of the 3 axes of the offset from target

Declaration
protected Vector3 Damping { get; }
Property Value
Type Description
Vector3

EffectiveOffset

Get the target offset, with sanitization

Declaration
public Vector3 EffectiveOffset { get; }
Property Value
Type Description
Vector3

HideOffsetInInspector

Hide the offset in int inspector. Used by FreeLook.

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

IsValid

True if component is enabled and has a valid Follow target

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

Stage

Get the Cinemachine Pipeline stage that this component implements. Always returns the Body stage

Declaration
public override CinemachineCore.Stage Stage { get; }
Property Value
Type Description
CinemachineCore.Stage
Overrides

Methods

ForceCameraPosition(Vector3, Quaternion)

Force the virtual camera to assume a given position and orientation

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

GetMaxDampTime()

Report maximum damping time needed for this component.

Declaration
public override float GetMaxDampTime()
Returns
Type Description
Single

Highest damping setting in this component
Overrides

GetOffsetForMinimumTargetDistance(Vector3, Vector3, Vector3, Vector3, Vector3)

Return a new damped target position that respects the minimum distance from the real target

Declaration
protected Vector3 GetOffsetForMinimumTargetDistance(Vector3 dampedTargetPos, Vector3 cameraOffset, Vector3 cameraFwd, Vector3 up, Vector3 actualTargetPos)
Parameters
Type Name Description
Vector3 dampedTargetPos

The effective position of the target, after damping
Vector3 cameraOffset

Desired camera offset from target
Vector3 cameraFwd

Current camera local +Z direction
Vector3 up

Effective world up
Vector3 actualTargetPos

The real undamped target position
Returns
Type Description
Vector3

New camera offset, potentially adjusted to respect minimum distance from target

GetReferenceOrientation(Vector3)

Internal API for the Inspector Editor, so it can draw a marker at the target

Declaration
public Quaternion GetReferenceOrientation(Vector3 worldUp)
Parameters
Type Name Description
Vector3 worldUp

Current effective world up
Returns
Type Description
Quaternion

The rotation of the Follow target, as understood by the Transposer.
This is not necessarily the same thing as the actual target rotation

GetTargetCameraPosition(Vector3)

Internal API for the Inspector Editor, so it can draw a marker at the target

Declaration
public virtual Vector3 GetTargetCameraPosition(Vector3 worldUp)
Parameters
Type Name Description
Vector3 worldUp

Current effective world up
Returns
Type Description
Vector3

The position of the Follow target

InitPrevFrameStateInfo(ref CameraState, Single)

Initializes the state for previous frame if appropriate.

Declaration
protected void InitPrevFrameStateInfo(ref CameraState curState, float deltaTime)
Parameters
Type Name Description
CameraState curState

The current camera state
Single deltaTime

Current effective deltaTime.

MutateCameraState(ref CameraState, Single)

Positions the virtual camera according to the transposer rules.

Declaration
public override void MutateCameraState(ref CameraState curState, float deltaTime)
Parameters
Type Name Description
CameraState curState

The current camera state
Single deltaTime

Used for damping. If less than 0, no damping is done.
Overrides

OnTargetObjectWarped(Transform, Vector3)

This is called to notify the us that a target got warped, so that we 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

OnValidate()

Derived classes should call this from their OnValidate() implementation

Declaration
protected virtual void OnValidate()

TrackTarget(Single, Vector3, Vector3, out Vector3, out Quaternion)

Positions the virtual camera according to the transposer rules.

Declaration
protected void TrackTarget(float deltaTime, Vector3 up, Vector3 desiredCameraOffset, out Vector3 outTargetPosition, out Quaternion outTargetOrient)
Parameters
Type Name Description
Single deltaTime

Used for damping. If less than 0, no damping is done.
Vector3 up

Current camera up
Vector3 desiredCameraOffset

Where we want to put the camera relative to the follow target
Vector3 outTargetPosition

Resulting camera position
Quaternion outTargetOrient

Damped target orientation