feat: sdk camera control components

[pravusjif]

Implements support for new SDK Camera Control components, high level changes:

• Implemented MainCamera plugin and MainCameraSystem to handle the new SDK components MainCamera and VirtualCamera
• Moved SDKComponents/CameraModeArea/ into new SDKComponents/CameraControl/CameraModeArea (many file changes come from that)
• Updated WriteCameraComponentSystem to put the MainCamera component on the scene camera CRDT Entity along with the other components already being set up during initialization
• Translated character camera blends to use ** ANY CAMERA **, maintaining the same existing easing and time. Behaviour-wise nothing changes regarding the existing character cameras.
• Set up spherical blend hint for character camera's Third Person Cam and Drone cam. Thus being able to return to the character's camera on the nearest position from the last SDK virtual camera.
• Changed AvatarShapeVisibilitySystem to change the main player avatar visibility based on camera distance instead of camera mode, since of course SDK Virtual Cameras are enabled far away from the main player. Commit.
• Introduced new CameraMode.SDKCamera to easily handle avoiding First Person chara input controls in CalculateCharacterVelocitySystem when an SDK Virtual Cam is activated. This also automatically avoids any problem with AvatarModifierArea. Commit.
• Added raw CameraMode tracking in ExposedCameraData and injected it into UpdateCursorInputSystem to be able to hide the corsshair when an SDK camera is being used. Commit.
• Added minimum distance check in BillboardSystem to avoid it conflicting with a VirtualCamera on the same entity or too close to the billboard entity (e.g. in the parent entity). Commit.
• Refactored CharacterTriggerArea plugin systems to avoid conflicting with the new SDK Camera, going from a "per frame" detected avatars collection to a "to be processed" avatars collection. Commit + Commit.

Related PRs

• feat: camera control components protocol#214
• feat: camera control components js-sdk-toolchain#990
• chore: virtual cameras test scene sdk7-test-scenes#13

QA TEST INSTRUCTIONS

• Download this PR's Explorer build
• Access the pravus.dcl.eth world for running the test scene (/goto pravus)
• Once the scene loads you are ready to test
  • Pressing 'E' will cycle between the scene virtual cameras
  • When you are with the Character default camera, if you look up you will be able to see the 4 entities that have virtual cameras (represented as cubes). The numbers represent the order in which they will be cycled.

Things to test:

Using the Character default camera

1. Enter the Avatar Modifier Area and exit it (being in third person cam), confirm that the Avatar is hidden only when inside the area.
2. Being in Third Person Cam enter the Camera Mode Area and confirm that the camera is forcefully changed to 1st perdon cam. Check that you can't change the camera mode inside that area but that it resets when you get out of it.

Using the SDK Camera 1

1. Confirm that you can move normally as you would if you were in third person cam.
2. Enter the Avatar Modifier Area and exit it, confirm that the Avatar is hidden only when inside the area.
3. Enter the Camera Mode Area and confirm that it doesn't change the camera at all.

Using the SDK Camera 2

1. Confirm that you can move normally as you would if you were in third person cam.
2. Enter the Avatar Modifier Area and exit it, confirm that the Avatar is hidden only when inside the area.
3. Enter the Camera Mode Area and confirm that it doesn't change the camera at all.
4. Exit the scene, and confirm that the camera goes back to the Character default camera and you can still control it. Then re-enter the scene and check that the last SDK Camera that was active is now active again.

Using the SDK Camera 3

1. Confirm that this camera constantly looks at the player, even when you move the player.
2. Confirm that you can move normally as you would if you were in third person cam.
3. Enter the Avatar Modifier Area and exit it, confirm that the Avatar is hidden only when inside the area.
4. Enter the Camera Mode Area and confirm that it doesn't change the camera at all.
5. Exit the scene, and confirm that the camera goes back to the Character default camera and you can still control it. Then re-enter the scene and check that the last SDK Camera that was active is now active again.

Using the SDK Camera 4

1. Confirm that you can move normally as you would if you were in third person cam.
2. Enter the Avatar Modifier Area and exit it, confirm that the Avatar is hidden only when inside the area.
3. Enter the Camera Mode Area and confirm that it doesn't change the camera at all.
4. Exit the scene, and confirm that the camera goes back to the Character default camera and you can still control it. Then re-enter the scene and check that the last SDK Camera that was active is now active again.

Camera Mode Area

