feat: Added support for client anticipation in NetworkVariables and NetworkTransform and support for throttling functionality in NetworkVariables (#2820)

Author: ShadauxCat

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -9,6 +9,14 @@ Additional documentation and release notes are available at [Multiplayer Documen
 ## [Unreleased]
 
 ### Added
+-Added AnticipatedNetworkVariable<T>, which adds support for client anticipation of NetworkVariable values, allowing for more responsive gameplay (#2820)
+- Added AnticipatedNetworkTransform, which adds support for client anticipation of NetworkTransforms (#2820)
+- Added NetworkVariableBase.ExceedsDirtinessThreshold to allow network variables to throttle updates by only sending updates when the difference between the current and previous values exceeds a threshold. (This is exposed in NetworkVariable<T> with the callback NetworkVariable<T>.CheckExceedsDirtinessThreshold) (#2820)
+- Added NetworkVariableUpdateTraits, which add additional throttling support: MinSecondsBetweenUpdates will prevent the NetworkVariable from sending updates more often than the specified time period (even if it exceeds the dirtiness threshold), while MaxSecondsBetweenUpdates will force a dirty NetworkVariable to send an update after the specified time period even if it has not yet exceeded the dirtiness threshold. (#2820)
+- Added virtual method NetworkVariableBase.OnInitialize() which can be used by NetworkVariable subclasses to add initialization code (#2820)
+- Added virtual method NetworkVariableBase.Update(), which is called once per frame to support behaviors such as interpolation between an anticipated value and an authoritative one. (#2820)
+- Added NetworkTime.TickWithPartial, which represents the current tick as a double that includes the fractional/partial tick value. (#2820)
+- Added NetworkTickSystem.AnticipationTick, which can be helpful with implementation of client anticipation. This value represents the tick the current local client was at at the beginning of the most recent network round trip, which enables it to correlate server update ticks with the client tick that may have triggered them. (#2820)
 
 ### Fixed
 

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

@@ -2047,10 +2047,15 @@ private bool ApplyTransformToNetworkStateWithInfo(ref NetworkTransformState netw
             return isDirty;
         }
 
+        protected virtual void OnTransformUpdated()
+        {
+
+        }
+
         /// <summary>
         /// Applies the authoritative state to the transform
         /// </summary>
-        private void ApplyAuthoritativeState()
+        protected internal void ApplyAuthoritativeState()
         {
             var networkState = m_LocalAuthoritativeNetworkState;
             // The m_CurrentPosition, m_CurrentRotation, and m_CurrentScale values are continually updated
@@ -2221,6 +2226,7 @@ private void ApplyAuthoritativeState()
                 }
                 transform.localScale = m_CurrentScale;
             }
+            OnTransformUpdated();
         }
 
         /// <summary>
@@ -2418,6 +2424,7 @@ private void ApplyTeleportingState(NetworkTransformState newState)
             {
                 AddLogEntry(ref newState, NetworkObject.OwnerClientId);
             }
+            OnTransformUpdated();
         }
 
         /// <summary>
@@ -2586,6 +2593,11 @@ protected virtual void OnNetworkTransformStateUpdated(ref NetworkTransformState
 
         }
 
+        protected virtual void OnBeforeUpdateTransformState()
+        {
+
+        }
+
         private NetworkTransformState m_OldState = new NetworkTransformState();
 
         /// <summary>
@@ -2609,6 +2621,8 @@ private void OnNetworkStateChanged(NetworkTransformState oldState, NetworkTransf
             // Get the time when this new state was sent
             newState.SentTime = new NetworkTime(m_CachedNetworkManager.NetworkConfig.TickRate, newState.NetworkTick).Time;
 
+            OnBeforeUpdateTransformState();
+
             // Apply the new state
             ApplyUpdatedState(newState);
 
@@ -3315,7 +3329,7 @@ private static void RegisterForTickUpdate(NetworkTransform networkTransform)
 
         /// <summary>
         /// If a NetworkTransformTickRegistration exists for the NetworkManager instance, then this will
-        /// remove the NetworkTransform instance from the single tick update entry point. 
+        /// remove the NetworkTransform instance from the single tick update entry point.
         /// </summary>
         /// <param name="networkTransform"></param>
         private static void DeregisterForTickUpdate(NetworkTransform networkTransform)

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

@@ -0,0 +1,14 @@
+using Unity.Netcode.Components;
+using UnityEditor;
+
+namespace Unity.Netcode.Editor
+{
+    /// <summary>
+    /// The <see cref="CustomEditor"/> for <see cref="AnticipatedNetworkTransform"/>
+    /// </summary>
+    [CustomEditor(typeof(AnticipatedNetworkTransform), true)]
+    public class AnticipatedNetworkTransformEditor : NetworkTransformEditor
+    {
+        public override bool HideInterpolateValue => true;
+    }
+}

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

@@ -408,6 +408,7 @@ private void CreateNetworkVariableTypeInitializers(AssemblyDefinition assembly,
                     }
                     else
                     {
+                        m_Diagnostics.AddError($"{type}: Managed type in NetworkVariable must implement IEquatable<{type}>");
                         equalityMethod = new GenericInstanceMethod(m_NetworkVariableSerializationTypes_InitializeEqualityChecker_ManagedClassEquals_MethodRef);
                     }
 

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

@@ -37,6 +37,8 @@ public class NetworkTransformEditor : UnityEditor.Editor
         private static GUIContent s_RotationLabel = EditorGUIUtility.TrTextContent("Rotation");
         private static GUIContent s_ScaleLabel = EditorGUIUtility.TrTextContent("Scale");
 
+        public virtual bool HideInterpolateValue => false;
+
         /// <inheritdoc/>
         public void OnEnable()
         {
@@ -137,7 +139,11 @@ public override void OnInspectorGUI()
             EditorGUILayout.Space();
             EditorGUILayout.LabelField("Configurations", EditorStyles.boldLabel);
             EditorGUILayout.PropertyField(m_InLocalSpaceProperty);
-            EditorGUILayout.PropertyField(m_InterpolateProperty);
+            if (!HideInterpolateValue)
+            {
+                EditorGUILayout.PropertyField(m_InterpolateProperty);
+            }
+
             EditorGUILayout.PropertyField(m_SlerpPosition);
             EditorGUILayout.PropertyField(m_UseQuaternionSynchronization);
             if (m_UseQuaternionSynchronization.boolValue)

com.unity.netcode.gameobjects/Editor/AnticipatedNetworkTransformEditor.cs.meta

@@ -510,6 +510,15 @@ internal void DisconnectEventHandler(ulong transportClientId)
                 // as the client ID is no longer valid.
                 NetworkManager.Shutdown(true);
             }
+
+            if (NetworkManager.IsServer)
+            {
+                MessageManager.ClientDisconnected(clientId);
+            }
+            else
+            {
+                MessageManager.ClientDisconnected(NetworkManager.ServerClientId);
+            }
 #if DEVELOPMENT_BUILD || UNITY_EDITOR
             s_TransportDisconnect.End();
 #endif

com.unity.netcode.gameobjects/Editor/CodeGen/NetworkBehaviourILPP.cs

@@ -815,19 +815,35 @@ internal void PostNetworkVariableWrite(bool forced = false)
                 // during OnNetworkSpawn has been sent and needs to be cleared
                 for (int i = 0; i < NetworkVariableFields.Count; i++)
                 {
-                    NetworkVariableFields[i].ResetDirty();
+                    var networkVariable = NetworkVariableFields[i];
+                    if (networkVariable.IsDirty())
+                    {
+                        if (networkVariable.CanSend())
+                        {
+                            networkVariable.UpdateLastSentTime();
+                            networkVariable.ResetDirty();
+                            networkVariable.SetDirty(false);
+                        }
+                    }
                 }
             }
             else
             {
                 // mark any variables we wrote as no longer dirty
                 for (int i = 0; i < NetworkVariableIndexesToReset.Count; i++)
                 {
-                    NetworkVariableFields[NetworkVariableIndexesToReset[i]].ResetDirty();
+                    var networkVariable = NetworkVariableFields[NetworkVariableIndexesToReset[i]];
+                    if (networkVariable.IsDirty())
+                    {
+                        if (networkVariable.CanSend())
+                        {
+                            networkVariable.UpdateLastSentTime();
+                            networkVariable.ResetDirty();
+                            networkVariable.SetDirty(false);
+                        }
+                    }
                 }
             }
-
-            MarkVariablesDirty(false);
         }
 
         internal void PreVariableUpdate()
@@ -836,7 +852,6 @@ internal void PreVariableUpdate()
             {
                 InitializeVariables();
             }
-
             PreNetworkVariableWrite();
         }
 
@@ -863,7 +878,10 @@ private void NetworkVariableUpdate(ulong targetClientId, int behaviourIndex)
                     var networkVariable = NetworkVariableFields[k];
                     if (networkVariable.IsDirty() && networkVariable.CanClientRead(targetClientId))
                     {
-                        shouldSend = true;
+                        if (networkVariable.CanSend())
+                        {
+                            shouldSend = true;
+                        }
                         break;
                     }
                 }
@@ -904,9 +922,16 @@ private bool CouldHaveDirtyNetworkVariables()
             // TODO: There should be a better way by reading one dirty variable vs. 'n'
             for (int i = 0; i < NetworkVariableFields.Count; i++)
             {
-                if (NetworkVariableFields[i].IsDirty())
+                var networkVariable = NetworkVariableFields[i];
+                if (networkVariable.IsDirty())
                 {
-                    return true;
+                    if (networkVariable.CanSend())
+                    {
+                        return true;
+                    }
+                    // If it's dirty but can't be sent yet, we have to keep monitoring it until one of the
+                    // conditions blocking its send changes.
+                    NetworkManager.BehaviourUpdater.AddForUpdate(NetworkObject);
                 }
             }
 
@@ -1063,6 +1088,11 @@ protected virtual void OnSynchronize<T>(ref BufferSerializer<T> serializer) wher
 
         }
 
+        public virtual void OnReanticipate(double lastRoundTripTime)
+        {
+
+        }
+
         /// <summary>
         /// The relative client identifier targeted for the serialization of this <see cref="NetworkBehaviour"/> instance.
         /// </summary>

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

@@ -11,14 +11,15 @@ public class NetworkBehaviourUpdater
         private NetworkManager m_NetworkManager;
         private NetworkConnectionManager m_ConnectionManager;
         private HashSet<NetworkObject> m_DirtyNetworkObjects = new HashSet<NetworkObject>();
+        private HashSet<NetworkObject> m_PendingDirtyNetworkObjects = new HashSet<NetworkObject>();
 
 #if DEVELOPMENT_BUILD || UNITY_EDITOR
         private ProfilerMarker m_NetworkBehaviourUpdate = new ProfilerMarker($"{nameof(NetworkBehaviour)}.{nameof(NetworkBehaviourUpdate)}");
 #endif
 
         internal void AddForUpdate(NetworkObject networkObject)
         {
-            m_DirtyNetworkObjects.Add(networkObject);
+            m_PendingDirtyNetworkObjects.Add(networkObject);
         }
 
         internal void NetworkBehaviourUpdate()
@@ -28,6 +29,9 @@ internal void NetworkBehaviourUpdate()
 #endif
             try
             {
+                m_DirtyNetworkObjects.UnionWith(m_PendingDirtyNetworkObjects);
+                m_PendingDirtyNetworkObjects.Clear();
+
                 // NetworkObject references can become null, when hidden or despawned. Once NUll, there is no point
                 // trying to process them, even if they were previously marked as dirty.
                 m_DirtyNetworkObjects.RemoveWhere((sobj) => sobj == null);

com.unity.netcode.gameobjects/Runtime/Connection/NetworkConnectionManager.cs

@@ -45,15 +45,25 @@ public void NetworkUpdate(NetworkUpdateStage updateStage)
 
                         DeferredMessageManager.ProcessTriggers(IDeferredNetworkMessageManager.TriggerType.OnNextFrame, 0);
 
+                        AnticipationSystem.SetupForUpdate();
                         MessageManager.ProcessIncomingMessageQueue();
                         MessageManager.CleanupDisconnectedClients();
+
+                        AnticipationSystem.ProcessReanticipation();
                     }
                     break;
                 case NetworkUpdateStage.PreUpdate:
                     {
                         NetworkTimeSystem.UpdateTime();
+                        AnticipationSystem.Update();
                     }
                     break;
+                case NetworkUpdateStage.PostScriptLateUpdate:
+
+                    AnticipationSystem.Sync();
+                    AnticipationSystem.SetupForRender();
+                    break;
+
                 case NetworkUpdateStage.PostLateUpdate:
                     {
                         // This should be invoked just prior to the MessageManager processes its outbound queue.
@@ -274,6 +284,25 @@ public event Action OnTransportFailure
             remove => ConnectionManager.OnTransportFailure -= value;
         }
 
+        public delegate void ReanticipateDelegate(double lastRoundTripTime);
+
+        /// <summary>
+        /// This callback is called after all individual OnReanticipate calls on AnticipatedNetworkVariable
+        /// and AnticipatedNetworkTransform values have been invoked. The first parameter is a hash set of
+        /// all the variables that have been changed on this frame (you can detect a particular variable by
+        /// checking if the set contains it), while the second parameter is a set of all anticipated network
+        /// transforms that have been changed. Both are passed as their base class type.
+        ///
+        /// The third parameter is the local time corresponding to the current authoritative server state
+        /// (i.e., to determine the amount of time that needs to be re-simulated, you will use
+        /// NetworkManager.LocalTime.Time - authorityTime).
+        /// </summary>
+        public event ReanticipateDelegate OnReanticipate
+        {
+            add => AnticipationSystem.OnReanticipate += value;
+            remove => AnticipationSystem.OnReanticipate -= value;
+        }
+
         /// <summary>
         /// The callback to invoke during connection approval. Allows client code to decide whether or not to allow incoming client connection
         /// </summary>
@@ -518,6 +547,8 @@ public NetworkPrefabHandler PrefabHandler
         /// </summary>
         public NetworkTickSystem NetworkTickSystem { get; private set; }
 
+        internal AnticipationSystem AnticipationSystem { get; private set; }
+
         /// <summary>
         /// Used for time mocking in tests
         /// </summary>
@@ -813,6 +844,7 @@ internal void Initialize(bool server)
 
             this.RegisterNetworkUpdate(NetworkUpdateStage.EarlyUpdate);
             this.RegisterNetworkUpdate(NetworkUpdateStage.PreUpdate);
+            this.RegisterNetworkUpdate(NetworkUpdateStage.PostScriptLateUpdate);
             this.RegisterNetworkUpdate(NetworkUpdateStage.PostLateUpdate);
 
             // ComponentFactory needs to set its defaults next
@@ -845,6 +877,7 @@ internal void Initialize(bool server)
             // The remaining systems can then be initialized
             NetworkTimeSystem = server ? NetworkTimeSystem.ServerTimeSystem() : new NetworkTimeSystem(1.0 / NetworkConfig.TickRate);
             NetworkTickSystem = NetworkTimeSystem.Initialize(this);
+            AnticipationSystem = new AnticipationSystem(this);
 
             // Create spawn manager instance
             SpawnManager = new NetworkSpawnManager(this);

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

@@ -54,7 +54,14 @@ public enum NetworkUpdateStage : byte
         /// </summary>
         PreLateUpdate = 6,
         /// <summary>
+        /// Updated after Monobehaviour.LateUpdate, but BEFORE rendering
+        /// </summary>
+        // Yes, these numbers are out of order due to backward compatibility requirements.
+        // The enum values are listed in the order they will be called.
+        PostScriptLateUpdate = 8,
+        /// <summary>
         /// Updated after the Monobehaviour.LateUpdate for all components is invoked
+        /// and all rendering is complete
         /// </summary>
         PostLateUpdate = 7
     }
@@ -258,6 +265,18 @@ public static PlayerLoopSystem CreateLoopSystem()
             }
         }
 
