com.wallstop-studios.unity-helpers 2.0.0 → 2.0.2

package/Runtime/Integrations/Reflex/RelationalComponentsInstaller.cs

@@ -0,0 +1,86 @@
+#if REFLEX_PRESENT
+namespace WallstopStudios.UnityHelpers.Integrations.Reflex
+{
+    using global::Reflex.Core;
+    using UnityEngine;
+    using UnityEngine.SceneManagement;
+    using WallstopStudios.UnityHelpers.Core.Attributes;
+    using WallstopStudios.UnityHelpers.Tags;
+
+    /// <summary>
+    /// Reflex installer that binds relational component services and optionally hydrates scenes.
+    /// </summary>
+    [AddComponentMenu("Wallstop Studios/Relational Components/Reflex Installer")]
+    public sealed class RelationalComponentsInstaller : MonoBehaviour, IInstaller
+    {
+        [SerializeField]
+        [Tooltip(
+            "When enabled, relational fields within the scene are assigned immediately after the container is built."
+        )]
+        private bool _assignSceneOnInitialize = true;
+
+        [SerializeField]
+        [Tooltip("Include inactive GameObjects when scanning for relational assignments.")]
+        private bool _includeInactiveObjects = true;
+
+        [SerializeField]
+        [Tooltip(
+            "Registers an additive scene listener that hydrates relational fields for scenes loaded additively."
+        )]
+        private bool _listenForAdditiveScenes = true;
+
+        [SerializeField]
+        [Tooltip(
+            "Use a single-pass scan when assigning relational fields for improved performance."
+        )]
+        private bool _useSinglePassScan = true;
+
+        /// <inheritdoc />
+        public void InstallBindings(ContainerBuilder builder)
+        {
+            AttributeMetadataCache cacheInstance = AttributeMetadataCache.Instance;
+            if (cacheInstance != null && !builder.HasBinding(typeof(AttributeMetadataCache)))
+            {
+                builder.AddSingleton(cacheInstance, typeof(AttributeMetadataCache));
+            }
+
+            if (!builder.HasBinding(typeof(IRelationalComponentAssigner)))
+            {
+                builder.AddSingleton(
+                    typeof(RelationalComponentAssigner),
+                    typeof(IRelationalComponentAssigner),
+                    typeof(RelationalComponentAssigner)
+                );
+            }
+
+            RelationalSceneAssignmentOptions options = new(
+                _includeInactiveObjects,
+                _useSinglePassScan
+            );
+            if (!builder.HasBinding(typeof(RelationalSceneAssignmentOptions)))
+            {
+                builder.AddSingleton(options);
+            }
+
+            Scene installerScene = gameObject.scene;
+
+            builder.OnContainerBuilt += container =>
+            {
+                RelationalSceneAssignmentOptions assignmentOptions = options;
+                if (container.HasBinding<RelationalSceneAssignmentOptions>())
+                {
+                    assignmentOptions = container.Resolve<RelationalSceneAssignmentOptions>();
+                }
+
+                RelationalReflexSceneBootstrapper.ConfigureScene(
+                    container,
+                    installerScene,
+                    assignmentOptions,
+                    _assignSceneOnInitialize,
+                    _listenForAdditiveScenes
+                );
+            };
+        }
+    }
+}
+#endif

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

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

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/Utils/ScriptableObjectSingleton.cs

@@ -24,7 +24,7 @@ namespace WallstopStudios.UnityHelpers.Utils
     ///
     /// If multiple assets are found, a warning is logged and the first result ordered by name is returned.
     /// The editor utility “ScriptableObject Singleton Creator” automatically creates and relocates assets to
-    /// the correct path on editor load — see EDITOR_TOOLS_GUIDE.md#scriptableobject-singleton-creator.
+    /// the correct path on editor load — see Docs/EDITOR_TOOLS_GUIDE.md#scriptableobject-singleton-creator.
     ///
     /// ODIN compatibility: When the <c>ODIN_INSPECTOR</c> symbol is defined, this class derives from
     /// <c>Sirenix.OdinInspector.SerializedScriptableObject</c>; otherwise it derives from <see cref="ScriptableObject"/>.