feat: Add ability to send instantiation data to a prefab handler (#3497)

<!-- Replace this block with what this PR does and why. Describe what
you'd like reviewers to know, how you applied the engineering
principles, and any interesting tradeoffs made. Delete bullet points
below that don't apply, and update the changelog section as appropriate.
-->

<!-- Add short version of the JIRA ticket to the PR title (e.g. "feat:
new shiny feature [MTT-123]") -->

Continues the work from  @Extrys in #3430.

## Changelog

- Added: A PrefabHandler that gives the ability to send data along with
object instantiation.
- Changed: Moved `INetworkPrefabInstanceHandler` to its own file.

## Testing and Documentation

- Includes unit tests.

<!-- Uncomment and mark items off with a * if this PR deprecates any
API:
### Deprecated API
- [ ] An `[Obsolete]` attribute was added along with a `(RemovedAfter
yyyy-mm-dd)` entry.
- [ ] An [api updater] was added.
- [ ] Deprecation of the API is explained in the CHANGELOG.
- [ ] The users can understand why this API was removed and what they
should use instead.
-->

## Backport

<!-- If this is a backport:
 - Add the following to the PR title: "\[Backport\] ..." .
 - Link to the original PR.
If this needs a backport - state this here
If a backport is not needed please provide the reason why.
If the "Backports" section is not present it will lead to a CI test
failure.
-->

This is a new feature so no backport is needed

---------

Co-authored-by: Extrys <[email protected]>
Co-authored-by: Noel Stephens <[email protected]>

Author: 3 people

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -39,6 +39,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/NetworkManager.cs

@@ -1593,8 +1593,9 @@ internal void ShutdownInternal()
             // Completely reset the NetworkClient
             ConnectionManager.LocalClient = new NetworkClient();
 
-            // This cleans up the internal prefabs list
+            // Clean up the internal prefabs data
             NetworkConfig?.Prefabs?.Shutdown();
+            PrefabHandler.Shutdown();
 
             // Reset the configuration hash for next session in the event
             // that the prefab list changes

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,24 @@ 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);
+
+                // Ensure that the buffer is completely reset
+                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);
+    }
+}