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

package/Runtime/Integrations/Zenject/DiContainerRelationalExtensions.cs

@@ -50,6 +50,26 @@ namespace WallstopStudios.UnityHelpers.Integrations.Zenject
     /// </example>
     public static class DiContainerRelationalExtensions
     {
+        /// <summary>
+        /// Injects <paramref name="component"/> with Zenject and assigns its relational fields.
+        /// </summary>
+        /// <typeparam name="T">The component type.</typeparam>
+        /// <param name="container">The Zenject container.</param>
+        /// <param name="component">The component instance to inject and hydrate.</param>
+        /// <returns>The same component instance.</returns>
+        public static T InjectWithRelations<T>(this DiContainer container, T component)
+            where T : Component
+        {
+            if (component == null)
+            {
+                return null;
+            }
+
+            container?.Inject(component);
+            container.AssignRelationalComponents(component);
+            return component;
+        }
+
         /// <summary>
         /// Assigns all relational fields on a component using the container-registered
         /// <see cref="IRelationalComponentAssigner"/>, with a safe fallback to the non-DI path.
@@ -124,9 +144,9 @@ namespace WallstopStudios.UnityHelpers.Integrations.Zenject
                 out List<Component> components
             );
             root.GetComponentsInChildren(includeInactiveChildren, components);
-            for (int i = 0; i < components.Count; i++)
+            foreach (Component component in components)
             {
-                components[i].AssignRelationalComponents();
+                component.AssignRelationalComponents();
             }
         }
 
@@ -161,6 +181,53 @@ namespace WallstopStudios.UnityHelpers.Integrations.Zenject
             return instance;
         }
 
+        /// <summary>
+        /// Instantiates a GameObject prefab with Zenject, injects the hierarchy and assigns
+        /// relational fields across the new instance.
+        /// </summary>
+        /// <param name="container">The Zenject container.</param>
+        /// <param name="prefab">GameObject prefab.</param>
+        /// <param name="parent">Optional parent transform.</param>
+        /// <param name="includeInactiveChildren">Include inactive children when assigning.</param>
+        /// <returns>The instantiated GameObject.</returns>
+        public static GameObject InstantiateGameObjectWithRelations(
+            this DiContainer container,
+            GameObject prefab,
+            Transform parent = null,
+            bool includeInactiveChildren = true
+        )
+        {
+            if (prefab == null)
+            {
+                throw new ArgumentNullException(nameof(prefab));
+            }
+
+            GameObject instance = container.InstantiatePrefab(prefab, parent);
+            container.InjectGameObjectWithRelations(instance, includeInactiveChildren);
+            return instance;
+        }
+
+        /// <summary>
+        /// Injects all components on <paramref name="root"/> and children with Zenject, then assigns
+        /// relational fields across the hierarchy.
+        /// </summary>
+        /// <param name="container">The Zenject container.</param>
+        /// <param name="root">Root GameObject.</param>
+        /// <param name="includeInactiveChildren">Include inactive children when assigning.</param>
+        public static void InjectGameObjectWithRelations(
+            this DiContainer container,
+            GameObject root,
+            bool includeInactiveChildren = true
+        )
+        {
+            if (root == null)
+            {
+                return;
+            }
+            container?.InjectGameObject(root);
+            container.AssignRelationalHierarchy(root, includeInactiveChildren);
+        }
+
         private static IRelationalComponentAssigner ResolveAssigner(DiContainer container)
         {
             if (container == null)

package/Runtime/Integrations/Zenject/RelationalComponentSceneInitializer.cs

@@ -65,40 +65,117 @@ namespace WallstopStudios.UnityHelpers.Integrations.Zenject
 
             if (relationalTypes.Count == 0)
             {
+                // Fallback: scan all components in the active scene and assign when type has relational fields
+                bool includeInactiveAll = _options.IncludeInactive;
+                Scene active = SceneManager.GetActiveScene();
+                Component[] allComponents = includeInactiveAll
+                    ? UnityEngine.Object.FindObjectsOfType<Component>(true)
+                    : UnityEngine.Object.FindObjectsOfType<Component>(false);
+
+                for (int i = 0; i < allComponents.Length; i++)
+                {
+                    Component c = allComponents[i];
+                    if (c == null || c.gameObject.scene != active)
+                    {
+                        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
+                );
+                foreach (Type relationalType in relationalTypes)
                 {
-                    continue;
+                    if (relationalType != null)
+                    {
+                        relationalSet.Add(relationalType);
+                    }
                 }
 
-                UnityEngine.Object[] located = includeInactive
-                    ? UnityEngine.Object.FindObjectsOfType(componentType, true)
-                    : UnityEngine.Object.FindObjectsOfType(componentType, false);
+                Component[] all = includeInactive
+                    ? UnityEngine.Object.FindObjectsOfType<Component>(true)
+                    : UnityEngine.Object.FindObjectsOfType<Component>(false);
+
+                foreach (Component c in all)
+                {
+                    if (c == null || c.gameObject.scene != activeScene)
+                    {
+                        continue;
+                    }
 
-                foreach (UnityEngine.Object candidate in located)
+                    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 (candidate is not Component component)
+                    if (componentType == null)
                     {
                         continue;
                     }
 
-                    // Ignore components that belong to scenes other than the active one to avoid
-                    // touching additive scenes unintentionally.
-                    if (component.gameObject.scene != activeScene)
+                    UnityEngine.Object[] located = includeInactive
+                        ? UnityEngine.Object.FindObjectsOfType(componentType, true)
+                        : UnityEngine.Object.FindObjectsOfType(componentType, false);
+
+                    foreach (UnityEngine.Object candidate in located)
+                    {
+                        if (candidate is not Component component)
+                        {
+                            continue;
+                        }
+
+                        if (component == null || component.gameObject.scene != activeScene)
+                        {
+                            continue;
+                        }
+
+                        _assigner.Assign(component);
+                    }
+                }
+            }
+
+            // Safety net in Editor/tests: also walk scene roots to ensure coverage
+#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.Assign(component);
+                    _assigner.AssignHierarchy(root, includeInactive);
                 }
             }
