Class CinemachinePositionComposer
This is a Cinemachine Component in the Body section of the component pipeline. Its job is to position the camera in a fixed screen-space relationship to the camera's Tracking target object, with offsets and damping.
The camera will be first moved along the camera Z axis until the target is at the desired distance from the camera's X-Y plane. The camera will then be moved in its XY plane until the target is at the desired point on the camera's screen.
The Position Composer will only change the camera's position in space. It will not re-orient or otherwise aim the camera.
For this component to work properly, the camera's tracking target must not be null. The tracking target will define what the camera is looking at.
Inheritance
Implements
Inherited Members
Namespace: Unity.Cinemachine
Assembly: Unity.Cinemachine.dll
Syntax
[AddComponentMenu("Cinemachine/Procedural/Position Control/Cinemachine Position Composer")]
[DisallowMultipleComponent]
[CameraPipeline(CinemachineCore.Stage.Body)]
[RequiredTarget(RequiredTargetAttribute.RequiredTargets.Tracking)]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.cinemachine@3.1/manual/CinemachinePositionComposer.html")]
public class CinemachinePositionComposer : CinemachineComponentBase, CinemachineFreeLookModifier.IModifiablePositionDamping, CinemachineFreeLookModifier.IModifiableDistance, CinemachineFreeLookModifier.IModifiableCompositionFields
CameraDistance
The distance along the camera axis that will be maintained from the target
Declaration
[Header("Camera Position")]
[Tooltip("The distance along the camera axis that will be maintained from the target")]
public float CameraDistanceField Value
| Type | Description |
|---|---|
| float |
CenterOnActivate
Force target to center of screen when this camera activates.
If false, will clamp target to the edges of the dead zone
Declaration
[Tooltip("Force target to center of screen when this camera activates. If false, will clamp target to the edges of the dead zone")]
public bool CenterOnActivateField Value
| Type | Description |
|---|---|
| bool |
Composition
Settings for screen-space composition
Declaration
[Header("Composition")]
public ScreenComposerSettings CompositionField Value
| Type | Description |
|---|---|
| ScreenComposerSettings |
Damping
How aggressively the camera tries to follow the target in screen space. Small numbers are more responsive, rapidly orienting the camera to keep the target in the dead zone. Larger numbers give a more heavy slowly responding camera. Using different vertical and horizontal settings can yield a wide range of camera behaviors.
Declaration
[Tooltip("How aggressively the camera tries to follow the target in the screen space. Small numbers are more responsive, rapidly orienting the camera to keep the target in the dead zone. Larger numbers give a more heavy slowly responding camera. Using different vertical and horizontal settings can yield a wide range of camera behaviors.")]
public Vector3 DampingField Value
| Type | Description |
|---|---|
| Vector3 |
DeadZoneDepth
The camera will not move along its z-axis if the target is within this distance of the specified camera distance
Declaration
[Tooltip("The camera will not move along its z-axis if the target is within this distance of the specified camera distance")]
public float DeadZoneDepthField Value
| Type | Description |
|---|---|
| float |
Lookahead
This setting will instruct the composer to adjust its target offset based on the motion of the target. The composer will look at a point where it estimates the target will be a little into the future.
Declaration
[FoldoutWithEnabledButton("Enabled")]
public LookaheadSettings LookaheadField Value
| Type | Description |
|---|---|
| LookaheadSettings |
TargetOffset
Offset from the target object (in target-local co-ordinates). The camera will attempt to frame the point which is the target's position plus this offset. Use it to correct for cases when the target's origin is not the point of interest for the camera.
Declaration
[Header("Target Tracking")]
[Tooltip("Offset from the target object (in target-local co-ordinates). The camera will attempt to frame the point which is the target's position plus this offset. Use it to correct for cases when the target's origin is not the point of interest for the camera.")]
[FormerlySerializedAs("TrackedObjectOffset")]
public Vector3 TargetOffsetField Value
| Type | Description |
|---|---|
| Vector3 |
Properties
BodyAppliesAfterAim
FramingTransposer algorithm takes camera orientation as input, so even though it is a Body component, it must apply after Aim
Declaration
public override bool BodyAppliesAfterAim { get; }Property Value
| Type | Description |
|---|---|
| bool |
Overrides
IsValid
True if component is enabled and has a valid Follow target
Declaration
public override bool IsValid { get; }Property Value
| Type | Description |
|---|---|
| bool |
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 | World-space position to take |
| Quaternion | rot | World-space orientation to take |
Overrides
GetMaxDampTime()
Report maximum damping time needed for this component.
Declaration
public override float GetMaxDampTime()Returns
| Type | Description |
|---|---|
| float | Highest damping setting in this component |
Overrides
MutateCameraState(ref CameraState, float)
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 |
| float | deltaTime | Used for damping. If less than 0, no damping is done. |
Overrides
OnTargetObjectWarped(Transform, Vector3)
This is called to notify the user that a target got warped, so that we can update its internal state to make the camera also warp seamlessly.
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, float)
Notification that this virtual camera is going live. Base class implementation does nothing.
Declaration
public override bool 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 |
| float | deltaTime | Delta time for time-based effects (ignore if less than or equal to 0) |
Returns
| Type | Description |
|---|---|
| bool | True if the vcam should do an internal update as a result of this call |