Review Changes

1) Moved the payload deserialization into the AddSceneObject, for deferred instantiation compatibility
2) Changed the new interface to be a direct single extended implementation, instead a complement of the handler
3) Some renames to better match what the feature does for developers

Author: Extrys

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

@@ -2981,8 +2981,8 @@ public void Serialize(FastBufferWriter writer)
 
                 if (HasInstantiationPayload)
                 {
-                    if (NetworkManager.Singleton.PrefabHandler.TryGetPayloadSynchronizer(Hash, out INetworkInstantiationPayloadSynchronizer synchronizer))
-                        synchronizer.OnSynchronize(ref bufferSerializer);
+                    if (NetworkManager.Singleton.PrefabHandler.TryGetPrefabInstanceHandlerWithData(Hash, out INetworkPrefabInstanceHandlerWithData synchronizer))
+                        synchronizer.OnSynchronizeInstantiationData(ref bufferSerializer);
                 }
 
                 OwnerObject.SynchronizeNetworkBehaviours(ref bufferSerializer, TargetClientId);
@@ -3041,15 +3041,6 @@ public void Deserialize(FastBufferReader reader)
                 // The NetworkSceneHandle is the server-side relative
                 // scene handle that the NetworkObject resides in.
                 reader.ReadValue(out NetworkSceneHandle);
-
-                if (HasInstantiationPayload)
-                {
-                    if (NetworkManager.Singleton.PrefabHandler.TryGetPayloadSynchronizer(Hash, out INetworkInstantiationPayloadSynchronizer synchronizer))
-                    {
-                        var instantiationPayloadBufferReader = new BufferSerializer<BufferSerializerReader>(new BufferSerializerReader(reader));
-                        synchronizer.OnSynchronize(ref instantiationPayloadBufferReader);
-                    }
-                }
             }
         }
 