+#endif
         }
     }
 }

package/Runtime/Integrations/Zenject/RelationalComponentsInstaller.cs

@@ -12,9 +12,13 @@ namespace WallstopStudios.UnityHelpers.Integrations.Zenject
     /// </summary>
     /// <remarks>
     /// Add this installer to your <c>SceneContext</c> to:
-    /// - Bind <see cref="IRelationalComponentAssigner"/> as a singleton
+    /// - Bind <see cref="IRelationalComponentAssigner"/> as a singleton (if nobody else already did)
     /// - Optionally register <see cref="RelationalComponentSceneInitializer"/> to populate relational
     ///   fields after container construction
+    /// - Optionally register <see cref="RelationalSceneLoadListener"/> so additively loaded scenes
+    ///   receive the same hydration pass
+    /// Serialized toggles expose these behaviours plus the shared
+    /// <see cref="RelationalSceneAssignmentOptions"/> (include inactive objects, scan strategy).
     /// </remarks>
     /// <example>
     /// <code>
@@ -39,6 +43,13 @@ namespace WallstopStudios.UnityHelpers.Integrations.Zenject
         )]
         private bool _includeInactiveObjects = true;
 
+        [SerializeField]
+        [Tooltip(
+            "When enabled, registers a listener that assigns relational fields for additively loaded"
+                + " scenes as they are loaded."
+        )]
+        private bool _listenForAdditiveScenes = true;
+
         public override void InstallBindings()
         {
             AttributeMetadataCache cacheInstance = AttributeMetadataCache.Instance;
@@ -66,6 +77,17 @@ namespace WallstopStudios.UnityHelpers.Integrations.Zenject
 
                 Container.BindInterfacesTo<RelationalComponentSceneInitializer>().AsSingle();
             }
+
+            if (_listenForAdditiveScenes)
+            {
+                if (!Container.HasBinding(typeof(RelationalSceneAssignmentOptions)))
+                {
+                    Container.BindInstance(
+                        new RelationalSceneAssignmentOptions(_includeInactiveObjects)
+                    );
+                }
+                Container.BindInterfacesTo<RelationalSceneLoadListener>().AsSingle();
+            }
         }
     }
 }

package/Runtime/Integrations/Zenject/RelationalMemoryPools.cs

@@ -0,0 +1,44 @@
+#if ZENJECT_PRESENT
+namespace WallstopStudios.UnityHelpers.Integrations.Zenject
+{
+    using global::Zenject;
+    using UnityEngine;
+
+    /// <summary>
+    /// MemoryPool that assigns relational fields for spawned items automatically.
+    /// </summary>
+    /// <typeparam name="TValue">Component type managed by the pool.</typeparam>
+    public class RelationalMemoryPool<TValue> : MemoryPool<TValue>
+        where TValue : Component
+    {
+        [Inject]
+        internal DiContainer _container = null;
+
+        protected override void OnSpawned(TValue item)
+        {
+            base.OnSpawned(item);
+            _container.AssignRelationalComponents(item);
+        }
+
+        internal void InternalOnSpawned(TValue item) => OnSpawned(item);
+    }
+
+    /// <summary>
+    /// MemoryPool with one spawn parameter that assigns relational fields for spawned items.
+    /// </summary>
+    /// <typeparam name="TParam1">Spawn parameter type.</typeparam>
+    /// <typeparam name="TValue">Component type managed by the pool.</typeparam>
+    public class RelationalMemoryPool<TParam1, TValue> : MemoryPool<TParam1, TValue>
+        where TValue : Component
+    {
+        [Inject]
+        internal DiContainer _container = null;
+
+        protected override void Reinitialize(TParam1 p1, TValue item)
+        {
+            base.Reinitialize(p1, item);
+            _container.AssignRelationalComponents(item);
+        }
+    }
+}
+#endif

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

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

