docs: [Backport] fixes of PVP-150-1 [1.X] (#3292)

* Fixes of PVP-150-1

* Remaining fixes

* update

Updating some of the missing XML API documentation.

* Deleted fixed pvp 150-1 exceptions

* Moved pvpExceptions file and modified pack and test commands

* Added missing artifacts

* Corrected utr command

* Removed unnecessary pvpExtension

* Extended 151-1 exceptions

* More API docs fixes

* Updated pvpExceptions file

---------

Co-authored-by: NoelStephensUnity <[email protected]>

Author: michalChrobot

.yamato/package-pack.yml

@@ -12,12 +12,16 @@ package_pack_-_ngo_{{ platform.name }}:
     image: {{ platform.image }}
     flavor: {{ platform.flavor }}
   timeout: 0.25
+  variables:
+    XRAY_PROFILE: "supported ./pvpExceptions.json"
   commands:
-    - npm install -g upm-ci-utils@stable --registry https://artifactory.prd.it.unity3d.com/artifactory/api/npm/upm-npm
-    - upm-ci package pack --package-path com.unity.netcode.gameobjects
-    - upm-pvp xray --packages "upm-ci~/packages/*.tgz" --results upm-ci~/xray
-    - upm-pvp require "supported rme com.unity.netcode.gameobjects/pvpExceptions.json" --allow-missing --results upm-ci~/xray --exemptions upm-ci~/xray/new-exemptions.json
+    - upm-pvp pack "com.unity.netcode.gameobjects" --output upm-ci~/packages
+    - upm-pvp xray --packages "upm-ci~/packages/com.unity.netcode.gameobjects*.tgz" --results pvp-results
+    - upm-pvp require {% if platform.name == "win" %}"%XRAY_PROFILE%"{% else %}"$XRAY_PROFILE"{% endif %} --results pvp-results --allow-missing
   artifacts:
+    logs:
+      paths:
+        - "pvp-results/*"
     packages:
       paths:
         - "upm-ci~/**"

.yamato/package-tests.yml

@@ -12,14 +12,30 @@ package_test_-_ngo_{{ editor }}_{{ platform.name }}:
     type: {{ platform.type }}
     image: {{ platform.image }}
     flavor: {{ platform.flavor }}
+  variables:
+    XRAY_PROFILE: "supported ./pvpExceptions.json"
+    UNITY_EXT_LOGGING: 1
   commands:
-    - npm install -g upm-ci-utils@stable --registry https://artifactory.prd.cds.internal.unity3d.com/artifactory/api/npm/upm-npm
     - unity-downloader-cli -u {{ editor }} -c Editor --fast --wait
-    - {% if platform.name == "ubuntu" %}DISPLAY=:0 {% endif %}upm-ci package test -u {{ editor }} --package-path com.unity.netcode.gameobjects --type package-tests --extra-utr-arg="--extra-editor-arg=-testCategory --extra-editor-arg=!Performance --reruncount=1 --clean-library-on-rerun"
+    # Platform specific UTR setup
+    - |
+{% if platform.name == "win" %}
+      curl -s https://artifactory.prd.it.unity3d.com/artifactory/unity-tools-local/utr-standalone/utr.bat --output utr.bat
+{% else %}
+      curl -s https://artifactory.prd.it.unity3d.com/artifactory/unity-tools-local/utr-standalone/utr --output utr && chmod +x utr
+{% endif %}
+  
+    # Validate packages.
+    - upm-pvp test --unity .Editor --packages "upm-ci~/packages/*.tgz" --filter "com.unity.netcode.gameobjects" --results pvp-results
+    - upm-pvp require {% if platform.name == "win" %}"%XRAY_PROFILE%"{% else %}"$XRAY_PROFILE"{% endif %} --results pvp-results
+    # Run UTR to test packages.
+    - upm-pvp create-test-project test-project --packages "upm-ci~/packages/*.tgz" --filter "com.unity.netcode.gameobjects" --unity .Editor
+    - {% if platform.name == "ubuntu" %}DISPLAY=:0 {% endif %} {% if platform.name == "win" %} utr.bat {% else %} ./utr {% endif %} --suite=editor --suite=playmode --editor-location=.Editor --testproject=test-project --artifacts-path=test-results "--ff={ops.upmpvpevidence.enable=true}" --extra-editor-arg=-testCategory --extra-editor-arg=!Performance --reruncount=1 --clean-library-on-rerun
   artifacts:
     logs:
       paths:
         - "upm-ci~/test-results/**/*"
+        - "pvp-results/*"
   dependencies:
     - .yamato/package-pack.yml#package_pack_-_ngo_{{ platform.name }}
 {% endfor -%}

com.unity.netcode.gameobjects/Components/AnticipatedNetworkTransform.cs

@@ -13,24 +13,24 @@ namespace Unity.Netcode.Components
     ///
     /// <list type="bullet">
     ///
-    /// <item><b>Snap:</b> In this mode (with <see cref="StaleDataHandling"/> set to
+    /// <item><description><b>Snap:</b> In this mode (with <see cref="StaleDataHandling"/> set to
     /// <see cref="StaleDataHandling.Ignore"/> and no <see cref="NetworkBehaviour.OnReanticipate"/> callback),
     /// the moment a more up-to-date value is received from the authority, it will simply replace the anticipated value,
-    /// resulting in a "snap" to the new value if it is different from the anticipated value.</item>
+    /// resulting in a "snap" to the new value if it is different from the anticipated value.</description></item>
     ///
-    /// <item><b>Smooth:</b> In this mode (with <see cref="StaleDataHandling"/> set to
+    /// <item><description><b>Smooth:</b> In this mode (with <see cref="StaleDataHandling"/> set to
     /// <see cref="Netcode.StaleDataHandling.Ignore"/> and an <see cref="NetworkBehaviour.OnReanticipate"/> callback that calls
     /// <see cref="Smooth"/> from the anticipated value to the authority value with an appropriate
     /// <see cref="Mathf.Lerp"/>-style smooth function), when a more up-to-date value is received from the authority,
-    /// it will interpolate over time from an incorrect anticipated value to the correct authoritative value.</item>
+    /// it will interpolate over time from an incorrect anticipated value to the correct authoritative value.</description></item>
     ///
-    /// <item><b>Constant Reanticipation:</b> In this mode (with <see cref="StaleDataHandling"/> set to
+    /// <item><description><b>Constant Reanticipation:</b> In this mode (with <see cref="StaleDataHandling"/> set to
     /// <see cref="Netcode.StaleDataHandling.Reanticipate"/> and an <see cref="NetworkBehaviour.OnReanticipate"/> that calculates a
     /// new anticipated value based on the current authoritative value), when a more up-to-date value is received from
     /// the authority, user code calculates a new anticipated value, possibly calling <see cref="Smooth"/> to interpolate
     /// between the previous anticipation and the new anticipation. This is useful for values that change frequently and
     /// need to constantly be re-evaluated, as opposed to values that change only in response to user action and simply
-    /// need a one-time anticipation when the user performs that action.</item>
+    /// need a one-time anticipation when the user performs that action.</description></item>
     ///
     /// </list>
     ///
@@ -135,7 +135,7 @@ public bool ShouldReanticipate
         /// Anticipate that, at the end of one round trip to the server, this transform will be in the given
         /// <see cref="newPosition"/>
         /// </summary>
-        /// <param name="newPosition"></param>
+        /// <param name="newPosition">The anticipated position</param>
         public void AnticipateMove(Vector3 newPosition)
         {
             if (NetworkManager.ShutdownInProgress || !NetworkManager.IsListening)
@@ -162,7 +162,7 @@ public void AnticipateMove(Vector3 newPosition)
         /// Anticipate that, at the end of one round trip to the server, this transform will have the given
         /// <see cref="newRotation"/>
         /// </summary>
-        /// <param name="newRotation"></param>
+        /// <param name="newRotation">The anticipated rotation</param>
         public void AnticipateRotate(Quaternion newRotation)
         {
             if (NetworkManager.ShutdownInProgress || !NetworkManager.IsListening)
@@ -189,7 +189,7 @@ public void AnticipateRotate(Quaternion newRotation)
         /// Anticipate that, at the end of one round trip to the server, this transform will have the given
         /// <see cref="newScale"/>
         /// </summary>
-        /// <param name="newScale"></param>
+        /// <param name="newScale">The anticipated scale</param>
         public void AnticipateScale(Vector3 newScale)
         {
             if (NetworkManager.ShutdownInProgress || !NetworkManager.IsListening)
@@ -216,7 +216,7 @@ public void AnticipateScale(Vector3 newScale)
         /// Anticipate that, at the end of one round trip to the server, the transform will have the given
         /// <see cref="newState"/>
         /// </summary>
-        /// <param name="newState"></param>
+        /// <param name="newState">The anticipated transform state</param>
         public void AnticipateState(TransformState newState)
         {
             if (NetworkManager.ShutdownInProgress || !NetworkManager.IsListening)
@@ -405,9 +405,9 @@ public override void OnDestroy()
         /// <see cref="to"/> over <see cref="durationSeconds"/> of real time. The duration uses
         /// <see cref="Time.deltaTime"/>, so it is affected by <see cref="Time.timeScale"/>.
         /// </summary>
-        /// <param name="from"></param>
-        /// <param name="to"></param>
-        /// <param name="durationSeconds"></param>
+        /// <param name="from">Starting transform state</param>
+        /// <param name="to">Target transform state</param>
+        /// <param name="durationSeconds">Interpolation time in seconds</param>
         public void Smooth(TransformState from, TransformState to, float durationSeconds)
         {
             var transform_ = transform;

com.unity.netcode.gameobjects/Components/HalfVector3.cs

@@ -8,7 +8,7 @@ namespace Unity.Netcode.Components
     /// Half float precision <see cref="Vector3"/>.
     /// </summary>
     /// <remarks>
-    /// The Vector3T<ushort> values are half float values returned by <see cref="Mathf.FloatToHalf(float)"/> for each
+    /// The Vector3T{ushort} values are half float values returned by <see cref="Mathf.FloatToHalf(float)"/> for each
     /// individual axis and the 16 bits of the half float are stored as <see cref="ushort"/> values since C# does not have
     /// a half float type.
     /// </remarks>
@@ -129,7 +129,7 @@ public void UpdateFrom(ref Vector3 vector3)
         /// Constructor
         /// </summary>
         /// <param name="vector3">The initial axial values (converted to half floats) when instantiated.</param>
-        /// <param name="vector3AxisToSynchronize">The axis to synchronize.</param>
+        /// <param name="axisToSynchronize">The axis to synchronize.</param>
         public HalfVector3(Vector3 vector3, bool3 axisToSynchronize)
         {
             Axis = half3.zero;

com.unity.netcode.gameobjects/Components/HalfVector4.cs

@@ -8,7 +8,7 @@ namespace Unity.Netcode.Components
     /// Half Precision <see cref="Vector4"/> that can also be used to convert a <see cref="Quaternion"/> to half precision.
     /// </summary>
     /// <remarks>
-    /// The Vector4T<ushort> values are half float values returned by <see cref="Mathf.FloatToHalf(float)"/> for each
+    /// The Vector4T{ushort} values are half float values returned by <see cref="Mathf.FloatToHalf(float)"/> for each
     /// individual axis and the 16 bits of the half float are stored as <see cref="ushort"/> values since C# does not have
     /// a half float type.
     /// </remarks>

com.unity.netcode.gameobjects/Components/Interpolator/BufferedLinearInterpolator.cs

@@ -352,7 +352,7 @@ protected override Quaternion Interpolate(Quaternion start, Quaternion end, floa
     }
 
     /// <summary>
-    /// A <see cref="BufferedLinearInterpolator<T>"/> <see cref="Vector3"/> implementation.
+    /// A <see cref="BufferedLinearInterpolator{T}"/> <see cref="Vector3"/> implementation.
     /// </summary>
     public class BufferedLinearInterpolatorVector3 : BufferedLinearInterpolator<Vector3>
     {

com.unity.netcode.gameobjects/Editor/NetworkTransformEditor.cs

@@ -39,7 +39,7 @@ public class NetworkTransformEditor : UnityEditor.Editor
 
         public virtual bool HideInterpolateValue => false;
 
-        /// <inheritdoc/>
+        /// <inheritdoc cref="UnityEditor.Editor.OnEnable"/>
         public void OnEnable()
         {
             m_UseUnreliableDeltas = serializedObject.FindProperty(nameof(NetworkTransform.UseUnreliableDeltas));

com.unity.netcode.gameobjects/Runtime/Configuration/NetworkConfig.cs

@@ -152,7 +152,7 @@ public class NetworkConfig
         /// <summary>
         /// Returns a base64 encoded version of the configuration
         /// </summary>
-        /// <returns></returns>
+        /// <returns>base64 encoded string containing the serialized network configuration</returns>
         public string ToBase64()
         {
             NetworkConfig config = this;
@@ -219,8 +219,8 @@ internal void ClearConfigHash()
         /// <summary>
         /// Gets a SHA256 hash of parts of the NetworkConfig instance
         /// </summary>
-        /// <param name="cache"></param>
-        /// <returns></returns>
+        /// <param name="cache">When true, caches the computed hash value for future retrievals, when false, always recomputes the hash</param>
+        /// <returns>A 64-bit hash value representing the configuration state</returns>
         public ulong GetConfig(bool cache = true)
         {
             if (m_ConfigHash != null && cache)
@@ -264,8 +264,11 @@ public ulong GetConfig(bool cache = true)
         /// <summary>
         /// Compares a SHA256 hash with the current NetworkConfig instances hash
         /// </summary>
-        /// <param name="hash"></param>
-        /// <returns></returns>
+        /// <param name="hash">The 64-bit hash value to compare against this configuration's hash</param>
+        /// <returns>
+        /// True if the hashes match, indicating compatible configurations.
+        /// False if the hashes differ, indicating potentially incompatible configurations.
+        /// </returns>
         public bool CompareConfig(ulong hash)
         {
             return hash == GetConfig();

com.unity.netcode.gameobjects/Runtime/Configuration/NetworkPrefabsList.cs

@@ -38,7 +38,7 @@ public class NetworkPrefabsList : ScriptableObject
         /// Adds a prefab to the prefab list. Performing this here will apply the operation to all
         /// <see cref="NetworkManager"/>s that reference this list.
         /// </summary>
-        /// <param name="prefab"></param>
+        /// <param name="prefab">The NetworkPrefab to add to the shared list</param>
         public void Add(NetworkPrefab prefab)
         {
             List.Add(prefab);
@@ -49,7 +49,7 @@ public void Add(NetworkPrefab prefab)
         /// Removes a prefab from the prefab list. Performing this here will apply the operation to all
         /// <see cref="NetworkManager"/>s that reference this list.
         /// </summary>
-        /// <param name="prefab"></param>
+        /// <param name="prefab">The NetworkPrefab to remove from the shared list</param>
         public void Remove(NetworkPrefab prefab)
         {
             List.Remove(prefab);

com.unity.netcode.gameobjects/Runtime/Core/NetworkManager.cs

@@ -480,15 +480,19 @@ public struct ConnectionApprovalRequest
         /// <summary>
         /// This callback is invoked once the local server is stopped.
         /// </summary>
-        /// <remarks>The bool parameter will be set to true when stopping a host instance and false when stopping a server instance.</remarks>
-        /// <param name="arg1">The first parameter of this event will be set to <see cref="true"/> when stopping a host instance and <see cref="false"/> when stopping a server instance.</param>
+        /// <remarks>
+        /// The bool parameter will be set to true when stopping a host instance and false when stopping a server instance.
+        /// The first parameter of this event will be set to <see cref="true"/> when stopping a host instance and <see cref="false"/> when stopping a server instance.
+        /// </remarks>
         public event Action<bool> OnServerStopped = null;
 
         /// <summary>
         /// The callback to invoke once the local client stops.
         /// </summary>
-        /// <remarks>The bool parameter will be set to true when stopping a host client and false when stopping a standard client instance.</remarks>
-        /// <param name="arg1">The first parameter of this event will be set to <see cref="true"/> when stopping the host client and <see cref="false"/> when stopping a standard client instance.</param>
+        /// <remarks>
+        /// The bool parameter will be set to true when stopping a host client and false when stopping a standard client instance.
+        /// The first parameter of this event will be set to <see cref="true"/> when stopping the host client and <see cref="false"/> when stopping a standard client instance.
+        /// </remarks>
         public event Action<bool> OnClientStopped = null;
 
         /// <summary>
@@ -757,14 +761,14 @@ private void OnEnable()
         /// <summary>
         /// <see cref="NetworkPrefabHandler.AddNetworkPrefab(GameObject)"/>
         /// </summary>
-        /// <param name="prefab"></param>
-        /// <exception cref="Exception"></exception>
+        /// <param name="prefab">The GameObject prefab to be registered. Must not be null and must have a NetworkObject component.</param>
+        /// <exception cref="Exception">Thrown when the prefab is null or missing required components.</exception>
         public void AddNetworkPrefab(GameObject prefab) => PrefabHandler.AddNetworkPrefab(prefab);
 
         /// <summary>
         /// <see cref="NetworkPrefabHandler.RemoveNetworkPrefab(GameObject)"/>
         /// </summary>
-        /// <param name="prefab"></param>
+        /// <param name="prefab">The GameObject prefab to be unregistered. Must not be null and must have been previously registered.</param>
         public void RemoveNetworkPrefab(GameObject prefab) => PrefabHandler.RemoveNetworkPrefab(prefab);
 
         /// <summary>
@@ -776,7 +780,6 @@ private void OnEnable()
         /// and thus should be large enough to ensure it can hold each message type.
         /// This value defaults to 1296.
         /// </summary>
-        /// <param name="size"></param>
         public int MaximumTransmissionUnitSize
         {
             set => MessageManager.NonFragmentedMessageMaxSize = value & ~7; // Round down to nearest word aligned size
@@ -788,8 +791,8 @@ public int MaximumTransmissionUnitSize
         /// This determines the maximum size of a message batch that can be sent to that client.
         /// If not set for any given client, <see cref="MaximumTransmissionUnitSize"/> will be used instead.
         /// </summary>
-        /// <param name="clientId"></param>
-        /// <param name="size"></param>
+        /// <param name="clientId">The unique identifier of the client to set the MTU for.</param>
+        /// <param name="size">The maximum transmission unit size in bytes for this specific client.</param>
         public void SetPeerMTU(ulong clientId, int size)
         {
             MessageManager.PeerMTUSizes[clientId] = size;
@@ -799,8 +802,8 @@ public void SetPeerMTU(ulong clientId, int size)
         /// Queries the current MTU size for a client.
         /// If no MTU has been set for that client, will return <see cref="MaximumTransmissionUnitSize"/>
         /// </summary>
-        /// <param name="clientId"></param>
-        /// <returns></returns>
+        /// <param name="clientId">The unique identifier of the client to query.</param>
+        /// <returns>The MTU size in bytes for the specified client. If no MTU has been set for that client, returns <see cref="MaximumTransmissionUnitSize"/>.</returns>
         public int GetPeerMTU(ulong clientId)
         {
             if (MessageManager.PeerMTUSizes.TryGetValue(clientId, out var ret))
@@ -815,7 +818,6 @@ public int GetPeerMTU(ulong clientId)
         /// Sets the maximum size of a message (or message batch) passed through the transport with the ReliableFragmented delivery.
         /// Warning: setting this value too low may result in the SDK becoming non-functional with projects that have a large number of NetworkBehaviours or NetworkVariables, as the SDK relies on the transport's ability to fragment some messages when they grow beyond the MTU size.
         /// </summary>
-        /// <param name="size"></param>
         public int MaximumFragmentedMessageSize
         {
             set => MessageManager.FragmentedMessageMaxSize = value;