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

package/Runtime/Integrations/Reflex/RelationalReflexSceneBootstrapper.cs

@@ -0,0 +1,316 @@
+#if REFLEX_PRESENT
+namespace WallstopStudios.UnityHelpers.Integrations.Reflex
+{
+    using System;
+    using System.Collections.Generic;
+    using global::Reflex.Core;
+    using UnityEngine;
+    using UnityEngine.SceneManagement;
+    using WallstopStudios.UnityHelpers.Core.Attributes;
+    using WallstopStudios.UnityHelpers.Tags;
+    using WallstopStudios.UnityHelpers.Utils;
+
+    internal static class RelationalReflexSceneBootstrapper
+    {
+        public static void ConfigureScene(
+            Container container,
+            Scene scene,
+            RelationalSceneAssignmentOptions options,
+            bool assignSceneOnInitialize,
+            bool listenForAdditiveScenes
+        )
+        {
+            if (container == null)
+            {
+                return;
+            }
+
+            IRelationalComponentAssigner assigner = ResolveAssigner(container);
+            if (assigner == null)
+            {
+                return;
+            }
+
+            AttributeMetadataCache metadataCache = ResolveMetadata(container);
+
+            if (assignSceneOnInitialize)
+            {
+                AssignScene(scene, assigner, metadataCache, options);
+            }
+
+            if (listenForAdditiveScenes)
+            {
+                RelationalSceneLoadListener listener = new(assigner, metadataCache, options, scene);
+                listener.Activate();
+            }
+        }
+
+        internal static void AssignScene(
+            Scene scene,
+            IRelationalComponentAssigner assigner,
+            AttributeMetadataCache metadataCache,
+            RelationalSceneAssignmentOptions options
+        )
+        {
+            if (!scene.IsValid() || assigner == null)
+            {
+                return;
+            }
+
+            AttributeMetadataCache cache = metadataCache ?? AttributeMetadataCache.Instance;
+            if (cache == null)
+            {
+                AssignBySceneRoots(scene, assigner, options.IncludeInactive);
+                return;
+            }
+
+            using PooledResource<List<Type>> typeBuffer = Buffers<Type>.List.Get(
+                out List<Type> relationalTypes
+            );
+            cache.CollectRelationalComponentTypes(relationalTypes);
+
+            if (relationalTypes.Count == 0)
+            {
+                AssignBySceneRoots(scene, assigner, options.IncludeInactive);
+                return;
+            }
+
+            if (options.UseSinglePassScan)
+            {
+                AssignBySinglePass(scene, assigner, relationalTypes, options.IncludeInactive);
+            }
+            else
+            {
+                AssignByTypePass(scene, assigner, relationalTypes, options.IncludeInactive);
+            }
+
+#if UNITY_EDITOR
+            if (!Application.isPlaying)
+            {
+                AssignBySceneRoots(scene, assigner, options.IncludeInactive);
+                UnityEditor.EditorApplication.delayCall += () =>
+                {
+                    if (scene.IsValid())
+                    {
+                        AssignBySceneRoots(scene, assigner, options.IncludeInactive);
+                    }
+                };
+            }
+#endif
+        }
+
+        private static void AssignByTypePass(
+            Scene target,
+            IRelationalComponentAssigner assigner,
+            List<Type> relationalTypes,
+            bool includeInactive
+        )
+        {
+            using PooledResource<List<GameObject>> rootBuffer = 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 static void AssignBySinglePass(
+            Scene target,
+            IRelationalComponentAssigner assigner,
+            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++)
+            {
+                Type type = relationalTypes[i];
+                if (type != null)
+                {
+                    relationalSet.Add(type);
+                }
+            }
+
+            Component[] allComponents = includeInactive
+                ? UnityEngine.Object.FindObjectsOfType<Component>(true)
+                : UnityEngine.Object.FindObjectsOfType<Component>(false);
+
+            for (int i = 0; i < allComponents.Length; i++)
+            {
+                Component component = allComponents[i];
+                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;
+                }
+            }
+        }
+
+        private static void AssignBySceneRoots(
+            Scene target,
+            IRelationalComponentAssigner assigner,
+            bool includeInactive
+        )
+        {
+            if (!target.IsValid())
+            {
+                return;
+            }
+
+            using PooledResource<List<GameObject>> rootBuffer = Buffers<GameObject>.List.Get(
+                out List<GameObject> roots
+            );
+            target.GetRootGameObjects(roots);
+            for (int i = 0; i < roots.Count; i++)
+            {
+                GameObject root = roots[i];
+                if (root == null)
+                {
+                    continue;
+                }
+
+                assigner.AssignHierarchy(root, includeInactive);
+            }
+        }
+
+        private static IRelationalComponentAssigner ResolveAssigner(Container container)
+        {
+            if (container.HasBinding<IRelationalComponentAssigner>())
+            {
+                return container.Resolve<IRelationalComponentAssigner>();
+            }
+            return null;
+        }
+
+        private static AttributeMetadataCache ResolveMetadata(Container container)
+        {
+            if (container.HasBinding<AttributeMetadataCache>())
+            {
+                return container.Resolve<AttributeMetadataCache>();
+            }
+            return AttributeMetadataCache.Instance;
+        }
+
+        private sealed class RelationalSceneLoadListener
+        {
+            private readonly IRelationalComponentAssigner _assigner;
+            private readonly AttributeMetadataCache _metadataCache;
+            private readonly RelationalSceneAssignmentOptions _options;
+            private readonly Scene _originScene;
+            private bool _isActive;
+
+            public RelationalSceneLoadListener(
+                IRelationalComponentAssigner assigner,
+                AttributeMetadataCache metadataCache,
+                RelationalSceneAssignmentOptions options,
+                Scene originScene
+            )
+            {
+                _assigner = assigner;
+                _metadataCache = metadataCache;
+                _options = options;
+                _originScene = originScene;
+            }
+
+            public void Activate()
+            {
+                if (_isActive)
+                {
+                    return;
+                }
+
+                SceneManager.sceneLoaded += OnSceneLoaded;
+                SceneManager.sceneUnloaded += OnSceneUnloaded;
+                _isActive = true;
+            }
+
+            private void OnSceneLoaded(Scene scene, LoadSceneMode mode)
+            {
+                if (mode != LoadSceneMode.Additive || !_isActive)
+                {
+                    return;
+                }
+
+                AssignScene(scene, _assigner, _metadataCache, _options);
+            }
+
+            private void OnSceneUnloaded(Scene scene)
+            {
+                if (!_isActive)
+                {
+                    return;
+                }
+
+                if (scene == _originScene)
+                {
+                    SceneManager.sceneLoaded -= OnSceneLoaded;
+                    SceneManager.sceneUnloaded -= OnSceneUnloaded;
+                    _isActive = false;
+                }
+            }
+        }
+    }
+}
+#endif

