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

package/Runtime/Core/Serialization/ProtobufUnitySurrogates.cs

@@ -15,10 +15,9 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         [ProtoMember(2)]
         public float y;
 
-        public static implicit operator Vector2Surrogate(Vector2 v) =>
-            new Vector2Surrogate { x = v.x, y = v.y };
+        public static implicit operator Vector2Surrogate(Vector2 v) => new() { x = v.x, y = v.y };
 
-        public static implicit operator Vector2(Vector2Surrogate s) => new Vector2(s.x, s.y);
+        public static implicit operator Vector2(Vector2Surrogate s) => new(s.x, s.y);
     }
 
     [ProtoContract]
@@ -34,14 +33,14 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         public float z;
 
         public static implicit operator Vector3Surrogate(Vector3 v) =>
-            new Vector3Surrogate
+            new()
             {
                 x = v.x,
                 y = v.y,
                 z = v.z,
             };
 
-        public static implicit operator Vector3(Vector3Surrogate s) => new Vector3(s.x, s.y, s.z);
+        public static implicit operator Vector3(Vector3Surrogate s) => new(s.x, s.y, s.z);
     }
 
     [ProtoContract]
@@ -60,7 +59,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         public float w;
 
         public static implicit operator QuaternionSurrogate(Quaternion q) =>
-            new QuaternionSurrogate
+            new()
             {
                 x = q.x,
                 y = q.y,
@@ -69,7 +68,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
             };
 
         public static implicit operator Quaternion(QuaternionSurrogate s) =>
-            new Quaternion(s.x, s.y, s.z, s.w);
+            new(s.x, s.y, s.z, s.w);
     }
 
     [ProtoContract]
@@ -88,7 +87,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         public float a;
 
         public static implicit operator ColorSurrogate(Color c) =>
-            new ColorSurrogate
+            new()
             {
                 r = c.r,
                 g = c.g,
@@ -96,7 +95,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
                 a = c.a,
             };
 
-        public static implicit operator Color(ColorSurrogate s) => new Color(s.r, s.g, s.b, s.a);
+        public static implicit operator Color(ColorSurrogate s) => new(s.r, s.g, s.b, s.a);
     }
 
     [ProtoContract]
@@ -115,7 +114,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         public byte a;
 
         public static implicit operator Color32Surrogate(Color32 c) =>
-            new Color32Surrogate
+            new()
             {
                 r = c.r,
                 g = c.g,
@@ -123,8 +122,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
                 a = c.a,
             };
 
-        public static implicit operator Color32(Color32Surrogate s) =>
-            new Color32(s.r, s.g, s.b, s.a);
+        public static implicit operator Color32(Color32Surrogate s) => new(s.r, s.g, s.b, s.a);
     }
 
     [ProtoContract]
@@ -143,7 +141,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         public float height;
 
         public static implicit operator RectSurrogate(Rect r) =>
-            new RectSurrogate
+            new()
             {
                 x = r.x,
                 y = r.y,
@@ -151,8 +149,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
                 height = r.height,
             };
 
-        public static implicit operator Rect(RectSurrogate s) =>
-            new Rect(s.x, s.y, s.width, s.height);
+        public static implicit operator Rect(RectSurrogate s) => new(s.x, s.y, s.width, s.height);
     }
 
     [ProtoContract]
@@ -171,7 +168,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         public int height;
 
         public static implicit operator RectIntSurrogate(RectInt r) =>
-            new RectIntSurrogate
+            new()
             {
                 x = r.x,
                 y = r.y,
@@ -180,7 +177,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
             };
 
         public static implicit operator RectInt(RectIntSurrogate s) =>
-            new RectInt(s.x, s.y, s.width, s.height);
+            new(s.x, s.y, s.width, s.height);
     }
 
     [ProtoContract]
@@ -205,7 +202,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         public float sz;
 
         public static implicit operator BoundsSurrogate(Bounds b) =>
-            new BoundsSurrogate
+            new()
             {
                 cx = b.center.x,
                 cy = b.center.y,
@@ -216,7 +213,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
             };
 
         public static implicit operator Bounds(BoundsSurrogate s) =>
-            new Bounds(new Vector3(s.cx, s.cy, s.cz), new Vector3(s.sx, s.sy, s.sz));
+            new(new Vector3(s.cx, s.cy, s.cz), new Vector3(s.sx, s.sy, s.sz));
     }
 
     [ProtoContract]
