com.wallstop-studios.unity-helpers 2.0.0-rc81.9 → 2.0.1

package/Runtime/Integrations/VContainer/RelationalComponentEntryPoint.cs

@@ -9,6 +9,7 @@ namespace WallstopStudios.UnityHelpers.Integrations.VContainer
     using WallstopStudios.UnityHelpers.Core.Attributes;
     using WallstopStudios.UnityHelpers.Tags;
     using WallstopStudios.UnityHelpers.Utils;
+    using Object = UnityEngine.Object;
 
     /// <summary>
     /// Entry point registered with VContainer to hydrate relational attributes once the container is
@@ -71,38 +72,117 @@ namespace WallstopStudios.UnityHelpers.Integrations.VContainer
 
             if (relationalTypes.Count == 0)
             {
+                // Fallback: scan all components once and assign when type has relational fields
+                bool includeInactiveAll = _options.IncludeInactive;
+                Component[] allComponents = includeInactiveAll
+                    ? Object.FindObjectsOfType<Component>(true)
+                    : Object.FindObjectsOfType<Component>(false);
+
+                for (int i = 0; i < allComponents.Length; i++)
+                {
+                    Component c = allComponents[i];
+                    if (c == null || c.gameObject.scene != SceneManager.GetActiveScene())
+                    {
+                        continue;
+                    }
+
+                    if (_assigner.HasRelationalAssignments(c.GetType()))
+                    {
+                        _assigner.Assign(c);
+                    }
+                }
                 return;
             }
 
             bool includeInactive = _options.IncludeInactive;
             Scene activeScene = SceneManager.GetActiveScene();
 
-            foreach (Type componentType in relationalTypes)
+            if (_options.UseSinglePassScan)
             {
-                if (componentType == null)
+                using PooledResource<HashSet<Type>> pooledSet = Buffers<Type>.HashSet.Get(
+                    out HashSet<Type> relationalSet
+                );
+                for (int i = 0; i < relationalTypes.Count; i++)
                 {
-                    continue;
+                    Type t = relationalTypes[i];
+                    if (t != null)
+                    {
+                        relationalSet.Add(t);
+                    }
                 }
 
-                UnityEngine.Object[] located = includeInactive
-                    ? UnityEngine.Object.FindObjectsOfType(componentType, true)
-                    : UnityEngine.Object.FindObjectsOfType(componentType, false);
+                Component[] all = includeInactive
+                    ? Object.FindObjectsOfType<Component>(true)
+                    : Object.FindObjectsOfType<Component>(false);
 
-                foreach (UnityEngine.Object candidate in located)
+                for (int i = 0; i < all.Length; i++)
                 {
-                    if (candidate is not Component component)
+                    Component c = all[i];
+                    if (c == null || c.gameObject.scene != activeScene)
                     {
                         continue;
                     }
 
-                    if (component.gameObject.scene != activeScene)
+                    Type t = c.GetType();
+                    while (t != null && typeof(Component).IsAssignableFrom(t))
+                    {
+                        if (relationalSet.Contains(t))
+                        {
+                            _assigner.Assign(c);
+                            break;
+                        }
+                        t = t.BaseType;
+                    }
+                }
+            }
+            else
+            {
+                foreach (Type componentType in relationalTypes)
+                {
+                    if (componentType == null)
                     {
                         continue;
                     }
 
-                    _assigner.Assign(component);
+                    Object[] located = includeInactive
+                        ? Object.FindObjectsOfType(componentType, true)
+                        : Object.FindObjectsOfType(componentType, false);
+
+                    foreach (Object t in located)
+                    {
+                        if (t is not Component component)
+                        {
+                            continue;
+                        }
+
+                        if (component.gameObject.scene != activeScene)
+                        {
+                            continue;
+                        }
+
+                        _assigner.Assign(component);
+                    }
                 }
             }
+
+            // Safety net in Editor/tests: also walk scene roots to catch any missed
+#if UNITY_EDITOR
+            if (!Application.isPlaying)
+            {
+                using PooledResource<List<GameObject>> rootGoBuffer = Buffers<GameObject>.List.Get(
+                    out List<GameObject> roots
+                );
+                activeScene.GetRootGameObjects(roots);
+                foreach (GameObject root in roots)
+                {
+                    if (root == null)
+                    {
+                        continue;
+                    }
+                    _assigner.AssignHierarchy(root, includeInactive);
+                }
+            }
+#endif
         }
     }
 }

