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

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}."
                     );

package/Runtime/Utils/Buffers.cs

@@ -1113,21 +1113,21 @@ namespace WallstopStudios.UnityHelpers.Utils
     /// This struct implements IDisposable to enable automatic resource return via 'using' statements.
     /// The resource is returned to its pool when Dispose is called, typically at the end of a 'using' block.
     /// </remarks>
-    public readonly struct PooledResource<T> : IDisposable
+    public struct PooledResource<T> : IDisposable
     {
         /// <summary>
         /// The pooled resource instance. Access this to use the resource.
         /// </summary>
         public readonly T resource;
         private readonly Action<T> _onDispose;
-        private readonly bool _initialized;
+        private bool _initialized;
 
         /// <summary>
         /// Creates a new PooledResource wrapping the specified resource with a disposal action.
         /// </summary>
         /// <param name="resource">The resource to wrap.</param>
         /// <param name="onDispose">The action to invoke when disposing, typically returning the resource to a pool.</param>
-        internal PooledResource(T resource, Action<T> onDispose)
+        public PooledResource(T resource, Action<T> onDispose)
         {
             _initialized = true;
             this.resource = resource;
@@ -1144,7 +1144,7 @@ namespace WallstopStudios.UnityHelpers.Utils
             {
                 return;
             }
-
+            _initialized = false;
             _onDispose(resource);
         }
     }

package/Runtime/Utils/ScriptableObjectSingleton.cs

@@ -1,7 +1,6 @@
 namespace WallstopStudios.UnityHelpers.Utils
 {
     using System;
-    using System.Linq;
     using UnityEngine;
     using WallstopStudios.UnityHelpers.Core.Attributes;
     using WallstopStudios.UnityHelpers.Core.Helper;

package/Runtime/Utils/SetTextureImportData.cs

@@ -1,7 +1,9 @@
 namespace WallstopStudios.UnityHelpers.Utils
 {
-    using UnityEditor;
     using UnityEngine;
+#if UNITY_EDITOR
+    using UnityEditor;
+#endif
 
     public static class SetTextureImportData
     {

package/Runtime/Utils/TextureScale.cs

@@ -36,10 +36,14 @@ namespace WallstopStudios.UnityHelpers.Utils
         /// This method modifies the texture in-place. Point sampling provides fast, sharp scaling
         /// but may produce pixelated results. Use Bilinear for smoother results.
         /// </remarks>
-        public static void Point(Texture2D tex, int newWidth, int newHeight)
+        public static void Point(Texture2D tex, int newWidth, int newHeight, bool apply = false)
         {
             ValidateInputs(tex, newWidth, newHeight);
             ThreadedScale(tex, newWidth, newHeight, false);
+            if (apply)
+            {
+                tex.Apply(updateMipmaps: false, makeNoLongerReadable: false);
+            }
         }
 
         /// <summary>
@@ -55,10 +59,14 @@ namespace WallstopStudios.UnityHelpers.Utils
         /// This method modifies the texture in-place. Bilinear interpolation provides smooth scaling
         /// with better visual quality than point sampling, at a slight performance cost.
         /// </remarks>
-        public static void Bilinear(Texture2D tex, int newWidth, int newHeight)
+        public static void Bilinear(Texture2D tex, int newWidth, int newHeight, bool apply = false)
         {
             ValidateInputs(tex, newWidth, newHeight);
             ThreadedScale(tex, newWidth, newHeight, true);
+            if (apply)
+            {
+                tex.Apply(updateMipmaps: false, makeNoLongerReadable: false);
+            }
         }
 
         private static void ValidateInputs(Texture2D tex, int newWidth, int newHeight)

package/Runtime/Visuals/UGUI/EnhancedImage.cs

@@ -70,6 +70,7 @@ namespace WallstopStudios.UnityHelpers.Visuals.UGUI
         /// Stores the dedicated material instance produced by <see cref="UpdateMaterialInstance"/>.
         /// </summary>
         private Material _cachedMaterialInstance;
+        internal Material CachedMaterialInstanceForTests => _cachedMaterialInstance;
 
         /// <summary>
         /// HDR-capable tint applied to the instantiated material. Values above 1 keep their intensity instead of being clamped.
@@ -214,5 +215,10 @@ namespace WallstopStudios.UnityHelpers.Visuals.UGUI
                 _cachedMaterialInstance = null;
             }
         }
+
+        // Test helpers to avoid reflection
+        internal void InvokeStartForTests() => Start();
+
+        internal void InvokeOnDestroyForTests() => OnDestroy();
     }
 }

package/Runtime/Visuals/UIToolkit/LayeredImage.cs

@@ -6,11 +6,13 @@ namespace WallstopStudios.UnityHelpers.Visuals.UIToolkit
     using System.Linq;
     using System.Runtime.CompilerServices;
     using System.Threading.Tasks;
-    using UnityEditor;
     using UnityEngine;
     using UnityEngine.UIElements;
     using WallstopStudios.UnityHelpers.Core.Helper;
     using WallstopStudios.UnityHelpers.Utils;
+#if UNITY_EDITOR
+    using UnityEditor;
+#endif
 
     public sealed class LayeredImage : VisualElement
     {
@@ -68,6 +70,7 @@ namespace WallstopStudios.UnityHelpers.Visuals.UIToolkit
 
         private readonly AnimatedSpriteLayer[] _layers;
         private readonly Texture2D[] _computed;
+        internal Texture2D[] ComputedTexturesForTests => _computed;
         private readonly Color _backgroundColor;
         private readonly Rect? _largestArea;
         private readonly Stopwatch _timer;

package/SERIALIZATION.md

@@ -646,3 +646,18 @@ References
 - Replace direct `System.Text.Json.JsonSerializer` calls in app code with `Serializer.JsonSerialize/JsonDeserialize/JsonStringify`, or with `Serializer.Serialize/Deserialize` + `SerializationType.Json` to centralize options and Unity converters.
 - Replace any custom protobuf helpers with `Serializer.ProtoSerialize/ProtoDeserialize` or the generic `Serializer.Serialize/Deserialize` APIs. Ensure models are annotated with `[ProtoContract]` and stable `[ProtoMember(n)]` tags.
 - For existing binary saves using BinaryFormatter, prefer migrating to Json or Protobuf. If you must keep BinaryFormatter, scope it to trusted, same-version caches only.
+
+## 2.0 changes
+
+- BinaryFormatter (`SerializationType.SystemBinary`) is deprecated but remains functional for trusted/legacy scenarios. Prefer:
+  - `SerializationType.Json` (System.Text.Json with Unity-aware converters) for readable, diffable content.
+  - `SerializationType.Protobuf` (protobuf-net) for compact, high-performance binary payloads.
+
+## IL2CPP / AOT guidance
+
+System.Text.Json can require extra care under AOT (e.g., IL2CPP):
+
+- Prefer explicit `JsonSerializerOptions` and concrete generic APIs over `object`-based serialization to reduce reflection.
+- For hot POCO models, consider adding a source-generated context (JsonSerializerContext) in your game assembly and pass it to `JsonSerializer` calls.
+- If you rely on many custom converters, ensure they are referenced by code so the linker doesn't strip them. The UnityHelpers converters are referenced via options by default.
+- Avoid deserializing `System.Type` from untrusted input (see `TypeConverter`); this is intended for trusted configs/tools.