Class CinemachineCollider

An add-on module for Cinemachine Virtual Camera that post-processes the final position of the virtual camera. Based on the supplied settings, the Collider will attempt to preserve the line of sight with the LookAt target of the virtual camera by moving away from objects that will obstruct the view.

Additionally, the Collider can be used to assess the shot quality and report this as a field in the camera State.

Inheritance
Object
Object
Component
Behaviour
MonoBehaviour
CinemachineExtension
CinemachineCollider
Inherited Members
Namespace: Cinemachine
Syntax
[DocumentationSorting(DocumentationSortingAttribute.Level.UserRef)]
[AddComponentMenu("")]
[ExecuteAlways]
[DisallowMultipleComponent]
[HelpURL("https://docs.unity.cn/Packages/com.unity.cinemachine@2.8/manual/CinemachineCollider.html")]
public class CinemachineCollider : CinemachineExtension

Fields

m_AvoidObstacles

When enabled, will attempt to resolve situations where the line of sight to the target is blocked by an obstacle

Declaration
[Space]
[Tooltip("When enabled, will attempt to resolve situations where the line of sight to the target is blocked by an obstacle")]
[FormerlySerializedAs("m_PreserveLineOfSight")]
public bool m_AvoidObstacles
Field Value
Type Description
Boolean

m_CameraRadius

Camera will try to maintain this distance from any obstacle. Increase this value if you are seeing inside obstacles due to a large FOV on the camera.

Declaration
[Tooltip("Camera will try to maintain this distance from any obstacle.  Try to keep this value small.  Increase it if you are seeing inside obstacles due to a large FOV on the camera.")]
public float m_CameraRadius
Field Value
Type Description
Single

m_CollideAgainst

Objects on these layers will be detected.

Declaration
[Header("Obstacle Detection")]
[Tooltip("Objects on these layers will be detected")]
public LayerMask m_CollideAgainst
Field Value
Type Description
LayerMask

m_Damping

How gradually the camera returns to its normal position after having been corrected. Higher numbers will move the camera more gradually back to normal.

Declaration
[Range(0F, 10F)]
[Tooltip("How gradually the camera returns to its normal position after having been corrected.  Higher numbers will move the camera more gradually back to normal.")]
[FormerlySerializedAs("m_Smoothing")]
public float m_Damping
Field Value
Type Description
Single

m_DampingWhenOccluded

How gradually the camera moves to resolve an occlusion. Higher numbers will move the camera more gradually.

Declaration
[Range(0F, 10F)]
[Tooltip("How gradually the camera moves to resolve an occlusion.  Higher numbers will move the camera more gradually.")]
public float m_DampingWhenOccluded
Field Value
Type Description
Single

m_DistanceLimit

The raycast distance to test for when checking if the line of sight to this camera's target is clear.

Declaration
[Tooltip("The maximum raycast distance when checking if the line of sight to this camera's target is clear.  If the setting is 0 or less, the current actual distance to target will be used.")]
[FormerlySerializedAs("m_LineOfSightFeelerDistance")]
public float m_DistanceLimit
Field Value
Type Description
Single

m_IgnoreTag

Obstacles with this tag will be ignored. It is a good idea to set this field to the target's tag

Declaration
[Tooltip("Obstacles with this tag will be ignored.  It is a good idea to set this field to the target's tag")]
public string m_IgnoreTag
Field Value
Type Description
String

m_MaximumEffort

Upper limit on how many obstacle hits to process. Higher numbers may impact performance. In most environments, 4 is enough.

Declaration
[Range(1F, 10F)]
[Tooltip("Upper limit on how many obstacle hits to process.  Higher numbers may impact performance.  In most environments, 4 is enough.")]
public int m_MaximumEffort
Field Value
Type Description
Int32

m_MinimumDistanceFromTarget

Obstacles closer to the target than this will be ignored

Declaration
[Tooltip("Obstacles closer to the target than this will be ignored")]
public float m_MinimumDistanceFromTarget
Field Value
Type Description
Single

m_MinimumOcclusionTime

Don't take action unless occlusion has lasted at least this long.

Declaration
[Tooltip("Don't take action unless occlusion has lasted at least this long.")]
public float m_MinimumOcclusionTime
Field Value
Type Description
Single

m_OptimalTargetDistance

If greater than zero, a higher score will be given to shots when the target is closer to this distance. Set this to zero to disable this feature

Declaration
[Header("Shot Evaluation")]
[Tooltip("If greater than zero, a higher score will be given to shots when the target is closer to this distance.  Set this to zero to disable this feature.")]
public float m_OptimalTargetDistance
Field Value
Type Description
Single

m_SmoothingTime

Smoothing to apply to obstruction resolution. Nearest camera point is held for at least this long.

Declaration
[Range(0F, 2F)]
[Tooltip("Smoothing to apply to obstruction resolution.  Nearest camera point is held for at least this long")]
public float m_SmoothingTime
Field Value
Type Description
Single

m_Strategy

The way in which the Collider will attempt to preserve sight of the target.

Declaration
[Tooltip("The way in which the Collider will attempt to preserve sight of the target.")]
public CinemachineCollider.ResolutionStrategy m_Strategy
Field Value
Type Description
CinemachineCollider.ResolutionStrategy

m_TransparentLayers

Objects on these layers will never obstruct view of the target.

Declaration
[Tooltip("Objects on these layers will never obstruct view of the target")]
public LayerMask m_TransparentLayers
Field Value
Type Description
LayerMask

Properties

DebugPaths

Inspector API for debugging collision resolution path

Declaration
public List<List<Vector3>> DebugPaths { get; }
Property Value
Type Description
List<List<Vector3>>

Methods

CameraWasDisplaced(ICinemachineCamera)

See whether the virtual camera has been moved nby the collider

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

The virtual camera in question. This might be different from the virtual camera that owns the collider, in the event that the camera has children
Returns
Type Description
Boolean

True if the virtual camera has been displaced due to collision or target obstruction

GetCameraDisplacementDistance(ICinemachineCamera)

See how far the virtual camera wa moved nby the collider

Declaration
public float GetCameraDisplacementDistance(ICinemachineCamera vcam)
Parameters
Type Name Description
ICinemachineCamera vcam

The virtual camera in question. This might be different from the virtual camera that owns the collider, in the event that the camera has children
Returns
Type Description
Single

True if the virtual camera has been displaced due to collision or target obstruction

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

IsTargetObscured(ICinemachineCamera)

See whether an object is blocking the camera's view of the target

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

The virtual camera in question. This might be different from the virtual camera that owns the collider, in the event that the camera has children
Returns
Type Description
Boolean

True if something is blocking the view

OnDestroy()

Cleanup

Declaration
protected override void OnDestroy()
Overrides

PostPipelineStageCallback(CinemachineVirtualCameraBase, CinemachineCore.Stage, ref CameraState, Single)

Callback to do the collision resolution and shot evaluation

Declaration
protected override void PostPipelineStageCallback(CinemachineVirtualCameraBase vcam, CinemachineCore.Stage stage, ref CameraState state, float deltaTime)
Parameters
Type Name Description
CinemachineVirtualCameraBase vcam

The virtual camera being processed
CinemachineCore.Stage stage

The current pipeline stage
CameraState state

The current virtual camera state
Single deltaTime

The current applicable deltaTime
Overrides