@@ -241,7 +238,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         public int sz;
 
         public static implicit operator BoundsIntSurrogate(BoundsInt b) =>
-            new BoundsIntSurrogate
+            new()
             {
                 px = b.position.x,
                 py = b.position.y,
@@ -252,7 +249,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
             };
 
         public static implicit operator BoundsInt(BoundsIntSurrogate s) =>
-            new BoundsInt(new Vector3Int(s.px, s.py, s.pz), new Vector3Int(s.sx, s.sy, s.sz));
+            new(new Vector3Int(s.px, s.py, s.pz), new Vector3Int(s.sx, s.sy, s.sz));
     }
 
     [ProtoContract]
@@ -265,10 +262,9 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         public int y;
 
         public static implicit operator Vector2IntSurrogate(Vector2Int v) =>
-            new Vector2IntSurrogate { x = v.x, y = v.y };
+            new() { x = v.x, y = v.y };
 
-        public static implicit operator Vector2Int(Vector2IntSurrogate s) =>
-            new Vector2Int(s.x, s.y);
+        public static implicit operator Vector2Int(Vector2IntSurrogate s) => new(s.x, s.y);
     }
 
     [ProtoContract]
@@ -284,15 +280,14 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
         public int z;
 
         public static implicit operator Vector3IntSurrogate(Vector3Int v) =>
-            new Vector3IntSurrogate
+            new()
             {
                 x = v.x,
                 y = v.y,
                 z = v.z,
             };
 
-        public static implicit operator Vector3Int(Vector3IntSurrogate s) =>
-            new Vector3Int(s.x, s.y, s.z);
+        public static implicit operator Vector3Int(Vector3IntSurrogate s) => new(s.x, s.y, s.z);
     }
 
     [ProtoContract]
@@ -309,7 +304,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
 
         [Obsolete("Obsolete")]
         public static implicit operator ResolutionSurrogate(Resolution r) =>
-            new ResolutionSurrogate
+            new()
             {
                 width = r.width,
                 height = r.height,
@@ -318,7 +313,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization
 
         public static implicit operator Resolution(ResolutionSurrogate s)
         {
-            Resolution r = new Resolution { width = s.width, height = s.height };
+            Resolution r = new() { width = s.width, height = s.height };
 #if !UNITY_2022_2_OR_NEWER
             r.refreshRate = s.refreshRate;
 #endif

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/Reflex/AssemblyInfo.cs

@@ -0,0 +1,7 @@
+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.Reflex")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Editor.Reflex")]

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

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

package/Runtime/Integrations/Reflex/ContainerRelationalExtensions.cs