package/Runtime/Integrations/Zenject/RelationalSceneAssignmentOptions.cs

@@ -2,6 +2,7 @@
 namespace WallstopStudios.UnityHelpers.Integrations.Zenject
 {
     using System;
+    using WallstopStudios.UnityHelpers.Core.Helper;
 
     /// <summary>
     /// Controls how the Zenject integration scans the scene for relational components.
@@ -22,25 +23,36 @@ namespace WallstopStudios.UnityHelpers.Integrations.Zenject
         /// When true the initializer 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 />
@@ -52,12 +64,9 @@ namespace WallstopStudios.UnityHelpers.Integrations.Zenject
         /// <inheritdoc />
         public override int GetHashCode()
         {
-            return IncludeInactive.GetHashCode();
+            return Objects.HashCode(IncludeInactive, UseSinglePassScan);
         }
 
-        /// <summary>
-        /// Equality operator.
-        /// </summary>
         /// <summary>
         /// Equality operator.
         /// </summary>
@@ -69,9 +78,6 @@ namespace WallstopStudios.UnityHelpers.Integrations.Zenject
             return left.Equals(right);
         }
 
-        /// <summary>
-        /// Inequality operator.
-        /// </summary>
         /// <summary>
         /// Inequality operator.
         /// </summary>

package/Runtime/Integrations/Zenject/RelationalSceneLoadListener.cs

@@ -0,0 +1,243 @@
+#if ZENJECT_PRESENT
+namespace WallstopStudios.UnityHelpers.Integrations.Zenject
+{
+    using System;
+    using System.Collections.Generic;
+    using global::Zenject;
+    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 within the newly loaded scene.
+    /// </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);
+
+            if (relationalTypes.Count == 0)
+            {
+                // Fallback: scan all components in new scene and assign when type has relational fields
+                bool includeInactiveAll = _options.IncludeInactive;
+                Component[] all = includeInactiveAll
+                    ? 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;
+            }
+
+            bool includeInactive = _options.IncludeInactive;
+
+            if (_options.UseSinglePassScan)
+            {
+                AssignBySinglePass(scene, relationalTypes, includeInactive);
+            }
+            else
+            {
+                AssignByTypePass(scene, relationalTypes, includeInactive);
+            }
+
+            // Safety net in Editor/tests: also walk scene roots
+#if UNITY_EDITOR
+            if (!Application.isPlaying)
+            {
+                AssignBySceneRoots(scene, includeInactive);
+
+                // In EditMode, some components may be registered on the following editor tick.
+                // Schedule a delayed pass to ensure complete hydration in tests/tools.
+                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 type = relationalTypes[i];
+                if (type != null)
+                {
+                    relationalSet.Add(type);
+                }
+            }
+
+            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
+            );
+            for (int i = 0; i < relationalTypes.Count; i++)
+            {
+                if (relationalTypes[i] != null)
+                {
+                    relationalSet.Add(relationalTypes[i]);
+                }
+            }
+
+            Component[] all = includeInactive
+                ? UnityEngine.Object.FindObjectsOfType<Component>(true)
+                : UnityEngine.Object.FindObjectsOfType<Component>(false);
+
+            for (int i = 0; i < all.Length; i++)
+            {
+                Component component = all[i];
+                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/Zenject/RelationalSceneLoadListener.cs.meta

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

package/Runtime/Tags/AttributeMetadataCache.cs

@@ -227,10 +227,7 @@ namespace WallstopStudios.UnityHelpers.Tags
                 if (inst != null && inst._prewarmRelationalOnLoad)
                 {
                     RelationalComponentInitializer.Report report =
-                        Core.Attributes.RelationalComponentInitializer.Initialize(
-                            types: null,
-                            logSummary: false
-                        );
+                        RelationalComponentInitializer.Initialize(types: null, logSummary: false);
                     Debug.Log(
                         $"AttributeMetadataCache: Relational prewarm enabled. TypesWarmed={report.TypesWarmed}, FieldsWarmed={report.FieldsWarmed}, Warnings={report.Warnings}, Errors={report.Errors}."
                     );