@@ -3236,6 +3227,18 @@ internal SceneObject GetMessageSceneObject(ulong targetClientId = NetworkManager
         /// <returns>The deserialized NetworkObject or null if deserialization failed</returns>
         internal static NetworkObject AddSceneObject(in SceneObject sceneObject, FastBufferReader reader, NetworkManager networkManager, bool invokedByMessage = false)
         {
+            var bufferSerializer = new BufferSerializer<BufferSerializerReader>(new BufferSerializerReader(reader));
+
+            //Synchronize the instantiation payload if needed
+            if (sceneObject.HasInstantiationPayload)
+            {
+                if (NetworkManager.Singleton.PrefabHandler.TryGetPrefabInstanceHandlerWithData(sceneObject.Hash, out INetworkPrefabInstanceHandlerWithData handler))
+                {
+                    var instantiationPayloadBufferReader = new BufferSerializer<BufferSerializerReader>(new BufferSerializerReader(reader));
+                    handler.OnSynchronizeInstantiationData(ref instantiationPayloadBufferReader);
+                }
+            }
+
             //Attempt to create a local NetworkObject
             var networkObject = networkManager.SpawnManager.CreateLocalNetworkObject(sceneObject);
 
@@ -3270,7 +3273,6 @@ internal static NetworkObject AddSceneObject(in SceneObject sceneObject, FastBuf
             networkObject.InvokeBehaviourNetworkPreSpawn();
 
             // Synchronize NetworkBehaviours
-            var bufferSerializer = new BufferSerializer<BufferSerializerReader>(new BufferSerializerReader(reader));
             networkObject.SynchronizeNetworkBehaviours(ref bufferSerializer, networkManager.LocalClientId);
 
             // If we are an in-scene placed NetworkObject and we originally had a parent but when synchronized we are

com.unity.netcode.gameobjects/Runtime/Spawning/INetworkInstantiationPayloadSynchronizer.cs

@@ -0,0 +1,16 @@
+namespace Unity.Netcode
+{
+    /// <summary>
+    /// Specialized version of <see cref="INetworkPrefabInstanceHandler"/> that supports synchronizing
+    /// custom data prior to the instantiation of a <see cref="NetworkObject"/>.
+    /// </summary>
+    public interface INetworkPrefabInstanceHandlerWithData : INetworkPrefabInstanceHandler
+    {
+        /// <summary>
+        /// Allows synchronizing custom instantiation data before the object is instantiated. <br/>
+        /// Called before <see cref="INetworkPrefabInstanceHandler.Instantiate"/>.
+        /// </summary>
+        /// <param name="serializer">The serializer used to synchronize the custom instantiation data.</param>
+        void OnSynchronizeInstantiationData<T>(ref BufferSerializer<T> serializer) where T : IReaderWriter;
+    }
+}

com.unity.netcode.gameobjects/Runtime/Spawning/INetworkPrefabInstanceHandlerWithData.cs

@@ -22,7 +22,7 @@ public interface INetworkPrefabInstanceHandler
         /// via the  <see cref="GameObject.SetActive(bool)"/> method.
         /// 
         /// If you need to pass custom data at instantiation time (e.g., selecting a variant, setting initialization parameters, or choosing a pre-instantiated object),
-        /// implement <see cref="INetworkInstantiationPayloadSynchronizer"/> alongside this interface to receive the data before instantiation.
+        /// implement <see cref="INetworkPrefabInstanceHandlerWithData"/> alongside this interface to receive the data before instantiation.
         /// </summary>
         /// <param name="ownerClientId">the owner for the <see cref="NetworkObject"/> to be instantiated</param>
         /// <param name="position">the initial/default position for the <see cref="NetworkObject"/> to be instantiated</param>
@@ -227,29 +227,29 @@ public bool RemoveHandler(uint globalObjectIdHash)
         internal bool ContainsHandler(uint networkPrefabHash) => m_PrefabAssetToPrefabHandler.ContainsKey(networkPrefabHash) || m_PrefabInstanceToPrefabAsset.ContainsKey(networkPrefabHash);
 
         /// <summary>
-        /// Check to see if a <see cref="NetworkObject.GlobalObjectIdHash"/> is registered to an <see cref="INetworkInstantiationPayloadSynchronizer"/> implementation
+        /// Check to see if a <see cref="NetworkObject.GlobalObjectIdHash"/> is registered to an <see cref="INetworkPrefabInstanceHandlerWithData"/> implementation
         /// </summary>
         /// <param name="objectHash"></param>
         /// <returns></returns>
-        internal bool HasPayloadSynchronizer(uint objectHash) => TryGetPayloadSynchronizer(objectHash, out _);
+        internal bool HasPayloadSynchronizer(uint objectHash) => TryGetPrefabInstanceHandlerWithData(objectHash, out _);
 
         /// <summary>
-        /// Returns the <see cref="INetworkInstantiationPayloadSynchronizer"/> implementation for a given <see cref="NetworkObject.GlobalObjectIdHash"/>
+        /// Returns the <see cref="INetworkPrefabInstanceHandlerWithData"/> implementation for a given <see cref="NetworkObject.GlobalObjectIdHash"/>
         /// </summary>
         /// <param name="objectHash"></param>
-        /// <param name="synchronizer"></param>
+        /// <param name="handler"></param>
         /// <returns></returns>
-        internal bool TryGetPayloadSynchronizer(uint objectHash, out INetworkInstantiationPayloadSynchronizer synchronizer)
+        internal bool TryGetPrefabInstanceHandlerWithData(uint objectHash, out INetworkPrefabInstanceHandlerWithData handler)
         {
             if (m_PrefabAssetToPrefabHandler.TryGetValue(objectHash, out var prefabInstanceHandler))
             {
-                if (prefabInstanceHandler is INetworkInstantiationPayloadSynchronizer payloadSynchronizer)
+                if (prefabInstanceHandler is INetworkPrefabInstanceHandlerWithData payloadSynchronizer)
                 {
-                    synchronizer = payloadSynchronizer;
+                    handler = payloadSynchronizer;
                     return true;
                 }
             }
-            synchronizer = null;
+            handler = null;
             return false;
         }