package/Runtime/Integrations/VContainer/RelationalComponentsBuilderExtensions.cs

@@ -14,6 +14,8 @@ namespace WallstopStudios.UnityHelpers.Integrations.VContainer
     /// <remarks>
     /// Registers the shared <see cref="IRelationalComponentAssigner"/> as a singleton and schedules a
     /// scene-wide entry point that hydrates all relational fields after the container has been built.
+    /// Optionally wires <see cref="RelationalSceneLoadListener"/> so future additive scenes receive
+    /// the same treatment.
     /// </remarks>
     public static class RelationalComponentsBuilderExtensions
     {
@@ -26,6 +28,10 @@ namespace WallstopStudios.UnityHelpers.Integrations.VContainer
         /// Optional settings to control how the active scene is scanned (e.g., include inactive
         /// objects). When <c>null</c>, <see cref="RelationalSceneAssignmentOptions.Default"/> is used.
         /// </param>
+        /// <param name="enableAdditiveSceneListener">
+        /// When true registers <see cref="RelationalSceneLoadListener"/> so additively loaded scenes
+        /// are hydrated with the same options. Disable when you manage additive scenes manually.
+        /// </param>
         /// <example>
         /// <code>
         /// using VContainer;
@@ -49,7 +55,8 @@ namespace WallstopStudios.UnityHelpers.Integrations.VContainer
         /// </example>
         public static void RegisterRelationalComponents(
             this IContainerBuilder builder,
-            RelationalSceneAssignmentOptions? options = null
+            RelationalSceneAssignmentOptions? options = null,
+            bool enableAdditiveSceneListener = true
         )
         {
             if (builder == null)
@@ -72,6 +79,11 @@ namespace WallstopStudios.UnityHelpers.Integrations.VContainer
                 .AsSelf();
 
             builder.RegisterEntryPoint<RelationalComponentEntryPoint>().WithParameter(resolved);
+
+            if (enableAdditiveSceneListener)
+            {
+                builder.RegisterEntryPoint<RelationalSceneLoadListener>().WithParameter(resolved);
+            }
         }
     }
 }

package/Runtime/Integrations/VContainer/RelationalObjectPools.cs

