feat: AttachableBehaviour and ComponentController

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -10,6 +10,10 @@ Additional documentation and release notes are available at [Multiplayer Documen
 
 ### Added
 
+- Added `AttachableBehaviour` helper component to provide an alternate approach to parenting items without using the `NetworkObject` parenting. (#3518)
+- Added `AttachableNode` helper component that is used by `AttachableBehaviour` as the target node for parenting. (#3518)
+- Added `ComponentController` helper component that can be used to synchronize the enabling and disabling of components and can be used in conjunction with `AttachableBehaviour`. (#3518)
+- Added `NetworkBehaviour.OnNetworkPreDespawn` that is invoked before running through the despawn sequence for the `NetworkObject` and all `NetworkBehaviour` children of the `NetworkObject` being despawned. (#3518)
 - Added methods `GetDefaultNetworkSettings` and `GetDefaultPipelineConfigurations` to `UnityTransport`. These can be used to retrieve the default settings and pipeline stages that are used by `UnityTransport`. This is useful when providing a custom driver constructor through `UnityTransport.s_DriverConstructor`, since it allows reusing or tuning the existing configuration instead of trying to recreate it. This means a transport with a custom driver can now easily benefit from most of the features of `UnityTransport`, like integration with the Network Simulator and Network Profiler from the multiplayer tools package. (#3501)
 - Added mappings between `ClientId` and `TransportId`. (#3516)
 - Added `NetworkPrefabInstanceHandlerWithData<T>`, a variant of `INetworkPrefabInstanceHandler` that provides access to custom instantiation data directly within the `Instantiate()` method. (#3430)

com.unity.netcode.gameobjects/Runtime/Components/Helpers/AttachableNode.cs

@@ -0,0 +1,97 @@
+using System.Collections.Generic;
+using Unity.Netcode;
+using Unity.Netcode.Components;
+
+
+/// <summary>
+/// This component is used in conjunction with <see cref="AttachableBehaviour"/> and is used to
+/// denote a specific child <see cref="UnityEngine.GameObject"/> that an <see cref="AttachableBehaviour"/>
+/// can attach itself to.
+/// </summary>
+/// <remarks>
+/// Primarily, the <see cref="AttachableNode"/> can be used as it is or can be extended to perform additional
+/// logical operations when something attaches to or detaches from the <see cref="AttachableNode"/> instance.
+/// </remarks>
+public class AttachableNode : NetworkBehaviour
+{
+    /// <summary>
+    /// Returns true if the <see cref="AttachableNode"/> instance has one or more attached <see cref="AttachableBehaviour"/> components.
+    /// </summary>
+    public bool HasAttachments => m_AttachedBehaviours.Count > 0;
+
+    /// <summary>
+    /// When enabled, any attached <see cref="AttachableBehaviour"/>s will be automatically detached and re-parented under its original parent.
+    /// </summary>
+    public bool DetachOnDespawn = true;
+
+    /// <summary>
+    /// A <see cref="List{T}"/> of the currently attached <see cref="AttachableBehaviour"/>s.
+    /// </summary>
+    protected readonly List<AttachableBehaviour> m_AttachedBehaviours = new List<AttachableBehaviour>();
+
+    /// <inheritdoc/>
+    /// <remarks>
+    /// If the <see cref="NetworkObject"/> this <see cref="AttachableNode"/> belongs to is despawned,
+    /// then any attached <see cref="AttachableBehaviour"/> will be detached during <see cref="OnNetworkDespawn"/>.
+    /// </remarks>
+    public override void OnNetworkPreDespawn()
+    {
+        if (IsSpawned && HasAuthority && DetachOnDespawn)
+        {
+            for (int i = m_AttachedBehaviours.Count - 1; i >= 0; i--)
+            {
+                m_AttachedBehaviours[i]?.Detach();
+            }
+        }
+        base.OnNetworkPreDespawn();
+    }
+
+    /// <inheritdoc/>
+    public override void OnNetworkDespawn()
+    {
+        m_AttachedBehaviours.Clear();
+        base.OnNetworkDespawn();
+    }
+
+    /// <summary>
+    /// Override this method to be notified when an <see cref="AttachableBehaviour"/> has attached to this node.
+    /// </summary>
+    /// <param name="attachableBehaviour">The <see cref="AttachableBehaviour"/> that has been attached.</param>
+    protected virtual void OnAttached(AttachableBehaviour attachableBehaviour)
+    {
+
+    }
+
+    internal void Attach(AttachableBehaviour attachableBehaviour)
+    {
+        if (m_AttachedBehaviours.Contains(attachableBehaviour))
+        {
+            NetworkLog.LogError($"[{nameof(AttachableNode)}][{name}][Attach] {nameof(AttachableBehaviour)} {attachableBehaviour.name} is already attached!");
+            return;
+        }
+
+        m_AttachedBehaviours.Add(attachableBehaviour);
+        OnAttached(attachableBehaviour);
+    }
+
+    /// <summary>
+    /// Override this method to be notified when an <see cref="AttachableBehaviour"/> has detached from this node.
+    /// </summary>
+    /// <param name="attachableBehaviour">The <see cref="AttachableBehaviour"/> that has been detached.</param>
+    protected virtual void OnDetached(AttachableBehaviour attachableBehaviour)
+    {
+
+    }
+
+    internal void Detach(AttachableBehaviour attachableBehaviour)
+    {
+        if (!m_AttachedBehaviours.Contains(attachableBehaviour))
+        {
+            NetworkLog.LogError($"[{nameof(AttachableNode)}][{name}][Detach] {nameof(AttachableBehaviour)} {attachableBehaviour.name} is not attached!");
+            return;
+        }
+
+        m_AttachedBehaviours.Remove(attachableBehaviour);
+        OnDetached(attachableBehaviour);
+    }
+}