fix: Prevent UseUnreliableDeltas from being used with SwitchTransformSpaceWhenParented (#3875)

* fix

Prevent user from selecting use unreliable deltas when SwitchTransformSpaceWhenParented is enabled (and vice versa).
Adding check during runtime to also notify the user that this combination does not work (i.e. missed updates can result in a missed transform update when parenting changes).

* update

Updating XML API to reflect the changes.

* update

Updating documentation.

* update

Adding changelog entry.
Removing white space.

* update

Including the scenario where SwitchTransformSpaceWhenParented was set while UseUnreliableDeltas had already been set.

* style

Fixing warning message grammar.

* update

Including NetworkTransform and the name in the warning logged when trying to set one or the other while either one is set.

Author: NoelStephensUnity

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -18,6 +18,7 @@ Additional documentation and release notes are available at [Multiplayer Documen
 
 ### Fixed
 
+- Fixed `NetworkTransform` issue where a user could enable UseUnreliableDeltas while SwitchTransformSpaceWhenParented was also enabled (and vice versa). (#3875)
 - Fixed issue where `NetworkVariable` was not properly synchronizing to changes made by the spawn and write authority during `OnNetworkSpawn` and `OnNetworkPostSpawn`. (#3878)
 - Fixed issue where `NetworkManager` was not cleaning itself up if an exception was thrown while starting. (#3864)
 - Prevented a `NullReferenceException` in `UnityTransport` when using a custom `INetworkStreamDriverConstructor` that doesn't use all the default pipelines and the multiplayer tools package is installed. (#3853)

com.unity.netcode.gameobjects/Documentation~/components/helper/networktransform.md

@@ -75,6 +75,9 @@ The following NetworkTransform properties can cause a full state update when cha
 - __Use Quaternion Compression__
 - __Use Half Float Precision__
 
+> [!NOTE]
+> **UseUnreliableDeltas** cannot be enabled if **SwitchTransformSpaceWhenParented** is enabled since **SwitchTransformSpaceWhenParented** requires deltas to be sent reliably.
+
 ### Axis to Synchronize
 
 ![image](../../images/networktransform/AxisToSynchronize.png)
@@ -180,6 +183,7 @@ To resolve this issue, you can enable the __Switch Transform Space When Parented
 Things to consider when using __Switch Transform Space When Parented__:
 
 - This property is synchronized by the authority instance. If you disable it on the authority instance then it will synchronize this adjustment on all non-authority instances.
+- This property cannot be enabled when **UseUnreliableDeltas** is enabled as it requires deltas to be sent reliably.
 - When using __Switch Transform Space When Parented__, it's best to not make adjustments to the __NetworkTransform.InLocalSpace__ field and let the NetworkTransform handle this for you.
   - While you can still change __In Local Space__ directly via script while __Switch Transform Space When Parented__ is enabled, this could impact the end results. It is recommended to not adjust __In Local Space__ when __Switch Transform Space When Parented__ is enabled.
 

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

@@ -184,13 +184,45 @@ private void DisplayNetworkTransformProperties()
             EditorGUILayout.Space();
             EditorGUILayout.LabelField("Delivery", EditorStyles.boldLabel);
             EditorGUILayout.PropertyField(m_TickSyncChildren);
-            EditorGUILayout.PropertyField(m_UseUnreliableDeltas);
+            // If both are set from a previous configuration, then SwitchTransformSpaceWhenParented takes
+            // precedence.
+            if (networkTransform.UseUnreliableDeltas && networkTransform.SwitchTransformSpaceWhenParented)
+            {
+                networkTransform.UseUnreliableDeltas = false;
+            }
+            GUI.enabled = !networkTransform.SwitchTransformSpaceWhenParented;
+            if (networkTransform.SwitchTransformSpaceWhenParented)
+            {
+                EditorGUILayout.BeginHorizontal();
+                EditorGUILayout.PropertyField(m_UseUnreliableDeltas);
+                EditorGUILayout.LabelField($"Cannot use with {nameof(NetworkTransform.SwitchTransformSpaceWhenParented)}.");
+                EditorGUILayout.EndHorizontal();
+            }
+            else
+            {
+                EditorGUILayout.PropertyField(m_UseUnreliableDeltas);
+            }
+            GUI.enabled = true;
+
             EditorGUILayout.Space();
             EditorGUILayout.LabelField("Configurations", EditorStyles.boldLabel);
-            EditorGUILayout.PropertyField(m_SwitchTransformSpaceWhenParented);
+            GUI.enabled = !networkTransform.UseUnreliableDeltas;
+            if (networkTransform.UseUnreliableDeltas)
+            {
+                EditorGUILayout.BeginHorizontal();
+                EditorGUILayout.PropertyField(m_SwitchTransformSpaceWhenParented);
+                EditorGUILayout.LabelField($"Cannot use with {nameof(NetworkTransform.UseUnreliableDeltas)}.");
+                EditorGUILayout.EndHorizontal();
+            }
+            else
+            {
+                EditorGUILayout.PropertyField(m_SwitchTransformSpaceWhenParented);
+            }
+            GUI.enabled = true;
             if (m_SwitchTransformSpaceWhenParented.boolValue)
             {
                 m_TickSyncChildren.boolValue = true;
+                networkTransform.UseUnreliableDeltas = false;
             }
             else
             {

com.unity.netcode.gameobjects/Runtime/Components/NetworkTransform.cs

@@ -1370,6 +1370,7 @@ public enum AuthorityModes
         /// are sent using a reliable fragmented sequenced network delivery.
         /// </summary>
         /// <remarks>
+        /// Cannot be used when <see cref="SwitchTransformSpaceWhenParented"/> is enabled. <br />
         /// The following more critical state updates are still sent as reliable fragmented sequenced:<br />
         /// <list type="bullet">
         /// <item><description>The initial synchronization state update.</description></item>
@@ -1570,6 +1571,7 @@ internal bool SynchronizeScale
         /// When de-parented: Automatically transitions into world space and coverts any pending interpolation states to the relative local space on non-authority instances.<br />
         /// </summary>
         /// <remarks>
+        /// Cannot be used if <see cref="UseUnreliableDeltas"/> is enabled. <br />
         /// Only works with <see cref="NetworkTransform"/> components that are not paired with a <see cref="NetworkRigidbody"/> or <see cref="NetworkRigidbody2D"/> component that is configured to use the rigid body for motion.<br />
         /// <see cref="TickSyncChildren"/> will automatically be set when this is enabled.
         /// This field is auto-synchronized with non-authority clients when changed by the authority instance.
@@ -1958,6 +1960,28 @@ private void TryCommitTransform(bool synchronize = false, bool settingState = fa
                 m_UseRigidbodyForMotion = m_NetworkRigidbodyInternal.UseRigidBodyForMotion;
             }
 #endif
+            // Authority check to assure that UseUnreliableDeltas is not set during runtime while using SwitchTransformSpaceWhenParented.
+            if (SwitchTransformSpaceWhenParented && UseUnreliableDeltas)
+            {
+                // If we didn't have UseUnreliableDeltas previously set...
+                if (!m_LocalAuthoritativeNetworkState.FlagStates.UnreliableFrameSync)
+                {
+                    if (m_CachedNetworkManager.LogLevel <= LogLevel.Normal)
+                    {
+                        NetworkLog.LogWarning($"[{nameof(NetworkTransform)}][{name}] Reverting {nameof(UseUnreliableDeltas)} back to false as it cannot be enabled while {nameof(SwitchTransformSpaceWhenParented)} is enabled!");
+                    }
+                    UseUnreliableDeltas = false;
+                }
+                else // Otherwise SwitchTransformSpaceWhenParented has changed while UseUnreliableDeltas was already set.
+                {
+                    if (m_CachedNetworkManager.LogLevel <= LogLevel.Normal)
+                    {
+                        NetworkLog.LogWarning($"[{nameof(NetworkTransform)}][{name}] Reverting {nameof(SwitchTransformSpaceWhenParented)} back to false as it cannot be enabled while {nameof(UseUnreliableDeltas)} is enabled!");
+                    }
+                    SwitchTransformSpaceWhenParented = false;
+                }
+            }
+
             // If the transform has deltas (returns dirty) or if an explicitly set state is pending
             if (m_LocalAuthoritativeNetworkState.ExplicitSet || CheckForStateChange(ref m_LocalAuthoritativeNetworkState, synchronize, forceState: settingState))
             {