package/Runtime/Integrations/Reflex/RelationalReflexSceneBootstrapper.cs.meta

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

package/Runtime/Integrations/Reflex/RelationalSceneAssignmentOptions.cs

@@ -0,0 +1,86 @@
+#if REFLEX_PRESENT
+namespace WallstopStudios.UnityHelpers.Integrations.Reflex
+{
+    using System;
+    using WallstopStudios.UnityHelpers.Core.Helper;
+
+    /// <summary>
+    /// Controls how the Reflex integration performs relational component assignment across scenes.
+    /// </summary>
+    public readonly struct RelationalSceneAssignmentOptions
+        : IEquatable<RelationalSceneAssignmentOptions>
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="RelationalSceneAssignmentOptions"/> struct.
+        /// </summary>
+        /// <param name="includeInactive">
+        /// When true, relational assignment scans include inactive GameObjects. Defaults to true.
+        /// </param>
+        /// <param name="useSinglePassScan">
+        /// When true, performs a single-pass scan for relational types to maximize performance.
+        /// Defaults to true.
+        /// </param>
+        public RelationalSceneAssignmentOptions(bool includeInactive, bool useSinglePassScan = true)
+        {
+            IncludeInactive = includeInactive;
+            UseSinglePassScan = useSinglePassScan;
+        }
+
+        /// <summary>
+        /// Gets default options (include inactive objects, single-pass scan).
+        /// </summary>
+        public static RelationalSceneAssignmentOptions Default => new(true, true);
+
+        /// <summary>
+        /// Gets whether inactive GameObjects are included during scans.
+        /// </summary>
+        public bool IncludeInactive { get; }
+
+        /// <summary>
+        /// Gets whether to use a single-pass scan strategy.
+        /// </summary>
+        public bool UseSinglePassScan { get; }
+
+        /// <inheritdoc />
+        public bool Equals(RelationalSceneAssignmentOptions other)
+        {
+            return IncludeInactive == other.IncludeInactive
+                && UseSinglePassScan == other.UseSinglePassScan;
+        }
+
+        /// <inheritdoc />
+        public override bool Equals(object obj)
+        {
+            return obj is RelationalSceneAssignmentOptions other && Equals(other);
+        }
+
+        /// <inheritdoc />
+        public override int GetHashCode()
+        {
+            return Objects.HashCode(IncludeInactive, UseSinglePassScan);
+        }
+
+        /// <summary>
+        /// Equality operator.
+        /// </summary>
+        public static bool operator ==(
+            RelationalSceneAssignmentOptions left,
+            RelationalSceneAssignmentOptions right
+        )
+        {
+            return left.Equals(right);
+        }
+
+        /// <summary>
+        /// Inequality operator.
+        /// </summary>
+        public static bool operator !=(
+            RelationalSceneAssignmentOptions left,
+            RelationalSceneAssignmentOptions right
+        )
+        {
+            return !left.Equals(right);
+        }
+    }
+}
+#endif