@@ -0,0 +1,198 @@
+#if REFLEX_PRESENT
+namespace WallstopStudios.UnityHelpers.Integrations.Reflex
+{
+    using System;
+    using System.Collections.Generic;
+    using global::Reflex.Core;
+    using global::Reflex.Injectors;
+    using UnityEngine;
+    using WallstopStudios.UnityHelpers.Core.Attributes;
+    using WallstopStudios.UnityHelpers.Utils;
+
+    /// <summary>
+    /// Extension methods that bridge Reflex containers with relational component assignment.
+    /// </summary>
+    public static class ContainerRelationalExtensions
+    {
+        /// <summary>
+        /// Injects a component using Reflex and assigns its relational fields.
+        /// </summary>
+        /// <typeparam name="T">Component type.</typeparam>
+        /// <param name="container">Reflex container.</param>
+        /// <param name="component">Component instance to inject and hydrate.</param>
+        /// <returns>The injected component instance.</returns>
+        public static T InjectWithRelations<T>(this Container container, T component)
+            where T : Component
+        {
+            if (component == null)
+            {
+                return null;
+            }
+
+            if (container != null)
+            {
+                AttributeInjector.Inject(component, container);
+            }
+
+            container.AssignRelationalComponents(component);
+            return component;
+        }
+
+        /// <summary>
+        /// Assigns relational component fields on the supplied component.
+        /// </summary>
+        /// <param name="container">Reflex container.</param>
+        /// <param name="component">Component to hydrate.</param>
+        public static void AssignRelationalComponents(this Container container, Component component)
+        {
+            if (component == null)
+            {
+                return;
+            }
+
+            IRelationalComponentAssigner assigner = ResolveAssigner(container);
+            if (assigner != null)
+            {
+                assigner.Assign(component);
+                return;
+            }
+
+            component.AssignRelationalComponents();
+        }
+
+        /// <summary>
+        /// Assigns relational component fields across a GameObject hierarchy.
+        /// </summary>
+        /// <param name="container">Reflex container.</param>
+        /// <param name="root">Hierarchy root.</param>
+        /// <param name="includeInactiveChildren">
+        /// When true, includes inactive children during assignment.
+        /// </param>
+        public static void AssignRelationalHierarchy(
+            this Container container,
+            GameObject root,
+            bool includeInactiveChildren = true
+        )
+        {
+            if (root == null)
+            {
+                return;
+            }
+
+            IRelationalComponentAssigner assigner = ResolveAssigner(container);
+            if (assigner != null)
+            {
+                assigner.AssignHierarchy(root, includeInactiveChildren);
+                return;
+            }
+
+            using PooledResource<List<Component>> pooledComponents = Buffers<Component>.List.Get(
+                out List<Component> components
+            );
+            root.GetComponentsInChildren(includeInactiveChildren, components);
+            for (int i = 0; i < components.Count; i++)
+            {
+                Component component = components[i];
+                if (component == null)
+                {
+                    continue;
+                }
+                component.AssignRelationalComponents();
+            }
+        }
+
+        /// <summary>
+        /// Instantiates a component prefab, injects it, and assigns relational fields.
+        /// </summary>
+        /// <typeparam name="T">Component type contained by the prefab.</typeparam>
+        /// <param name="container">Reflex container.</param>
+        /// <param name="prefab">Component prefab.</param>
+        /// <param name="parent">Optional parent transform.</param>
+        /// <returns>The instantiated and hydrated component.</returns>
+        public static T InstantiateComponentWithRelations<T>(
+            this Container container,
+            T prefab,
+            Transform parent = null
+        )
+            where T : Component
+        {
+            if (prefab == null)
+            {
+                throw new ArgumentNullException(nameof(prefab));
+            }
+
+            T instance = UnityEngine.Object.Instantiate(prefab, parent);
+            return container.InjectWithRelations(instance);
+        }
+
+        /// <summary>
+        /// Instantiates a GameObject prefab, injects the hierarchy, and assigns relational fields.
+        /// </summary>
+        /// <param name="container">Reflex container.</param>
+        /// <param name="prefab">GameObject prefab.</param>
+        /// <param name="parent">Optional parent transform.</param>
+        /// <param name="includeInactiveChildren">
+        /// When true, includes inactive children during relational assignment.
+        /// </param>
+        /// <returns>The instantiated GameObject.</returns>
+        public static GameObject InstantiateGameObjectWithRelations(
+            this Container container,
+            GameObject prefab,
+            Transform parent = null,
+            bool includeInactiveChildren = true
+        )
+        {
+            if (prefab == null)
+            {
+                throw new ArgumentNullException(nameof(prefab));
+            }
+
+            GameObject instance = UnityEngine.Object.Instantiate(prefab, parent);
+            container.InjectGameObjectWithRelations(instance, includeInactiveChildren);
+            return instance;
+        }
+
+        /// <summary>
+        /// Injects all components in a hierarchy and assigns relational fields.
+        /// </summary>
+        /// <param name="container">Reflex container.</param>
+        /// <param name="root">Root GameObject.</param>
+        /// <param name="includeInactiveChildren">
+        /// When true, includes inactive children during relational assignment.
+        /// </param>
+        public static void InjectGameObjectWithRelations(
+            this Container container,
+            GameObject root,
+            bool includeInactiveChildren = true
+        )
+        {
+            if (root == null)
+            {
+                return;
+            }
+
+            if (container != null)
+            {
+                GameObjectInjector.InjectRecursive(root, container);
+            }
+
+            container.AssignRelationalHierarchy(root, includeInactiveChildren);
+        }
+
+        private static IRelationalComponentAssigner ResolveAssigner(Container container)
+        {
+            if (container == null)
+            {
+                return null;
+            }
+
+            if (container.HasBinding<IRelationalComponentAssigner>())
+            {
+                return container.Resolve<IRelationalComponentAssigner>();
+            }
+
+            return null;
+        }
+    }
+}
+#endif

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

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

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: