Cinemachine Deoccluder

Cinemachine Deoccluder is an extension for the CinemachineCamera. It post-processes the final position of the CinemachineCamera to attempt to preserve the line of sight with the Look At target of the CinemachineCamera. It does this by moving away from the GameObjects that obstruct the view.

Add a Cinemachine Deoccluder extension to a CinemachineCamera to do any of the following tasks:

• Push the camera away from obstructing obstacles in the Scene.

• Place the camera in front of obstacles that come between the CinemachineCamera and its Look At target.

• Evaluate shot quality. Shot quality is a measure of the distance of the CinemachineCamera from its ideal position, the distance of the CinemachineCamera to its target, and the obstacles that block the view of the target. Other modules use shot quality, including Clear Shot.

The Deoccluder uses a Physics Raycaster. Therefore, Cinemachine Deoccluder requires that potential obstacles have collider volumes. There is a performance cost for this requirement. If this cost is prohibitive in your game, consider implementing this functionality differently.

Properties:

Property:		Function:
Collide Against		Cinemachine Deoccluder considers GameObjects in these layers to be potential obstacles. It ignores GameObjects that are not in the selected layers.
Minimum Distance From Target		Ignore obstacles that are less than this distance from the target's pivot point.
Avoid Obstacles		When enabled, the Deoccluder will move the camera in the Scene when the target is obscured by an obstacle. Use the Distance Limit, Camera Radius, Strategy, Smoothing Time, Minimum Occlusion Time, Damping, and DampingWhenOccluded properties to adjust how to avoid obstacles. If disabled, the Cinemachine Deoccluder will evaluate shot quality based on obstacles, but will not attempt to move the camera to improve the shot.
Distance Limit		The maximum raycast distance when checking if the line of sight to this camera’s target is clear. Enter 0 to use the current actual distance to the target. Available when Avoid Obstacles is checked.
Use Follow Target		When enabled, the Deoccluder will move the camera towards the Follow target instead of the LookAt target.
Y Offset		When Use Follow Target is enabled, the Follow target's Y position will be considered to be offset by this much in its local vertical direction.
Camera Radius		Distance to maintain from any obstacle. Try to keep this value small for the best results. Increase it if you are seeing inside obstacles due to a large FOV on the camera. Available when Avoid Obstacles is checked.
Strategy		The way in which the Deoccluder attempts to preserve sight of the target. Available when Avoid Obstacles is checked.
	Pull Camera Forward	Move the camera forward along its Z axis until it is in front of the obstacle that is nearest to the target.
	Preserve Camera Height	Move the camera to an alternate point of view while attempting to keep the camera at its original height.
	Preserve Camera Distance	Move the camera to an alternate point of view while attempting to keep the camera at its original distance from the target.
Smoothing Time		Minimum number of seconds to hold the camera at the nearest point to the target. Can be used to reduce excess camera movement in environments with lots of obstacles. Available when Avoid Obstacles is checked.
Damping		How quickly to return the camera to its normal position after an occlusion has gone away. Small numbers make the camera more responsive. Larger numbers make the camera respond more slowly. Available when Avoid Obstacles is checked.
Damping When Occluded		How quickly to move the camera to avoid an obstacle. Small numbers make the camera more responsive. Larger numbers make the camera respond more slowly. Available when Avoid Obstacles is checked.
Transparent Layers		Objects on these layers will never obstruct the view of the target.
Minimum Occlusion Time		Do not take action unless the occulsion has lasted at least this long.
Maximum Effort		Upper limit on how many obstacle hits to process. Higher numbers may impact performance. In most environments four (4) hits is enough.
Ignore Tag		Obstacles with this tag will be ignored. It is recommended to set this field to the target's tag.
Shot Quality Evaluation		If enabled, gives a higher score to shots when the target is closer to an optimal distance.
	Optimal Distance	Maximum quality boost will be given to the shot when the target is near this distance from the camera.
	Near Limit	Quality boost drops off as the target distance gets smaller than the optimal distance. When thie near limit is reached, quality is no longer boosted.
	Far Limit	Quality boost drops off as the target distance gets larger than the optimal distance. When thie far limit is reached, quality is no longer boosted.
	Max Quality Boost	This is the quality boost that will be given when the target is at the optimal distance. It is expresses as the fraction of the default quality that will get added in. For example, when this value is 0.5, the shot quality will be multiplied by 1.5.