package/Runtime/Integrations/Reflex/RelationalSceneAssignmentOptions.cs.meta

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

package/Runtime/Integrations/Reflex/WallstopStudios.UnityHelpers.Integration.Reflex.asmdef

@@ -0,0 +1,20 @@
+{
+  "name": "WallstopStudios.UnityHelpers.Integration.Reflex",
+  "rootNamespace": "WallstopStudios.UnityHelpers.Integrations.Reflex",
+  "references": ["WallstopStudios.UnityHelpers", "Reflex"],
+  "includePlatforms": [],
+  "excludePlatforms": [],
+  "allowUnsafeCode": false,
+  "overrideReferences": false,
+  "precompiledReferences": [],
+  "autoReferenced": true,
+  "defineConstraints": ["REFLEX_PRESENT"],
+  "versionDefines": [
+    {
+      "name": "com.gustavopsantos.reflex",
+      "expression": "0.0.1",
+      "define": "REFLEX_PRESENT"
+    }
+  ],
+  "noEngineReferences": false
+}

package/Runtime/Integrations/Reflex/WallstopStudios.UnityHelpers.Integration.Reflex.asmdef.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: a97bece904584fe29a1cb15c14637610
+AssemblyDefinitionImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Integrations/Reflex.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: ad38057b5632441999deda0a7c20a633
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Integrations/VContainer/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/VContainer/AssemblyInfo.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 87d075d4bb0645c2a11721a306a1de00
+timeCreated: 1760388352

package/Runtime/Integrations/VContainer/ObjectResolverRelationalExtensions.cs

