feat: Instantiation payload support for INetworkPrefabInstanceHandler

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

@@ -2882,6 +2882,12 @@ public bool SpawnWithObservers
                 set => ByteUtility.SetBit(ref m_BitField, 10, value);
             }
 
+            public bool HasInstantiationPayload
+            {
+                get => ByteUtility.GetBit(m_BitField, 11);
+                set => ByteUtility.SetBit(ref m_BitField, 11, value);
+            }
+
             // When handling the initial synchronization of NetworkObjects,
             // this will be populated with the known observers.
             public ulong[] Observers;
@@ -2970,8 +2976,15 @@ public void Serialize(FastBufferWriter writer)
                     writer.WriteValue(OwnerObject.GetSceneOriginHandle());
                 }
 
-                // Synchronize NetworkVariables and NetworkBehaviours
+                // Synchronize Payload, NetworkVariables and NetworkBehaviours
                 var bufferSerializer = new BufferSerializer<BufferSerializerWriter>(new BufferSerializerWriter(writer));
+
+                if (HasInstantiationPayload)
+                {
+                    if (NetworkManager.Singleton.PrefabHandler.TryGetPayloadSynchronizer(Hash, out INetworkInstantiationPayloadSynchronizer synchronizer))
+                        synchronizer.OnSynchronize(ref bufferSerializer);
+                }
+
                 OwnerObject.SynchronizeNetworkBehaviours(ref bufferSerializer, TargetClientId);
             }
 
@@ -3028,6 +3041,15 @@ 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);
+                    }
+                }
             }
         }
 
@@ -3148,7 +3170,8 @@ internal SceneObject GetMessageSceneObject(ulong targetClientId = NetworkManager
                 NetworkSceneHandle = NetworkSceneHandle,
                 Hash = CheckForGlobalObjectIdHashOverride(),
                 OwnerObject = this,
-                TargetClientId = targetClientId
+                TargetClientId = targetClientId,
+                HasInstantiationPayload = NetworkManager.PrefabHandler.HasPayloadSynchronizer(GlobalObjectIdHash),
             };
 
             // Handle Parenting

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

@@ -0,0 +1,22 @@
+namespace Unity.Netcode
+{
+    /// <summary>
+    /// Interface for synchronizing custom instantiation payloads during NetworkObject spawning.
+    /// Used alongside <see cref="INetworkPrefabInstanceHandler"/> to extend instantiation behavior.
+    /// </summary>
+    public interface INetworkInstantiationPayloadSynchronizer
+    {
+        /// <summary>
+        /// Provides a method for synchronizing instantiation payload data during the spawn process.
+        /// Extends <see cref="INetworkPrefabInstanceHandler"/> to allow passing additional data prior to instantiation
+        /// to help identify or configure the local object instance that should be linked to the spawned NetworkObject.
+        ///
+        /// This method is invoked immediately before <see cref="INetworkPrefabInstanceHandler.Instantiate"/> is called,
+        /// allowing you to cache or prepare information needed during instantiation.
+        /// </summary>
+        /// <param name="serializer">The buffer serializer used to read or write custom instantiation data.</param>
+        void OnSynchronize<T>(ref BufferSerializer<T> serializer) where T : IReaderWriter;
+        //void Serialize(FastBufferWriter writer);
+        //void Deserialize(FastBufferReader reader);
+    }
+}

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

@@ -20,6 +20,9 @@ public interface INetworkPrefabInstanceHandler
         ///
         /// Note on Pooling:  If you are using a NetworkObject pool, don't forget to make the NetworkObject active
         /// 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.
         /// </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>
@@ -223,6 +226,33 @@ public bool RemoveHandler(uint globalObjectIdHash)
         /// <returns>true or false</returns>
         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
+        /// </summary>
+        /// <param name="objectHash"></param>
+        /// <returns></returns>
+        internal bool HasPayloadSynchronizer(uint objectHash) => TryGetPayloadSynchronizer(objectHash, out _);
+
+        /// <summary>
+        /// Returns the <see cref="INetworkInstantiationPayloadSynchronizer"/> implementation for a given <see cref="NetworkObject.GlobalObjectIdHash"/>
+        /// </summary>
+        /// <param name="objectHash"></param>
+        /// <param name="synchronizer"></param>
+        /// <returns></returns>
+        internal bool TryGetPayloadSynchronizer(uint objectHash, out INetworkInstantiationPayloadSynchronizer synchronizer)
+        {
+            if (m_PrefabAssetToPrefabHandler.TryGetValue(objectHash, out var prefabInstanceHandler))
+            {
+                if (prefabInstanceHandler is INetworkInstantiationPayloadSynchronizer payloadSynchronizer)
+                {
+                    synchronizer = payloadSynchronizer;
+                    return true;
+                }
+            }
+            synchronizer = null;
+            return false;
+        }
+
         /// <summary>
         /// Returns the source NetworkPrefab's <see cref="NetworkObject.GlobalObjectIdHash"/>
         /// </summary>