+        internal struct NetworkPostScriptLateUpdate
+        {
+            public static PlayerLoopSystem CreateLoopSystem()
+            {
+                return new PlayerLoopSystem
+                {
+                    type = typeof(NetworkPostScriptLateUpdate),
+                    updateDelegate = () => RunNetworkUpdateStage(NetworkUpdateStage.PostScriptLateUpdate)
+                };
+            }
+        }
+
         internal struct NetworkPostLateUpdate
         {
             public static PlayerLoopSystem CreateLoopSystem()
@@ -399,6 +418,7 @@ internal static void RegisterLoopSystems()
                 else if (currentSystem.type == typeof(PreLateUpdate))
                 {
                     TryAddLoopSystem(ref currentSystem, NetworkPreLateUpdate.CreateLoopSystem(), typeof(PreLateUpdate.ScriptRunBehaviourLateUpdate), LoopSystemPosition.Before);
+                    TryAddLoopSystem(ref currentSystem, NetworkPostScriptLateUpdate.CreateLoopSystem(), typeof(PreLateUpdate.ScriptRunBehaviourLateUpdate), LoopSystemPosition.After);
                 }
                 else if (currentSystem.type == typeof(PostLateUpdate))
                 {
@@ -440,6 +460,7 @@ internal static void UnregisterLoopSystems()
                 else if (currentSystem.type == typeof(PreLateUpdate))
                 {
                     TryRemoveLoopSystem(ref currentSystem, typeof(NetworkPreLateUpdate));
+                    TryRemoveLoopSystem(ref currentSystem, typeof(NetworkPostScriptLateUpdate));
                 }
                 else if (currentSystem.type == typeof(PostLateUpdate))
                 {