feat: Add ability to send instantiation data to a prefab handler

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -25,6 +25,7 @@ Additional documentation and release notes are available at [Multiplayer Documen
 
 - Added `SinglePlayerTransport` that provides the ability to start as a host for a single player network session. (#3473)
 - When using UnityTransport >=2.4 and Unity >= 6000.1.0a1, SetConnectionData will accept a fully qualified hostname instead of an IP as a connect address on the client side. (#3441)
+- Added `NetworkPrefabInstanceHandlerWithData<T>`, a variant of `INetworkPrefabInstanceHandler` that provides access to custom instantiation data directly within the `Instantiate()` method. (#3430)
 
 ### Fixed
 

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

@@ -58,6 +58,12 @@ public uint PrefabIdHash
             }
         }
 
+        /// <summary>
+        /// InstantiationData sent during the instantiation process.
+        /// Available to read as T parameter to  <see cref="NetworkPrefabInstanceHandlerWithData{T}.Instantiate(ulong, Vector3, Quaternion, T)"/> for custom handling by user code.
+        /// </summary>
+        internal byte[] InstantiationData;
+
         /// <summary>
         /// All <see cref="NetworkTransform"/> component instances associated with a <see cref="NetworkObject"/> component instance.
         /// </summary>
@@ -2857,6 +2863,12 @@ public bool SpawnWithObservers
                 set => ByteUtility.SetBit(ref m_BitField, 10, value);
             }
 
+            public bool HasInstantiationData
+            {
+                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;
@@ -2884,6 +2896,7 @@ public struct TransformData : INetworkSerializeByMemcpy
 
             public int NetworkSceneHandle;
 
+            internal int SynchronizationDataSize;
 
             public void Serialize(FastBufferWriter writer)
             {
@@ -2945,9 +2958,29 @@ public void Serialize(FastBufferWriter writer)
                     writer.WriteValue(OwnerObject.GetSceneOriginHandle());
                 }
 
+                // write placeholder for serialized data size.
+                // Can't be bitpacked because we don't know the value until we calculate it later
+                var positionBeforeSynchronizing = writer.Position;
+                writer.WriteValueSafe(0);
+                var sizeToSkipCalculationPosition = writer.Position;
+
+                if (HasInstantiationData)
+                {
+                    writer.WriteValueSafe(OwnerObject.InstantiationData);
+                }
+
                 // Synchronize NetworkVariables and NetworkBehaviours
                 var bufferSerializer = new BufferSerializer<BufferSerializerWriter>(new BufferSerializerWriter(writer));
                 OwnerObject.SynchronizeNetworkBehaviours(ref bufferSerializer, TargetClientId);
+
+                var currentPosition = writer.Position;
+                // Write the total number of bytes written for synchronization data.
+                writer.Seek(positionBeforeSynchronizing);
+                // We want the size of everything after our size to skip calculation position
+                var size = currentPosition - sizeToSkipCalculationPosition;
+                writer.WriteValueSafe(size);
+                // seek back to the head of the writer.
+                writer.Seek(currentPosition);
             }
 
             public void Deserialize(FastBufferReader reader)
@@ -3003,6 +3036,10 @@ public void Deserialize(FastBufferReader reader)
                 // The NetworkSceneHandle is the server-side relative
                 // scene handle that the NetworkObject resides in.
                 reader.ReadValue(out NetworkSceneHandle);
+
+                // Read the size of the remaining synchronization data
+                // This data will be read in AddSceneObject()
+                reader.ReadValueSafe(out SynchronizationDataSize);
             }
         }
 