@@ -0,0 +1,114 @@
+#if VCONTAINER_PRESENT
+namespace WallstopStudios.UnityHelpers.Integrations.VContainer
+{
+    using System;
+    using global::VContainer;
+    using global::VContainer.Unity;
+    using UnityEngine;
+    using UnityEngine.Pool;
+
+    /// <summary>
+    /// Helpers for creating UnityEngine.Pool object pools plus extensions that hydrate pooled items
+    /// through VContainer when you rent them via <see cref="GetWithRelations{T}(ObjectPool{T},IObjectResolver)"/>.
+    /// </summary>
+    public static class RelationalObjectPools
+    {
+        /// <summary>
+        /// Creates a component pool to be combined with <see cref="GetWithRelations{T}(ObjectPool{T},IObjectResolver)"/>
+        /// so items are injected and hydrated on rental time.
+        /// </summary>
+        public static ObjectPool<T> CreatePoolWithRelations<T>(
+            Func<T> createFunc,
+            Action<T> actionOnGet = null,
+            Action<T> actionOnRelease = null,
+            Action<T> actionOnDestroy = null,
+            bool collectionCheck = true,
+            int defaultCapacity = 10,
+            int maxSize = 10000
+        )
+            where T : Component
+        {
+            if (createFunc == null)
+            {
+                throw new ArgumentNullException(nameof(createFunc));
+            }
+
+            return new ObjectPool<T>(
+                createFunc,
+                actionOnGet: actionOnGet,
+                actionOnRelease: actionOnRelease,
+                actionOnDestroy: actionOnDestroy,
+                collectionCheck: collectionCheck,
+                defaultCapacity: defaultCapacity,
+                maxSize: maxSize
+            );
+        }
+
+        /// <summary>
+        /// Creates a GameObject pool to be combined with
+        /// <see cref="GetWithRelations(ObjectPool{GameObject},IObjectResolver)"/> so hierarchies are
+        /// injected and hydrated on rental time.
+        /// </summary>
+        public static ObjectPool<GameObject> CreateGameObjectPoolWithRelations(
+            GameObject prefab,
+            Transform parent = null,
+            Action<GameObject> actionOnGet = null,
+            Action<GameObject> actionOnRelease = null,
+            Action<GameObject> actionOnDestroy = null,
+            bool collectionCheck = true,
+            int defaultCapacity = 10,
+            int maxSize = 10000
+        )
+        {
+            if (prefab == null)
+            {
+                throw new ArgumentNullException(nameof(prefab));
+            }
+
+            Func<GameObject> create = () => UnityEngine.Object.Instantiate(prefab, parent);
+
+            return new ObjectPool<GameObject>(
+                create,
+                actionOnGet: actionOnGet,
+                actionOnRelease: actionOnRelease,
+                actionOnDestroy: actionOnDestroy,
+                collectionCheck: collectionCheck,
+                defaultCapacity: defaultCapacity,
+                maxSize: maxSize
+            );
+        }
+
+        /// <summary>
+        /// Rents an item from the pool, injects and assigns relational fields.
+        /// </summary>
+        public static T GetWithRelations<T>(this ObjectPool<T> pool, IObjectResolver resolver)
+            where T : Component
+        {
+            T item = pool.Get();
+            if (item != null)
+            {
+                resolver?.Inject(item);
+                resolver.AssignRelationalComponents(item);
+            }
+            return item;
+        }
+
+        /// <summary>
+        /// Rents a GameObject from the pool, injects the hierarchy and assigns relational fields.
+        /// </summary>
+        public static GameObject GetWithRelations(
+            this ObjectPool<GameObject> pool,
+            IObjectResolver resolver
+        )
+        {
+            GameObject go = pool.Get();
+            if (go != null)
+            {
+                resolver?.InjectGameObject(go);
+                resolver.AssignRelationalHierarchy(go, includeInactiveChildren: true);
+            }
+            return go;
+        }
+    }
+}
+#endif

package/Runtime/Integrations/VContainer/RelationalObjectPools.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: fa576218812adfe4b98444f975a1cbf4
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Integrations/VContainer/RelationalSceneAssignmentOptions.cs

