Class CinemachineVirtualCamera
This behaviour is intended to be attached to an empty Transform GameObject, and it represents a Virtual Camera within the Unity scene.
The Virtual Camera will animate its Transform according to the rules contained in its CinemachineComponent pipeline (Aim, Body, and Noise). When the virtual camera is Live, the Unity camera will assume the position and orientation of the virtual camera.
A virtual camera is not a camera. Instead, it can be thought of as a camera controller, not unlike a cameraman. It can drive the Unity Camera and control its position, orientation, lens settings, and PostProcessing effects. Each Virtual Camera owns its own Cinemachine Component Pipeline, through which you provide the instructions for dynamically tracking specific game objects.
A virtual camera is very lightweight, and does no rendering of its own. It merely tracks interesting GameObjects, and positions itself accordingly. A typical game can have dozens of virtual cameras, each set up to follow a particular character or capture a particular event.
A Virtual Camera can be in any of three states:
- Live: The virtual camera is actively controlling the Unity Camera. The virtual camera is tracking its targets and being updated every frame.
- Standby: The virtual camera is tracking its targets and being updated every frame, but no Unity Camera is actively being controlled by it. This is the state of a virtual camera that is enabled in the scene but perhaps at a lower priority than the Live virtual camera.
- Disabled: The virtual camera is present but disabled in the scene. It is not actively tracking its targets and so consumes no processing power. However, the virtual camera can be made live from the Timeline.
The Unity Camera can be driven by any virtual camera in the scene. The game logic can choose the virtual camera to make live by manipulating the virtual cameras' enabled flags and their priorities, based on game logic.
In order to be driven by a virtual camera, the Unity Camera must have a CinemachineBrain behaviour, which will select the most eligible virtual camera based on its priority or on other criteria, and will manage blending.
Inheritance
Implements
Inherited Members
Namespace: Cinemachine
Assembly: solution.dll
Syntax
[DocumentationSorting(DocumentationSortingAttribute.Level.UserRef)]
[DisallowMultipleComponent]
[ExecuteInEditMode]
[ExcludeFromPreset]
[AddComponentMenu("Cinemachine/CinemachineVirtualCamera")]
public class CinemachineVirtualCamera : CinemachineVirtualCameraBase, ICinemachineCameraFields
| Name | Description |
|---|---|
| CreatePipelineOverride | 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. |
| DestroyPipelineOverride | Override component pipeline destruction. This needs to be done by the editor to support Undo. |
| PipelineName | This is the name of the hidden GameObject that will be created as a child object of the virtual camera. This hidden game object acts as a container for the polymorphic CinemachineComponent pipeline. The Inspector UI for the Virtual Camera provides access to this pipleline, as do the CinemachineComponent-family of public methods in this class. The lifecycle of the pipeline GameObject is managed automatically. |
| m_Follow | The object that the camera wants to move with (the Body target). The Body component of the CinemachineComponent pipeline will refer to this target and position the vcam in accordance with rules and settings that are provided to it. If this is null, then the vcam's Transform position will be used. |
| m_Lens | Specifies the LensSettings of this Virtual Camera. These settings will be transferred to the Unity camera when the vcam is live. |
| m_LookAt | The object that the camera wants to look at (the Aim target). The Aim component of the CinemachineComponent pipeline will refer to this target and orient the vcam in accordance with rules and settings that are provided to it. If this is null, then the vcam's Transform orientation will be used. |
| m_Transitions | Collection of parameters that influence how this virtual camera transitions from other virtual cameras |
Properties
| Name | Description |
|---|---|
| Follow | Get the Follow target for the Body component in the Cinemachine pipeline. If this vcam is a part of a meta-camera collection, then the owner's target will be used if the local target is null. |
| LookAt | Get the LookAt target for the Aim component in the Cinemachine pipeline. If this vcam is a part of a meta-camera collection, then the owner's target will be used if the local target is null. |
| State | The CameraState object holds all of the information necessary to position the Unity camera. It is the output of this class. |
| UserIsDragging | API for the editor, to make the dragging of position handles behave better. |
Methods
| Name | Description |
|---|---|
| AddCinemachineComponent<T>() | Add a component to the cinemachine pipeline. |
| DestroyCinemachineComponent<T>() | Remove a component from the cinemachine pipeline. |
| ForceCameraPosition(Vector3, Quaternion) | Force the virtual camera to assume a given position and orientation |
| GetCinemachineComponent(Stage) | Get the component set for a specific stage. |
| GetCinemachineComponent<T>() | Get an existing component of a specific type from the cinemachine pipeline. |
| GetComponentOwner() | Get the hidden CinemachinePipeline child object. |
| GetComponentPipeline() | Get the component pipeline owned by the hidden child pipline container. For most purposes, it is preferable to use the GetCinemachineComponent method. |
| GetMaxDampTime() | Query components and extensions for the maximum damping time. |
| InternalUpdateCameraState(Vector3, float) | Internal use only. Do not call this method. Called by CinemachineCore at the appropriate Update time so the vcam can position itself and track its targets. This class will invoke its pipeline and generate a CameraState for this frame. |
| InvalidateComponentPipeline() | Editor API: Call this when changing the pipeline from the editor. Will force a rebuild of the pipeline cache. |
| OnDestroy() | Calls the DestroyPipelineDelegate for destroying the hidden child object, to support undo. |
| OnEnable() | Make sure that the pipeline cache is up-to-date. |
| 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. |
| OnTransitionFromCamera(ICinemachineCamera, Vector3, float) | If we are transitioning from another vcam, grab the position from it. |
| OnValidate() | Enforce bounds for fields, when changed in inspector. |