@@ -3017,12 +3054,7 @@ internal void SynchronizeNetworkBehaviours<T>(ref BufferSerializer<T> serializer
         {
             if (serializer.IsWriter)
             {
-                // write placeholder int.
-                // Can't be bitpacked because we don't know the value until we calculate it later
                 var writer = serializer.GetFastBufferWriter();
-                var positionBeforeSynchronizing = writer.Position;
-                writer.WriteValueSafe(0);
-                var sizeToSkipCalculationPosition = writer.Position;
 
                 // Synchronize NetworkVariables
                 foreach (var behavior in ChildNetworkBehaviours)
@@ -3048,12 +3080,6 @@ internal void SynchronizeNetworkBehaviours<T>(ref BufferSerializer<T> serializer
                 }
 
                 var currentPosition = writer.Position;
-                // Write the total number of bytes written for NetworkVariable and NetworkBehaviour
-                // synchronization.
-                writer.Seek(positionBeforeSynchronizing);
-                // We want the size of everything after our size to skip calculation position
-                var size = currentPosition - sizeToSkipCalculationPosition;
-                writer.WriteValueSafe(size);
                 // Write the number of NetworkBehaviours synchronized
                 writer.Seek(networkBehaviourCountPosition);
                 writer.WriteValueSafe(synchronizationCount);
@@ -3063,41 +3089,26 @@ internal void SynchronizeNetworkBehaviours<T>(ref BufferSerializer<T> serializer
             }
             else
             {
-                var seekToEndOfSynchData = 0;
                 var reader = serializer.GetFastBufferReader();
-                try
-                {
-                    reader.ReadValueSafe(out int sizeOfSynchronizationData);
-                    seekToEndOfSynchData = reader.Position + sizeOfSynchronizationData;
-
-                    // Apply the network variable synchronization data
-                    foreach (var behaviour in ChildNetworkBehaviours)
-                    {
-                        behaviour.InitializeVariables();
-                        behaviour.SetNetworkVariableData(reader, targetClientId);
-                    }
 
-                    // Read the number of NetworkBehaviours to synchronize
-                    reader.ReadValueSafe(out byte numberSynchronized);
+                // Apply the network variable synchronization data
+                foreach (var behaviour in ChildNetworkBehaviours)
+                {
+                    behaviour.InitializeVariables();
+                    behaviour.SetNetworkVariableData(reader, targetClientId);
+                }
 
-                    // If a NetworkBehaviour writes synchronization data, it will first
-                    // write its NetworkBehaviourId so when deserializing the client-side
-                    // can find the right NetworkBehaviour to deserialize the synchronization data.
-                    for (int i = 0; i < numberSynchronized; i++)
-                    {
-                        reader.ReadValueSafe(out ushort networkBehaviourId);
-                        var networkBehaviour = GetNetworkBehaviourAtOrderIndex(networkBehaviourId);
-                        networkBehaviour.Synchronize(ref serializer, targetClientId);
-                    }
+                // Read the number of NetworkBehaviours to synchronize
+                reader.ReadValueSafe(out byte numberSynchronized);
 
-                    if (seekToEndOfSynchData != reader.Position)
-                    {
-                        Debug.LogWarning($"[Size mismatch] Expected: {seekToEndOfSynchData} Currently At: {reader.Position}!");
-                    }
-                }
-                catch
+                // If a NetworkBehaviour writes synchronization data, it will first
+                // write its NetworkBehaviourId so when deserializing the client-side
+                // can find the right NetworkBehaviour to deserialize the synchronization data.
+                for (int i = 0; i < numberSynchronized; i++)
                 {
-                    reader.Seek(seekToEndOfSynchData);
+                    reader.ReadValueSafe(out ushort networkBehaviourId);
+                    var networkBehaviour = GetNetworkBehaviourAtOrderIndex(networkBehaviourId);
+                    networkBehaviour.Synchronize(ref serializer, targetClientId);
                 }
             }
         }
@@ -3121,7 +3132,8 @@ internal SceneObject GetMessageSceneObject(ulong targetClientId = NetworkManager
                 NetworkSceneHandle = NetworkSceneHandle,
                 Hash = CheckForGlobalObjectIdHashOverride(),
                 OwnerObject = this,
-                TargetClientId = targetClientId
+                TargetClientId = targetClientId,
+                HasInstantiationData = InstantiationData != null && InstantiationData.Length > 0
             };
 
             // Handle Parenting
@@ -3186,8 +3198,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)
         {
-            //Attempt to create a local NetworkObject
-            var networkObject = networkManager.SpawnManager.CreateLocalNetworkObject(sceneObject);
+            var endOfSynchronizationData = reader.Position + sceneObject.SynchronizationDataSize;
+
+            byte[] instantiationData = null;
+            if (sceneObject.HasInstantiationData)
+            {
+                reader.ReadValueSafe(out instantiationData);
+            }
+
+
+            // Attempt to create a local NetworkObject
+            var networkObject = networkManager.SpawnManager.CreateLocalNetworkObject(sceneObject, instantiationData);
+
 
             if (networkObject == null)
             {
@@ -3200,8 +3222,7 @@ internal static NetworkObject AddSceneObject(in SceneObject sceneObject, FastBuf
                 try
                 {
                     // If we failed to load this NetworkObject, then skip past the Network Variable and (if any) synchronization data
-                    reader.ReadValueSafe(out int networkBehaviourSynchronizationDataLength);
-                    reader.Seek(reader.Position + networkBehaviourSynchronizationDataLength);
+                    reader.Seek(endOfSynchronizationData);
                 }
                 catch (Exception ex)
                 {
@@ -3219,9 +3240,23 @@ internal static NetworkObject AddSceneObject(in SceneObject sceneObject, FastBuf
             // Special Case: Invoke NetworkBehaviour.OnPreSpawn methods here before SynchronizeNetworkBehaviours
             networkObject.InvokeBehaviourNetworkPreSpawn();
 
-            // Synchronize NetworkBehaviours
-            var bufferSerializer = new BufferSerializer<BufferSerializerReader>(new BufferSerializerReader(reader));
-            networkObject.SynchronizeNetworkBehaviours(ref bufferSerializer, networkManager.LocalClientId);
+            // Process the remaining synchronization data from the buffer
+            try
+            {
+                // Synchronize NetworkBehaviours
+                var bufferSerializer = new BufferSerializer<BufferSerializerReader>(new BufferSerializerReader(reader));
+                networkObject.SynchronizeNetworkBehaviours(ref bufferSerializer, networkManager.LocalClientId);
+
+                if (reader.Position != endOfSynchronizationData)
+                {
+                    Debug.LogWarning($"[Size mismatch] Expected: {endOfSynchronizationData} Currently At: {reader.Position}!");
+                    reader.Seek(endOfSynchronizationData);
+                }
+            }
+            catch
+            {
+                reader.Seek(endOfSynchronizationData);
+            }
 
             // If we are an in-scene placed NetworkObject and we originally had a parent but when synchronized we are
             // being told we do not have a parent, then we want to clear the latest parent so it is not automatically

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

@@ -0,0 +1,49 @@
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace Unity.Netcode
+{
+    /// <summary>
+    /// Interface for customizing, overriding, spawning, and destroying Network Prefabs
+    /// Used by <see cref="NetworkPrefabHandler"/>
+    /// </summary>
+    public interface INetworkPrefabInstanceHandler
+    {
+        /// <summary>
+        /// Client Side Only
+        /// Once an implementation is registered with the <see cref="NetworkPrefabHandler"/>, this method will be called every time
+        /// a Network Prefab associated <see cref="NetworkObject"/> is spawned on clients
+        ///
+        /// Note On Hosts: Use the <see cref="NetworkPrefabHandler.RegisterHostGlobalObjectIdHashValues(GameObject, List{T})"/>
+        /// method to register all targeted NetworkPrefab overrides manually since the host will be acting as both a server and client.
+        ///
+        /// 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.
+        /// </summary>
+        /// <remarks>
+        /// 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="NetworkPrefabInstanceHandlerWithData{T}"/> instead.
+        /// </remarks>
+        /// <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>
+        /// <param name="rotation">the initial/default rotation for the <see cref="NetworkObject"/> to be instantiated</param>
+        /// <returns>The instantiated NetworkObject instance. Returns null if instantiation fails.</returns>
+        public NetworkObject Instantiate(ulong ownerClientId, Vector3 position, Quaternion rotation);
+
+        /// <summary>
+        /// Invoked on Client and Server
+        /// Once an implementation is registered with the <see cref="NetworkPrefabHandler"/>, this method will be called when
+        /// a Network Prefab associated <see cref="NetworkObject"/> is:
+        ///
+        /// Server Side: destroyed or despawned with the destroy parameter equal to true
+        /// If <see cref="NetworkObject.Despawn(bool)"/> is invoked with the default destroy parameter (i.e. false) then this method will NOT be invoked!
+        ///
+        /// Client Side: destroyed when the client receives a destroy object message from the server or host.
+        ///
+        /// Note on Pooling: When this method is invoked, you do not need to destroy the NetworkObject as long as you want your pool to persist.
+        /// The most common approach is to make the <see cref="NetworkObject"/> inactive by calling <see cref="GameObject.SetActive(bool)"/>.
+        /// </summary>
+        /// <param name="networkObject">The <see cref="NetworkObject"/> being destroyed</param>
+        public void Destroy(NetworkObject networkObject);
+    }
+}