@@ -2,6 +2,7 @@
 namespace WallstopStudios.UnityHelpers.Integrations.VContainer
 {
     using System;
+    using WallstopStudios.UnityHelpers.Core.Helper;
 
     /// <summary>
     /// Controls how the VContainer integration applies relational component assignment.
@@ -24,25 +25,36 @@ namespace WallstopStudios.UnityHelpers.Integrations.VContainer
         /// When true the entry point will scan inactive scene objects so that relational fields are
         /// populated even for disabled hierarchies. Defaults to <c>true</c>.
         /// </param>
-        public RelationalSceneAssignmentOptions(bool includeInactive)
+        /// <param name="useSinglePassScan">
+        /// When true uses a single-pass scene scan for performance (recommended). Defaults to
+        /// <c>true</c>.
+        /// </param>
+        public RelationalSceneAssignmentOptions(bool includeInactive, bool useSinglePassScan = true)
         {
             IncludeInactive = includeInactive;
+            UseSinglePassScan = useSinglePassScan;
         }
 
         /// <summary>
         /// Options used when no explicit configuration is supplied.
         /// </summary>
-        public static RelationalSceneAssignmentOptions Default => new(includeInactive: true);
+        public static RelationalSceneAssignmentOptions Default => new(true, true);
 
         /// <summary>
         /// Gets whether inactive GameObjects should be included when scanning the scene.
         /// </summary>
         public bool IncludeInactive { get; }
 
+        /// <summary>
+        /// Gets whether to use a single-pass scene scan to locate relational components.
+        /// </summary>
+        public bool UseSinglePassScan { get; }
+
         /// <inheritdoc />
         public bool Equals(RelationalSceneAssignmentOptions other)
         {
-            return IncludeInactive == other.IncludeInactive;
+            return IncludeInactive == other.IncludeInactive
+                && UseSinglePassScan == other.UseSinglePassScan;
         }
 
         /// <inheritdoc />
@@ -54,7 +66,7 @@ namespace WallstopStudios.UnityHelpers.Integrations.VContainer
         /// <inheritdoc />
         public override int GetHashCode()
         {
-            return IncludeInactive.GetHashCode();
+            return Objects.HashCode(IncludeInactive, UseSinglePassScan);
         }
 
         /// <summary>

package/Runtime/Integrations/VContainer/RelationalSceneLoadListener.cs

@@ -0,0 +1,241 @@
+#if VCONTAINER_PRESENT
+namespace WallstopStudios.UnityHelpers.Integrations.VContainer
+{
+    using System;
+    using System.Collections.Generic;
+    using global::VContainer.Unity;
+    using UnityEngine;
+    using UnityEngine.SceneManagement;
+    using WallstopStudios.UnityHelpers.Core.Attributes;
+    using WallstopStudios.UnityHelpers.Tags;
+    using WallstopStudios.UnityHelpers.Utils;
+
+    /// <summary>
+    /// Listens for additive scene loads and assigns relational fields for components in the
+    /// newly loaded scene using the configured options.
+    /// </summary>
+    public sealed class RelationalSceneLoadListener : IInitializable, IDisposable
+    {
+        private readonly IRelationalComponentAssigner _assigner;
+        private readonly AttributeMetadataCache _metadataCache;
+        private readonly RelationalSceneAssignmentOptions _options;
+
+        public RelationalSceneLoadListener(
+            IRelationalComponentAssigner assigner,
+            AttributeMetadataCache metadataCache,
+            RelationalSceneAssignmentOptions options
+        )
+        {
+            _assigner = assigner ?? throw new ArgumentNullException(nameof(assigner));
+            _metadataCache = metadataCache;
+            _options = options;
+        }
+
+        public void Initialize()
+        {
+            SceneManager.sceneLoaded += OnSceneLoaded;
+        }
+
+        public void Dispose()
+        {
+            SceneManager.sceneLoaded -= OnSceneLoaded;
+        }
+
+        internal void OnSceneLoaded(Scene scene, LoadSceneMode mode)
+        {
+            if (!scene.IsValid())
+            {
+                return;
+            }
+
+            AttributeMetadataCache cache = _metadataCache ?? AttributeMetadataCache.Instance;
+            if (cache == null)
+            {
+                return;
+            }
+
+            using PooledResource<List<Type>> pooledTypes = Buffers<Type>.List.Get(
+                out List<Type> relationalTypes
+            );
+            cache.CollectRelationalComponentTypes(relationalTypes);
+
+            bool includeInactive = _options.IncludeInactive;
+            if (relationalTypes.Count == 0)
+            {
+                // Fallback: scan all components once and assign when type has relational fields
+                Component[] all = includeInactive
+                    ? UnityEngine.Object.FindObjectsOfType<Component>(true)
+                    : UnityEngine.Object.FindObjectsOfType<Component>(false);
+
+                for (int i = 0; i < all.Length; i++)
+                {
+                    Component c = all[i];
+                    if (c == null || c.gameObject.scene != scene)
+                    {
+                        continue;
+                    }
+
+                    if (_assigner.HasRelationalAssignments(c.GetType()))
+                    {
+                        _assigner.Assign(c);
+                    }
+                }
+                return;
+            }
+
+            if (_options.UseSinglePassScan)
+            {
+                AssignBySinglePass(scene, relationalTypes, includeInactive);
+            }
+            else
+            {
+                AssignByTypePass(scene, relationalTypes, includeInactive);
+            }
+
+            // Safety net in Editor/tests: walk scene roots to catch any missed components
+#if UNITY_EDITOR
+            if (!Application.isPlaying)
+            {
+                AssignBySceneRoots(scene, includeInactive);
+
+                // In EditMode, object registration can lag a frame after scene creation.
+                // Schedule a follow-up pass to catch late-registered components.
+                UnityEditor.EditorApplication.delayCall += () =>
+                {
+                    if (scene.IsValid())
+                    {
+                        AssignBySceneRoots(scene, includeInactive);
+                    }
+                };
+            }
+#endif
+        }
+
+        private void AssignByTypePass(
+            Scene target,
+            List<Type> relationalTypes,
+            bool includeInactive
+        )
+        {
+            using PooledResource<List<GameObject>> rootGoBuffer = Buffers<GameObject>.List.Get(
+                out List<GameObject> roots
+            );
+            target.GetRootGameObjects(roots);
+            if (roots.Count == 0)
+            {
+                return;
+            }
+
+            using PooledResource<HashSet<Type>> typeSetPool = Buffers<Type>.HashSet.Get(
+                out HashSet<Type> relationalSet
+            );
+            for (int i = 0; i < relationalTypes.Count; i++)
+            {
+                Type relationalType = relationalTypes[i];
+                if (relationalType != null)
+                {
+                    relationalSet.Add(relationalType);
+                }
+            }
+
+            using PooledResource<List<Component>> componentBuffer = Buffers<Component>.List.Get(
+                out List<Component> components
+            );
+
+            for (int i = 0; i < roots.Count; i++)
+            {
+                GameObject root = roots[i];
+                if (root == null)
+                {
+                    continue;
+                }
+
+                root.GetComponentsInChildren(includeInactive, components);
+                for (int j = 0; j < components.Count; j++)
+                {
+                    Component component = components[j];
+                    if (component == null || component.gameObject.scene != target)
+                    {
+                        continue;
+                    }
+
+                    Type current = component.GetType();
+                    while (current != null && typeof(Component).IsAssignableFrom(current))
+                    {
+                        if (relationalSet.Contains(current))
+                        {
+                            _assigner.Assign(component);
+                            break;
+                        }
+                        current = current.BaseType;
+                    }
+                }
+
+                components.Clear();
+            }
+        }
+
+        private void AssignBySinglePass(
+            Scene target,
+            List<Type> relationalTypes,
+            bool includeInactive
+        )
+        {
+            using PooledResource<HashSet<Type>> pooledSet = Buffers<Type>.HashSet.Get(
+                out HashSet<Type> relationalSet
+            );
+            foreach (Type t in relationalTypes)
+            {
+                if (t != null)
+                {
+                    relationalSet.Add(t);
+                }
+            }
+
+            Component[] all = includeInactive
+                ? UnityEngine.Object.FindObjectsOfType<Component>(true)
+                : UnityEngine.Object.FindObjectsOfType<Component>(false);
+
+            foreach (Component component in all)
+            {
+                if (component == null || component.gameObject.scene != target)
+                {
+                    continue;
+                }
+
+                Type t = component.GetType();
+                while (t != null && typeof(Component).IsAssignableFrom(t))
+                {
+                    if (relationalSet.Contains(t))
+                    {
+                        _assigner.Assign(component);
+                        break;
+                    }
+                    t = t.BaseType;
+                }
+            }
+        }
+
+        private void AssignBySceneRoots(Scene target, bool includeInactive)
+        {
+            int rootCount = target.rootCount;
+            if (rootCount == 0)
+            {
+                return;
+            }
+            using PooledResource<List<GameObject>> rootGoBuffer = Buffers<GameObject>.List.Get(
+                out List<GameObject> roots
+            );
+            target.GetRootGameObjects(roots);
+            foreach (GameObject root in roots)
+            {
+                if (root == null)
+                {
+                    continue;
+                }
+                _assigner.AssignHierarchy(root, includeInactive);
+            }
+        }
+    }
+}
+#endif

package/Runtime/Integrations/VContainer/RelationalSceneLoadListener.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 9a9e90db7c71e6d448d94c973df2fb1b
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Integrations/Zenject/AssemblyInfo.cs

@@ -0,0 +1,9 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Editor")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Runtime")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Editor")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Runtime.Zenject")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Runtime.VContainer")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Editor.VContainer")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Editor.Zenject")]

package/Runtime/Integrations/Zenject/AssemblyInfo.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 8e6f7bff5ef44f688472b92382e2a9aa
+timeCreated: 1760388364