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

package/Runtime/Core/Serialization/Serializer.cs

@@ -277,6 +277,10 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         None = 0,
 
         /// <summary>Legacy .NET BinaryFormatter. Trusted/ephemeral data only.</summary>
+        [Obsolete(
+            "BinaryFormatter is obsolete and unsafe for untrusted data. "
+                + "Prefer Json or Protobuf for new code."
+        )]
         SystemBinary = 1,
 
         /// <summary>protobuf-net compact binary. Best for networking and high-performance.</summary>
@@ -608,7 +612,9 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         {
             switch (serializationType)
             {
+#pragma warning disable CS0618 // Type or member is obsolete
                 case SerializationType.SystemBinary:
+#pragma warning restore CS0618 // Type or member is obsolete
                 {
                     return BinaryDeserialize<T>(serialized);
                 }
@@ -650,7 +656,9 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         {
             switch (serializationType)
             {
+#pragma warning disable CS0618 // Type or member is obsolete
                 case SerializationType.SystemBinary:
+#pragma warning restore CS0618 // Type or member is obsolete
                 {
                     return BinarySerialize(instance);
                 }
@@ -689,7 +697,9 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         {
             switch (serializationType)
             {
+#pragma warning disable CS0618 // Type or member is obsolete
                 case SerializationType.SystemBinary:
+#pragma warning restore CS0618 // Type or member is obsolete
                 {
                     return BinarySerialize(instance, ref buffer);
                 }
@@ -1494,6 +1504,35 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
             return JsonDeserialize<T>(settingsAsBytes);
         }
 
+        /// <summary>
+        /// Asynchronously reads JSON with cancellation.
+        /// </summary>
+        public static async Task<T> ReadFromJsonFileAsync<T>(
+            string path,
+            System.Threading.CancellationToken cancellationToken
+        )
+        {
+            using FileStream fs = new(
+                path,
+                FileMode.Open,
+                FileAccess.Read,
+                FileShare.Read,
+                4096,
+                useAsync: true
+            );
+            using Utils.PooledResource<PooledBufferStream> lease = PooledBufferStream.Rent(
+                out PooledBufferStream stream
+            );
+            byte[] buffer = new byte[8192];
+            int read;
+            while ((read = await fs.ReadAsync(buffer, 0, buffer.Length, cancellationToken)) > 0)
+            {
+                stream.Write(buffer, 0, read);
+            }
+            ArraySegment<byte> seg = stream.GetWrittenSegment();
+            return JsonDeserialize<T>(seg.Array.AsSpan(0, seg.Count).ToArray());
+        }
+
         /// <summary>
         /// Writes an instance to a JSON file (UTF‑8).
         /// </summary>
@@ -1520,6 +1559,29 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
             await File.WriteAllTextAsync(path, jsonAsText);
         }
 
+        /// <summary>
+        /// Asynchronously writes an instance to a JSON file (UTF‑8) with cancellation.
+        /// </summary>
+        public static async Task WriteToJsonFileAsync<T>(
+            T input,
+            string path,
+            bool pretty,
+            System.Threading.CancellationToken cancellationToken
+        )
+        {
+            string jsonAsText = JsonStringify(input, pretty);
+            byte[] bytes = SerializerEncoding.Encoding.GetBytes(jsonAsText);
+            using FileStream fs = new(
+                path,
+                FileMode.Create,
+                FileAccess.Write,
+                FileShare.None,
+                4096,
+                useAsync: true
+            );
+            await fs.WriteAsync(bytes, 0, bytes.Length, cancellationToken);
+        }
+
         /// <summary>
         /// Writes an instance to a JSON file (UTF‑8) using the provided <paramref name="options"/>.
         /// </summary>
@@ -1549,6 +1611,45 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
             string jsonAsText = JsonStringify(input, options);
             await File.WriteAllTextAsync(path, jsonAsText);
         }
+
+        /// <summary>
+        /// Attempts to read JSON into an instance, returns false if file missing or invalid.
+        /// </summary>
+        public static bool TryReadFromJsonFile<T>(string path, out T value)
+        {
+            try
+            {
+                if (!File.Exists(path))
+                {
+                    value = default;
+                    return false;
+                }
+                string json = File.ReadAllText(path);
+                value = JsonDeserialize<T>(json);
+                return true;
+            }
+            catch
+            {
+                value = default;
+                return false;
+            }
+        }
+
+        /// <summary>
+        /// Attempts to write JSON to a file, returns false on failure.
+        /// </summary>
+        public static bool TryWriteToJsonFile<T>(T input, string path, bool pretty = true)
+        {
+            try
+            {
+                WriteToJsonFile(input, path, pretty);
+                return true;
+            }
+            catch
+            {
+                return false;
+            }
+        }
     }
 
     // Internal pooled, growable write stream backed by ArrayPool<byte> to reduce allocations

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

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>