Cinemachine integration needs a documentation update and example scene

[Cheo]

Hello, I finally decided to give the Cinemachine integration demo scene a try this morning, but the intial setup was a bit more complicated than expected because of some errors in the documentation page :

-The Cinemachine Brain should apparently be added to the UCC cam.

-The setup suggests creating a Cinemachine camera on Step 3, and then another camera under on the first substep for both perspective. Only a single Cinemachine camera should be needed for the purpose of this setup.

Edit : Missed the last step that says "The Virtual Camera with the highest priority will activate when the game starts.". This results in a counter intuitive situation in my opinion. If the priority is what matters, then why bother with the Virtual Camera field ? Also, if we drag in a virtual camera with a low priority, and have another camera with a higher priority, the latter takes precedence in the game view even before pressing play, and there is a transition between this cam and the one set in the field when starting the game.
I don't have much experience to Cinemachine to be entirely honest, so if you think I'm not looking at this clearly please do say so !

-Step 1 of the third person setup mentions the "Free Look Virtual Camera component", but I couldn't find it, only "Cinemachine Free Look". Unless I missed something it would be best to correct this name.

If we really try to follow along the setup, we get those 2 errors :

[Error] Error: A Cinemachine camera must first be setup in order to be used by the Cinemachine ViewType.
CinemachineViewType.Awake() at /Opsive/UltimateCharacterController/Integrations/Cinemachine/Scripts/CinemachineViewType.cs:143
 141:  m_Brain = m_CameraController.GetComponent<CinemachineBrain>();
 142:  if (m_Brain == null) {
--> 143:      Debug.LogError("Error: A Cinemachine camera must first be setup in order to be used by the Cinemachine ViewType.");
 144:      return;
 145:  }

CameraController.Awake() at /Opsive/UltimateCharacterController/Scripts/Camera/CameraController.cs:194
 192:  if (m_ViewTypes != null) {
 193:      for (int i = 0; i < m_ViewTypes.Length; ++i) {
--> 194:          m_ViewTypes[i].Awake();
 195:      }
 196:  }

[Exception] NullReferenceException: Object reference not set to an instance of an object
CinemachineViewType.UpdateFreeLookCameraValues() at /Opsive/UltimateCharacterController/Integrations/Cinemachine/Scripts/CinemachineViewType.cs:214
 212:  private void UpdateFreeLookCameraValues()
 213:  {
--> 214:      if (m_Brain.ActiveVirtualCamera == null) {
 215:          return;
 216:      }

CinemachineViewType.Reset() at /Opsive/UltimateCharacterController/Integrations/Cinemachine/Scripts/CinemachineViewType.cs:250
 248:  public override void Reset(Quaternion characterRotation)
 249:  {
--> 250:      UpdateFreeLookCameraValues();
 251:      if (m_SpringExtension != null) {
 252:          m_SpringExtension.PositionCorrection = Vector3.zero;

CameraController.PositionImmediately() at /Opsive/UltimateCharacterController/Scripts/Camera/CameraController.cs:876
 874:      // Reset the view type's variables.
 875:      for (int i = 0; i < m_ViewTypes.Length; ++i) {
--> 876:          m_ViewTypes[i].Reset(m_CharacterRigidbody.rotation);
 877:      }
 878:  }

CameraController.PositionImmediately() at /Opsive/UltimateCharacterController/Scripts/Camera/CameraController.cs:859
 857:  public void PositionImmediately()
 858:  {
--> 859:      PositionImmediately(true);
 860:  }

InvokableAction.Invoke() at <52329c5bb9d24a17aa3c9cbeab267298>:0

EventHandler.ExecuteEvent() at <52329c5bb9d24a17aa3c9cbeab267298>:0

AnimatorMonitor.SnapAnimator() at /Opsive/UltimateCharacterController/Scripts/Character/AnimatorMonitor.cs:323
 322:  if (executeEvent) {
--> 323:      EventHandler.ExecuteEvent(m_GameObject, "OnAnimatorWillSnap");
 324:  }

Opsive.Shared.Events.InvokableAction`1[T1].Invoke() at <52329c5bb9d24a17aa3c9cbeab267298>:0

EventHandler.ExecuteEvent[T1]() at <52329c5bb9d24a17aa3c9cbeab267298>:0

UltimateCharacterLocomotion.Start() at /Opsive/UltimateCharacterController/Scripts/Character/UltimateCharacterLocomotion.cs:509
 508:  // The abilities may have updated the animator.
--> 509:  EventHandler.ExecuteEvent(m_GameObject, "OnCharacterSnapAnimator", true);
 511:  // The character isn't moving at the start.

I've already asked for more or better integration demo scenes, and this is no exception - we need a simple scene featuring a standard character with both perspectives availables and using Cinemachine for both. Once again, this will serve as a proof of correct functioning and give an example of how to set this up. Thanks in advance.

 

[Justin]

-The Cinemachine Brain should apparently be added to the UCC cam.

I'll make that clarification.

-The setup suggests creating a Cinemachine camera on Step 3, and then another camera under on the first substep for both perspective. Only a single Cinemachine camera should be needed for the purpose of this setup.

This step indicates adding the Cinemachine Virtual Camera, not another camera. The Virtual Camera does not contain the Camera component.

-Step 1 of the third person setup mentions the "Free Look Virtual Camera component", but I couldn't find it, only "Cinemachine Free Look". Unless I missed something it would be best to correct this name.

The Free Look component is a subclass of the Virtual Camera component. I'll make sure to specify that.

I have a Cinemachine scene for testing but did not include it in the integration due to it not being ready for publishing.

 

[Cheo]

This step indicates adding the Cinemachine Virtual Camera, not another camera. The Virtual Camera does not contain the Camera component.

Yes, I know that a Virtual Camera doesn't come with a Camera component, but that's not what I'm talking about - step 3 says "Create a Cinemachine camera (through the Cinemachine toolbar)" and step 5-1 says "Create a new GameObject and add the Cinemachine Free Look component". If we do that we end up with 2 cinemachine cameras, that's just what I'm saying.

A very basic scene would definitely be better than nothing, once again just a character with a cinemachine cam for both perspectives could be helpful and enough for the moment.