@@ -1,8 +1,10 @@
 #if VCONTAINER_PRESENT
 namespace WallstopStudios.UnityHelpers.Integrations.VContainer
 {
+    using System;
     using System.Collections.Generic;
     using global::VContainer;
+    using global::VContainer.Unity;
     using UnityEngine;
     using WallstopStudios.UnityHelpers.Core.Attributes;
     using WallstopStudios.UnityHelpers.Utils;
@@ -56,6 +58,27 @@ namespace WallstopStudios.UnityHelpers.Integrations.VContainer
     /// </example>
     public static class ObjectResolverRelationalExtensions
     {
+        /// <summary>
+        /// Injects <paramref name="component"/> with VContainer and assigns its relational fields.
+        /// </summary>
+        /// <typeparam name="T">The component type.</typeparam>
+        /// <param name="resolver">The VContainer object resolver.</param>
+        /// <param name="component">The component instance to inject and hydrate.</param>
+        /// <returns>The same component instance.</returns>
+        public static T InjectWithRelations<T>(this IObjectResolver resolver, T component)
+            where T : Component
+        {
+            if (component == null)
+            {
+                return null;
+            }
+
+            // Use Inject for compatibility with VContainer 1.16.x
+            resolver?.Inject(component);
+            resolver.AssignRelationalComponents(component);
+            return component;
+        }
+
         /// <summary>
         /// Assigns all relational fields on a component using the container's registered
         /// <see cref="IRelationalComponentAssigner"/> if present, with a safe fallback to the
@@ -167,6 +190,79 @@ namespace WallstopStudios.UnityHelpers.Integrations.VContainer
             return component;
         }
 
+        /// <summary>
+        /// Instantiates a prefab that has component <typeparamref name="T"/> on the root, injects it
+        /// using VContainer and assigns relational fields.
+        /// </summary>
+        /// <typeparam name="T">Component type on the prefab root.</typeparam>
+        /// <param name="resolver">The VContainer object resolver.</param>
+        /// <param name="prefab">Prefab that contains <typeparamref name="T"/>.</param>
+        /// <param name="parent">Optional parent transform for the new instance.</param>
+        /// <returns>The instantiated component with DI and relational fields populated.</returns>
+        public static T InstantiateComponentWithRelations<T>(
+            this IObjectResolver resolver,
+            T prefab,
+            Transform parent = null
+        )
+            where T : Component
+        {
+            if (prefab == null)
+            {
+                throw new ArgumentNullException(nameof(prefab));
+            }
+
+            T instance = UnityEngine.Object.Instantiate(prefab, parent);
+            return resolver.BuildUpWithRelations(instance);
+        }
+
+        /// <summary>
+        /// Instantiates a GameObject prefab, injects its hierarchy with VContainer, then assigns
+        /// relational fields for all components beneath the root.
+        /// </summary>
+        /// <param name="resolver">The VContainer object resolver.</param>
+        /// <param name="prefab">GameObject prefab to instantiate.</param>
+        /// <param name="parent">Optional parent transform.</param>
+        /// <param name="includeInactiveChildren">Whether to include inactive children when assigning.</param>
+        /// <returns>The instantiated GameObject.</returns>
+        public static GameObject InstantiateGameObjectWithRelations(
+            this IObjectResolver resolver,
+            GameObject prefab,
+            Transform parent = null,
+            bool includeInactiveChildren = true
+        )
+        {
+            if (prefab == null)
+            {
+                throw new ArgumentNullException(nameof(prefab));
+            }
+
+            GameObject instance = UnityEngine.Object.Instantiate(prefab, parent);
+            resolver.InjectGameObjectWithRelations(instance, includeInactiveChildren);
+            return instance;
+        }
+
+        /// <summary>
+        /// Injects all components on <paramref name="root"/> and its children, then assigns
+        /// relational fields for the hierarchy.
+        /// </summary>
+        /// <param name="resolver">The VContainer object resolver.</param>
+        /// <param name="root">Root GameObject to inject and hydrate.</param>
+        /// <param name="includeInactiveChildren">Whether to include inactive children when assigning.</param>
+        public static void InjectGameObjectWithRelations(
+            this IObjectResolver resolver,
+            GameObject root,
+            bool includeInactiveChildren = true
+        )
+        {
+            if (root == null)
+            {
+                return;
+            }
+
+            resolver?.InjectGameObject(root);
+            resolver.AssignRelationalHierarchy(root, includeInactiveChildren);
+        }
+
         private static bool TryResolveAssigner(
             IObjectResolver resolver,
             out IRelationalComponentAssigner assigner