Clarification and Enhancement Request: Cinemachine `PrioritySettings` Casting/Type Conversion Operators

Description

I would like to raise an issue regarding the PrioritySettings struct in the package, specifically its lack of custom operators for casting to/from int, either explicitly or implicitly. This concern arises from the recent (3.0.0) API changes and the subsequent challenges it poses for developers during the upgrading process.

Issue Details

In the previous API version, setting the camera priority was straightforward, as shown in the following code snippet:

cam.Priority = 1;

However, with the API update, the type has changed while the name remains the same. Because of that, this change can't be marked with an Obsolete attribute, so it doesn't provide in-IDE guidance for upgrading.

Though they mention it, the comments do not sufficiently clarify the need to set the priority value in my opinion:

The default priority is 0. Often it is sufficient to leave the default setting.
In special cases where you want a CinemachineCamera to have a higher or lower priority than 0,
the value can be set here.

Additionally, this issue is not addressed in the Cinemachine Upgrade Guide, leading to potential confusion among users, especially beginners. They might incorrectly assume the new assignment method as:

cam.Priority = new PrioritySettings();

cam.Priority = new PrioritySettings(){ Value = 1 };

Instead of the correct approach:

cam.Priority.Value = 1;

Suggested Enhancements

A. Adding Custom Operators: Implement custom operators for casting to/from int in the PrioritySettings struct. This would streamline the process and make it more intuitive, particularly given that the struct primarily serves as a wrapper around an integer.

B. Documentation Update: Revise the XML comments and the Upgrade Guide to clearly explain the new method of setting priority. This would help in reducing confusion and aid in smoother transitions for developers upgrading their projects.

Conclusion

The lack of custom operators and clear documentation for the PrioritySettings struct in the Cinemachine package poses unnecessary challenges in the upgrading process. Implementing (one of) these suggested enhancements would significantly improve the developer experience and reduce potential roadblocks.

Unity-Technologies / com.unity.cinemachine