1. Being in character's default camera
   -> move inside the CameraModeArea that will force 1st person cam
   -> press 'E' to activate any SDK camera (doesn't matter which one)
   -> cycle through the cameras until you get back to the character camera
   -> confirm that you are again under the effect of the Camera Mode Area
   -> get out of the Camera Mode Area and confirm you can control the camera again
2. Being in character's default camera
   -> press 'E' to activate any SDK camera (doesn't matter which one)
   -> move the character inside the CameraModeArea
   -> cycle through the cameras until you get back to the character camera
   -> confirm that you are now under the effect of the Camera Mode Area
   -> get out of the Camera Mode Area and confirm you can control the camera again
3. Being in character's default camera
   -> move inside the CameraModeArea that will force 1st person cam
   -> press 'E' to activate any SDK camera (doesn't matter which one)
   -> move the character outside the Camera Mode Area
   -> cycle through the cameras until you get back to the character camera
   -> confirm that you free from the effect of the Camera Mode Area and you can control the camera again
4. Being in character's default camera
   -> move inside the CameraModeArea that will force 1st person cam
   -> press 'E' to activate any SDK camera (doesn't matter which one)
   -> move the character outside the Camera Mode Area
   -> move the character inside the Camera Mode Area again
   -> cycle through the cameras until you get back to the character camera
   -> confirm that you are still under the effect of the Camera Mode Area
   -> get out of the Camera Mode Area and confirm you can control the camera again
5. Being in character's default camera
   -> press 'E' to activate any SDK camera (doesn't matter which one)
   -> move the character inside the Camera Mode Area
   -> move the character outside the Camera Mode Area again
   -> cycle through the cameras until you get back to the character camera
   -> confirm that you are still free from the effect of the Camera Mode Area

Video reference for testing

SDKCameraControlDemo-NO-CONTROLLABLE-CAM.mp4

Summary by CodeRabbit

• New Features

  • Enhanced avatar visibility logic based on camera distance for improved performance.
  • Improved avatar interaction tracking with new collections for processing.
  • Introduced new assets and updated existing asset references for better organization.
  • Added a new MainCameraSystem for improved camera management.
  • Introduced MainCameraComponent for advanced camera control.
  • Added a new MainCameraPlugin for enhanced camera functionalities.

• Bug Fixes

  • Streamlined avatar state management to enhance clarity and performance.

• Documentation

  • Updated documentation to reflect changes in avatar visibility and interaction tracking.

• Chores

  • Added metadata files for new assets to improve asset management.

[github-actions]

New build in progress, come back later!

[coderabbitai]

Actionable comments posted: 3

Review details

Configuration used: CodeRabbit UI
Review profile: CHILL

Commits

Files that changed from the base of the PR and between 5c42442 and 57fb7f7.

Files selected for processing (5)

• Explorer/Assets/DCL/PerformanceAndDiagnostics/Diagnostics/ReportsHandling/ReportCategory.cs (1 hunks)
• Explorer/Assets/DCL/SDKComponents/AvatarModifierArea/Systems/AvatarModifierAreaHandlerSystem.cs (2 hunks)
• Explorer/Assets/DCL/SDKComponents/CameraControl/CameraModeArea/Systems/CameraModeAreaHandlerSystem.cs (4 hunks)
• Explorer/Assets/DCL/SDKComponents/CameraControl/MainCamera/Systems/MainCameraSystem.cs (1 hunks)
• Explorer/Assets/DCL/SDKComponents/CameraControl/MainCamera/Systems/VirtualCameraSystem.cs (1 hunks)

Files skipped from review as they are similar to previous changes (2)

• Explorer/Assets/DCL/PerformanceAndDiagnostics/Diagnostics/ReportsHandling/ReportCategory.cs
• Explorer/Assets/DCL/SDKComponents/AvatarModifierArea/Systems/AvatarModifierAreaHandlerSystem.cs

Additional context used

Path-based instructions (3)

Explorer/Assets/DCL/SDKComponents/CameraControl/MainCamera/Systems/VirtualCameraSystem.cs (2)

Pattern **/*.cs: Review the code for heap allocations and suggest potential improvements to avoid runtime allocations.

---

Pattern **/*.cs: Review the code for specific unity engine optimizations and suggest potential improvements.

Explorer/Assets/DCL/SDKComponents/CameraControl/CameraModeArea/Systems/CameraModeAreaHandlerSystem.cs (2)

Pattern **/*.cs: Review the code for heap allocations and suggest potential improvements to avoid runtime allocations.

---

Pattern **/*.cs: Review the code for specific unity engine optimizations and suggest potential improvements.

Explorer/Assets/DCL/SDKComponents/CameraControl/MainCamera/Systems/MainCameraSystem.cs (2)

Pattern **/*.cs: Review the code for heap allocations and suggest potential improvements to avoid runtime allocations.

---

Pattern **/*.cs: Review the code for specific unity engine optimizations and suggest potential improvements.

Additional comments not posted (8)

Explorer/Assets/DCL/SDKComponents/CameraControl/MainCamera/Systems/VirtualCameraSystem.cs (1)

1-86: LGTM!

The VirtualCameraSystem class is well-implemented and follows good practices. The use of dependency injection, attribute usage, and component pools is commendable. The class effectively handles the setup, removal, and finalization of virtual cameras. The code is clean, readable, and follows a clear structure.

The changes are approved.

Explorer/Assets/DCL/SDKComponents/CameraControl/MainCamera/Systems/MainCameraSystem.cs (1)

101-101: **Add a check for `sceneStateProvider.

Explorer/Assets/DCL/SDKComponents/CameraControl/CameraModeArea/Systems/CameraModeAreaHandlerSystem.cs (6)

29-35: ****

The following comment from the previous review is still valid:

coderabbitai[bot]: Refactor suggestion: Consider using dependency injection for cameraData.

The constructor now includes an additional parameter IExposedCameraData cameraData which is a significant change. To enhance testability and maintainability, consider using dependency injection for cameraData instead of directly passing it through the constructor. This approach would make it easier to manage dependencies and mock them during testing.

---

59-83: ****

The following comment from the previous review is still valid:

coderabbitai[bot]: Optimization: Reduce complexity in UpdateCameraModeArea.

The method UpdateCameraModeArea has been expanded significantly to handle new checks for EnteredAvatarsToBeProcessed and ExitedAvatarsToBeProcessed. Consider refactoring this method to reduce complexity and improve readability. Splitting the method into smaller, more focused methods could help manage the different conditions and actions more clearly.

---

66-66: ****

The following comment from the previous review is still valid:

mikhail-dcl: You can remove nullable suppression as the lists are defined as non-nullables

---

25-25: ****

The following comment from the previous review is still valid:

mikhail-dcl: It would be great to pool this hashset on Initialize/Dispose

---

88-91: LGTM!

The code changes are approved.

---

97-101: LGTM!

The code changes are approved.

Also applies to: 126-130

[coderabbitai]

Actionable comments posted: 6

Review details

Configuration used: CodeRabbit UI
Review profile: CHILL

Commits

Files that changed from the base of the PR and between ed358d5 and 3bd6d36.

Files selected for processing (1)

• Explorer/Assets/DCL/SDKComponents/CameraControl/MainCamera/Systems/MainCameraSystem.cs (1 hunks)

Additional context used

Path-based instructions (1)

Explorer/Assets/DCL/SDKComponents/CameraControl/MainCamera/Systems/MainCameraSystem.cs (2)

Pattern **/*.cs: Review the code for heap allocations and suggest potential improvements to avoid runtime allocations.

---

Pattern **/*.cs: Review the code for specific unity engine optimizations and suggest potential improvements.

Additional comments not posted (5)

Explorer/Assets/DCL/SDKComponents/CameraControl/MainCamera/Systems/MainCameraSystem.cs (5)

48-58: LGTM!

The Update method looks good. It delegates the work to specific query methods, which is a good practice. There are no obvious issues or potential optimizations in this method.

---

113-119: LGTM!

The DisableVirtualCameraOnSceneLeave method looks good. It has a clear purpose and delegates the actual disabling of the virtual camera to a separate method, which is a good practice. There are no obvious issues or potential optimizations in this method.

---

121-129: LGTM!

The SetupMainCamera method looks good. It has a clear purpose and adds the necessary component to the camera entity. There are no obvious issues or potential optimizations in this method.

---

131-137: LGTM!

The HandleMainCameraRemoval method looks good. It has a clear purpose and removes the necessary component from the camera entity. There are no obvious issues or potential optimizations in this method.

---

139-144: LGTM!

The HandleMainCameraEntityDestruction method looks good. It has a clear purpose and disables the active virtual camera when the main camera entity is destroyed. There are no obvious issues or potential optimizations in this method.

[mikhail-dcl]

Good job 💪 I only have one question but can approve upfront

[pravusjif]

restored branch temporarily until I adapt the Test Coverage PR that currently is based on this branch