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

package/Runtime/AssemblyInfo.cs

@@ -5,3 +5,7 @@ using System.Runtime.CompilerServices;
 [assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Editor")]
 [assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Runtime.Zenject")]
 [assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Runtime.VContainer")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Runtime.Reflex")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Editor.VContainer")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Editor.Zenject")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Editor.Reflex")]

package/Runtime/Core/Attributes/NotNullAttribute.cs

@@ -13,9 +13,7 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
         {
 #if UNITY_EDITOR
             IEnumerable<FieldInfo> properties =
-                WallstopStudios.UnityHelpers.Core.Helper.ReflectionHelpers.GetFieldsWithAttribute<NotNullAttribute>(
-                    o.GetType()
-                );
+                Helper.ReflectionHelpers.GetFieldsWithAttribute<NotNullAttribute>(o.GetType());
 
             foreach (FieldInfo field in properties)
             {

package/Runtime/Core/Attributes/RelationalComponentAssigner.cs

@@ -2,6 +2,7 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
 {
     using System;
     using System.Collections.Generic;
+    using System.Linq;
     using Tags;
     using UnityEngine;
     using WallstopStudios.UnityHelpers.Utils;
@@ -39,14 +40,58 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
             AttributeMetadataCache cache = _metadataCache ?? AttributeMetadataCache.Instance;
             if (cache == null)
             {
-                return false;
+                // Fallback to reflection-based discovery when no cache is available
+                return HasRelationalAttributesViaReflection(componentType);
             }
 
-            return cache.TryGetRelationalFields(
-                    componentType,
-                    out AttributeMetadataCache.RelationalFieldMetadata[] fields
+            Type current = componentType;
+            while (current != null && typeof(Component).IsAssignableFrom(current))
+            {
+                if (
+                    cache.TryGetRelationalFields(
+                        current,
+                        out AttributeMetadataCache.RelationalFieldMetadata[] fields
+                    )
+                    && fields.Length > 0
                 )
-                && fields.Length > 0;
+                {
+                    return true;
+                }
+                current = current.BaseType;
+            }
+
+            // Fallback: inspect fields via reflection to detect relational attributes
+            return HasRelationalAttributesViaReflection(componentType);
+        }
+
+        private static bool HasRelationalAttributesViaReflection(Type componentType)
+        {
+            Type current = componentType;
+            while (current != null && typeof(Component).IsAssignableFrom(current))
+            {
+                // Prefer ReflectionHelpers so Editor TypeCache can accelerate lookups
+                bool has =
+                    Helper
+                        .ReflectionHelpers.GetFieldsWithAttribute<ParentComponentAttribute>(current)
+                        .Any()
+                    || Helper
+                        .ReflectionHelpers.GetFieldsWithAttribute<ChildComponentAttribute>(current)
+                        .Any()
+                    || Helper
+                        .ReflectionHelpers.GetFieldsWithAttribute<SiblingComponentAttribute>(
+                            current
+                        )
+                        .Any();
+
+                if (has)
+                {
+                    return true;
+                }
+
+                current = current.BaseType;
+            }
+
+            return false;
         }
 
         /// <inheritdoc />

package/Runtime/Core/DataStructure/CyclicBuffer.cs

@@ -4,7 +4,6 @@ namespace WallstopStudios.UnityHelpers.Core.DataStructure
     using System.Collections;
     using System.Collections.Generic;
     using System.Runtime.CompilerServices;
-    using Extension;
     using Helper;
     using ProtoBuf;
     using UnityEngine;

package/Runtime/Core/DataStructure/KDTree3D.cs

@@ -17,7 +17,7 @@ namespace WallstopStudios.UnityHelpers.Core.DataStructure
     /// <para>Semantics: Due to algorithmic choices (axis-aligned splitting, half-open containment checks,
     /// minimum node-size enforcement, and tie-handling on split planes), KdTree3D (balanced and unbalanced)
     /// may return different edge-case results compared to OctTree3D for identical inputs/queries—especially for
-    /// points lying exactly on query boundaries or split planes. See SPATIAL_TREE_SEMANTICS.md for details.</para>
+    /// points lying exactly on query boundaries or split planes. See Docs/SPATIAL_TREE_SEMANTICS.md for details.</para>
     /// </remarks>
     [Serializable]
     public sealed class KdTree3D<T> : ISpatialTree3D<T>

package/Runtime/Core/DataStructure/OctTree3D.cs

@@ -16,7 +16,7 @@ namespace WallstopStudios.UnityHelpers.Core.DataStructure
     /// <para>Cons: Immutable structure by design; rebuild when positions change frequently.</para>
     /// <para>Semantics: OctTree3D uses octant subdivision and inclusive half-open containment checks with internal
     /// fast-paths when nodes are fully contained. These choices can lead to different results from KdTree3D for points
-    /// on boundaries or when numeric precision interacts with minimum node-size adjustments. See SPATIAL_TREE_SEMANTICS.md.</para>
+    /// on boundaries or when numeric precision interacts with minimum node-size adjustments. See Docs/SPATIAL_TREE_SEMANTICS.md.</para>
     /// </remarks>
     [Serializable]
     public sealed class OctTree3D<T> : ISpatialTree3D<T>

package/Runtime/Core/Extension/AsyncOperationExtensions.cs

@@ -271,6 +271,67 @@ namespace WallstopStudios.UnityHelpers.Core.Extension
             onResult?.Invoke(task.Result);
         }
 
+        /// <summary>
+        /// Converts a Task returning a tuple with two elements to a Unity coroutine (IEnumerator), optionally invoking a callback with the tuple elements.
+        /// </summary>
+        /// <typeparam name="T1">The type of the first tuple element.</typeparam>
+        /// <typeparam name="T2">The type of the second tuple element.</typeparam>
+        /// <param name="task">The task to convert.</param>
+        /// <param name="onResult">Optional callback invoked with the tuple elements. Can be null.</param>
+        /// <returns>An IEnumerator that can be used with StartCoroutine.</returns>
+        /// <remarks>
+        /// <para>Null handling: Task cannot be null. onResult can be null.</para>
+        /// <para>Thread safety: Must be iterated on Unity main thread. No Unity main thread requirement for task execution.</para>
+        /// <para>Performance: Delegates work to the generic Task overload. O(1) per iteration.</para>
+        /// <para>Allocations: Iterator allocation only.</para>
+        /// <para>Edge cases: Returns immediately if task is complete. Propagates task exceptions.</para>
+        /// </remarks>
+        /// <exception cref="Exception">Throws the task's exception if the task is faulted.</exception>
+        public static IEnumerator AsCoroutine<T1, T2>(
+            this Task<(T1 First, T2 Second)> task,
+            Action<T1, T2> onResult = null
+        )
+        {
+            return task.AsCoroutine(tuple =>
+            {
+                if (onResult != null)
+                {
+                    onResult(tuple.First, tuple.Second);
+                }
+            });
+        }
+
+        /// <summary>
+        /// Converts a Task returning a tuple with three elements to a Unity coroutine (IEnumerator), optionally invoking a callback with the tuple elements.
+        /// </summary>
+        /// <typeparam name="T1">The type of the first tuple element.</typeparam>
+        /// <typeparam name="T2">The type of the second tuple element.</typeparam>
+        /// <typeparam name="T3">The type of the third tuple element.</typeparam>
+        /// <param name="task">The task to convert.</param>
+        /// <param name="onResult">Optional callback invoked with the tuple elements. Can be null.</param>
+        /// <returns>An IEnumerator that can be used with StartCoroutine.</returns>
+        /// <remarks>
+        /// <para>Null handling: Task cannot be null. onResult can be null.</para>
+        /// <para>Thread safety: Must be iterated on Unity main thread. No Unity main thread requirement for task execution.</para>
+        /// <para>Performance: Delegates work to the generic Task overload. O(1) per iteration.</para>
+        /// <para>Allocations: Iterator allocation only.</para>
+        /// <para>Edge cases: Returns immediately if task is complete. Propagates task exceptions.</para>
+        /// </remarks>
+        /// <exception cref="Exception">Throws the task's exception if the task is faulted.</exception>
+        public static IEnumerator AsCoroutine<T1, T2, T3>(
+            this Task<(T1 First, T2 Second, T3 Third)> task,
+            Action<T1, T2, T3> onResult = null
+        )
+        {
+            return task.AsCoroutine(tuple =>
+            {
+                if (onResult != null)
+                {
+                    onResult(tuple.First, tuple.Second, tuple.Third);
+                }
+            });
+        }
+
         /// <summary>
         /// Converts a ValueTask to a Unity coroutine (IEnumerator).
         /// </summary>
@@ -348,6 +409,67 @@ namespace WallstopStudios.UnityHelpers.Core.Extension
             onResult?.Invoke(innerTask.Result);
         }
 
+        /// <summary>
+        /// Converts a ValueTask returning a tuple with two elements to a Unity coroutine (IEnumerator), optionally invoking a callback with the tuple elements.
+        /// </summary>
+        /// <typeparam name="T1">The type of the first tuple element.</typeparam>
+        /// <typeparam name="T2">The type of the second tuple element.</typeparam>
+        /// <param name="task">The ValueTask to convert.</param>
+        /// <param name="onResult">Optional callback invoked with the tuple elements. Can be null.</param>
+        /// <returns>An IEnumerator that can be used with StartCoroutine.</returns>
+        /// <remarks>
+        /// <para>Null handling: ValueTask is a value type and cannot be null. onResult can be null.</para>
+        /// <para>Thread safety: Must be iterated on Unity main thread. No Unity main thread requirement for task execution.</para>
+        /// <para>Performance: Delegates work to the generic ValueTask overload. O(1) per iteration.</para>
+        /// <para>Allocations: Iterator allocation only.</para>
+        /// <para>Edge cases: Returns immediately if task is complete. Propagates task exceptions.</para>
+        /// </remarks>
+        /// <exception cref="Exception">Throws the task's exception if the task is faulted.</exception>
+        public static IEnumerator AsCoroutine<T1, T2>(
+            this ValueTask<(T1 First, T2 Second)> task,
+            Action<T1, T2> onResult = null
+        )
+        {
+            return task.AsCoroutine(tuple =>
+            {
+                if (onResult != null)
+                {
+                    onResult(tuple.First, tuple.Second);
+                }
+            });
+        }
+
+        /// <summary>
+        /// Converts a ValueTask returning a tuple with three elements to a Unity coroutine (IEnumerator), optionally invoking a callback with the tuple elements.
+        /// </summary>
+        /// <typeparam name="T1">The type of the first tuple element.</typeparam>
+        /// <typeparam name="T2">The type of the second tuple element.</typeparam>
+        /// <typeparam name="T3">The type of the third tuple element.</typeparam>
+        /// <param name="task">The ValueTask to convert.</param>
+        /// <param name="onResult">Optional callback invoked with the tuple elements. Can be null.</param>
+        /// <returns>An IEnumerator that can be used with StartCoroutine.</returns>
+        /// <remarks>
+        /// <para>Null handling: ValueTask is a value type and cannot be null. onResult can be null.</para>
+        /// <para>Thread safety: Must be iterated on Unity main thread. No Unity main thread requirement for task execution.</para>
+        /// <para>Performance: Delegates work to the generic ValueTask overload. O(1) per iteration.</para>
+        /// <para>Allocations: Iterator allocation only.</para>
+        /// <para>Edge cases: Returns immediately if task is complete. Propagates task exceptions.</para>
+        /// </remarks>
+        /// <exception cref="Exception">Throws the task's exception if the task is faulted.</exception>
+        public static IEnumerator AsCoroutine<T1, T2, T3>(
+            this ValueTask<(T1 First, T2 Second, T3 Third)> task,
+            Action<T1, T2, T3> onResult = null
+        )
+        {
+            return task.AsCoroutine(tuple =>
+            {
+                if (onResult != null)
+                {
+                    onResult(tuple.First, tuple.Second, tuple.Third);
+                }
+            });
+        }
+
         // IEnumerator to Task/ValueTask conversions
         /// <summary>
         /// Converts a Unity coroutine (IEnumerator) to a Task.

package/Runtime/Core/Extension/RandomExtensions.cs

@@ -17,6 +17,74 @@ namespace WallstopStudios.UnityHelpers.Core.Extension
     /// </remarks>
     public static class RandomExtensions
     {
+        /// <summary>
+        /// Returns an index sampled from the provided weights (unnormalized). Negative weights are treated as zero.
+        /// </summary>
+        public static int NextWeightedIndex(this IRandom random, IReadOnlyList<float> weights)
+        {
+            if (weights == null)
+            {
+                throw new ArgumentNullException(nameof(weights));
+            }
+            if (weights.Count == 0)
+            {
+                throw new ArgumentException("Weights cannot be empty", nameof(weights));
+            }
+            double total = 0;
+            for (int i = 0; i < weights.Count; i++)
+            {
+                if (weights[i] > 0)
+                {
+                    total += weights[i];
+                }
+            }
+            if (total <= 0)
+            {
+                throw new ArgumentException("Sum of weights must be > 0", nameof(weights));
+            }
+            double r = random.NextDouble() * total;
+            double acc = 0;
+            for (int i = 0; i < weights.Count; i++)
+            {
+                float w = weights[i];
+                if (w <= 0)
+                {
+                    continue;
+                }
+                acc += w;
+                if (r <= acc)
+                {
+                    return i;
+                }
+            }
+            return weights.Count - 1;
+        }
+
+        /// <summary>
+        /// Returns an element sampled according to the given weights list. Throws if lengths mismatch.
+        /// </summary>
+        public static T NextWeightedElement<T>(
+            this IRandom random,
+            IReadOnlyList<T> items,
+            IReadOnlyList<float> weights
+        )
+        {
+            if (items == null)
+            {
+                throw new ArgumentNullException(nameof(items));
+            }
+            if (weights == null)
+            {
+                throw new ArgumentNullException(nameof(weights));
+            }
+            if (items.Count != weights.Count)
+            {
+                throw new ArgumentException("Items and weights length must match.");
+            }
+            int idx = random.NextWeightedIndex(weights);
+            return items[idx];
+        }
+
         /// <summary>
         /// Generates a random 2D vector with components in the range [-amplitude, amplitude].
         /// </summary>

package/Runtime/Core/Extension/WallstopStudiosLogger.cs

@@ -74,6 +74,22 @@ namespace WallstopStudios.UnityHelpers.Core.Extension
             LoggingEnabled = false;
         }
 
+        /// <summary>
+        /// Gets whether global logging is enabled.
+        /// </summary>
+        public static bool IsGlobalLoggingEnabled()
+        {
+            return LoggingEnabled;
+        }
+
+        /// <summary>
+        /// Sets global logging enabled/disabled without requiring an Object instance.
+        /// </summary>
+        public static void SetGlobalLoggingEnabled(bool enabled)
+        {
+            LoggingEnabled = enabled;
+        }
+
         public static void EnableLogging(this Object component)
         {
             Disabled.Remove(component);

package/Runtime/Core/Helper/Partials/ObjectHelpers.cs

@@ -3,11 +3,14 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
     using System;
     using System.Collections.Generic;
     using Extension;
-    using UnityEditor;
     using UnityEngine;
     using UnityEngine.SceneManagement;
     using WallstopStudios.UnityHelpers.Utils;
     using Object = UnityEngine.Object;
+#if UNITY_EDITOR
+    using UnityEditor;
+#endif
+
 #if UNITY_EDITOR
     using UnityEditor.SceneManagement;
 #endif

package/Runtime/Core/Helper/ReflectionHelpers.cs

@@ -12,7 +12,9 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
     using System.Linq.Expressions;
     using System.Reflection;
     using System.Runtime.CompilerServices;
+#if UNITY_EDITOR
     using UnityEditor;
+#endif
 #if EMIT_DYNAMIC_IL
     using System.Reflection.Emit;
 #endif
@@ -50,10 +52,9 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
     {
         // Cache for type resolution by name
 #if !SINGLE_THREADED
-        private static readonly System.Collections.Concurrent.ConcurrentDictionary<
-            string,
-            Type
-        > TypeResolutionCache = new(StringComparer.Ordinal);
+        private static readonly ConcurrentDictionary<string, Type> TypeResolutionCache = new(
+            StringComparer.Ordinal
+        );
 #else
         private static readonly Dictionary<string, Type> TypeResolutionCache = new(
             StringComparer.Ordinal
@@ -383,6 +384,17 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
             return ListCreators.GetOrAdd(elementType, type => GetListCreator(type)).Invoke();
         }
 
+        // Test helpers to avoid reflection in tests when asserting cache state
+        internal static bool IsFieldGetterCached(FieldInfo field)
+        {
+            return field != null && FieldGetterCache.ContainsKey(field);
+        }
+
+        internal static bool IsFieldSetterCached(FieldInfo field)
+        {
+            return field != null && FieldSetterCache.ContainsKey(field);
+        }
+
         /// <summary>
         /// Builds a cached delegate that returns the value of a field as <see cref="object"/>.
         /// Supports instance and static fields.
@@ -3713,7 +3725,7 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
 #if UNITY_EDITOR
             try
             {
-                TypeCache.TypeCollection list = UnityEditor.TypeCache.GetTypesDerivedFrom<T>();
+                TypeCache.TypeCollection list = TypeCache.GetTypesDerivedFrom<T>();
                 return list.Where(t =>
                     t != null && (includeAbstract || (t.IsClass && !t.IsAbstract))
                 );
@@ -3747,7 +3759,7 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
 #if UNITY_EDITOR
             try
             {
-                TypeCache.TypeCollection list = UnityEditor.TypeCache.GetTypesDerivedFrom(baseType);
+                TypeCache.TypeCollection list = TypeCache.GetTypesDerivedFrom(baseType);
                 return list.Where(t =>
                     t != null && (includeAbstract || (t.IsClass && !t.IsAbstract))
                 );
@@ -3799,8 +3811,7 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
 #if UNITY_EDITOR
             try
             {
-                TypeCache.TypeCollection types =
-                    UnityEditor.TypeCache.GetTypesWithAttribute<TAttribute>();
+                TypeCache.TypeCollection types = TypeCache.GetTypesWithAttribute<TAttribute>();
                 return types.Where(t =>
                     t != null && (includeAbstract || (t.IsClass && !t.IsAbstract))
                 );
@@ -3855,7 +3866,7 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
             try
             {
                 TypeCache.MethodCollection methods =
-                    UnityEditor.TypeCache.GetMethodsWithAttribute<TAttribute>();
+                    TypeCache.GetMethodsWithAttribute<TAttribute>();
                 IEnumerable<MethodInfo> filtered = methods;
                 if (within != null)
                 {
@@ -3892,7 +3903,7 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
             try
             {
                 TypeCache.FieldInfoCollection fields =
-                    UnityEditor.TypeCache.GetFieldsWithAttribute<TAttribute>();
+                    TypeCache.GetFieldsWithAttribute<TAttribute>();
                 IEnumerable<FieldInfo> filtered = fields;
                 if (within != null)
                 {

package/Runtime/Core/Helper/SpriteHelpers.cs

@@ -1,8 +1,10 @@
 namespace WallstopStudios.UnityHelpers.Core.Helper
 {
     using Extension;
-    using UnityEditor;
     using UnityEngine;
+#if UNITY_EDITOR
+    using UnityEditor;
+#endif
 
     /// <summary>
     /// Sprite and texture utilities for editor workflows.

package/Runtime/Core/Helper/UnityMainThreadDispatcher.cs

@@ -2,9 +2,11 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
 {
     using System;
     using System.Collections.Concurrent;
-    using UnityEditor;
     using UnityEngine;
     using Utils;
+#if UNITY_EDITOR
+    using UnityEditor;
+#endif
 
     /// <summary>
     /// Thread-safe dispatcher that enqueues work to run on Unity's main thread.
@@ -96,5 +98,47 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
                 }
             }
         }
+
+        /// <summary>
+        /// Posts an action to run on the main thread and returns a Task that completes after execution.
+        /// </summary>
+        public System.Threading.Tasks.Task RunAsync(Action action)
+        {
+            var tcs = new System.Threading.Tasks.TaskCompletionSource<bool>();
+            RunOnMainThread(() =>
+            {
+                try
+                {
+                    action();
+                    tcs.SetResult(true);
+                }
+                catch (Exception ex)
+                {
+                    tcs.SetException(ex);
+                }
+            });
+            return tcs.Task;
+        }
+
+        /// <summary>
+        /// Posts a function to run on the main thread and returns its result via Task.
+        /// </summary>
+        public System.Threading.Tasks.Task<T> Post<T>(Func<T> func)
+        {
+            var tcs = new System.Threading.Tasks.TaskCompletionSource<T>();
+            RunOnMainThread(() =>
+            {
+                try
+                {
+                    T result = func();
+                    tcs.SetResult(result);
+                }
+                catch (Exception ex)
+                {
+                    tcs.SetException(ex);
+                }
+            });
+            return tcs.Task;
+        }
     }
 }

package/Runtime/Core/Serialization/JsonConverters/GameObjectConverter.cs

@@ -26,11 +26,19 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization.JsonConverters
             JsonSerializerOptions options
         )
         {
-            writer.WriteStringValue(
-                value == null
-                    ? "{}"
-                    : new { name = value.name, type = value.GetType().FullName }.ToString()
-            );
+            if (value == null)
+            {
+                writer.WriteNullValue();
+                return;
+            }
+
+            writer.WriteStartObject();
+            writer.WriteString("name", value.name);
+            // Use AssemblyQualifiedName to disambiguate type for diagnostics
+            writer.WriteString("type", value.GetType().AssemblyQualifiedName);
+            // Emit the actual Unity instance ID without transformation for correctness.
+            writer.WriteNumber("instanceId", value.GetInstanceID());
+            writer.WriteEndObject();
         }
     }
 }

package/Runtime/Core/Serialization/JsonConverters/ResolutionConverter.cs

@@ -141,7 +141,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization.JsonConverters
 #if UNITY_2022_2_OR_NEWER
             uint num = value.refreshRateRatio.numerator;
             uint den = value.refreshRateRatio.denominator;
-            int hz = den != 0 ? (int)System.Math.Round((double)num / den) : 0;
+            int hz = den != 0 ? (int)Math.Round((double)num / den) : 0;
             writer.WriteNumber(RefreshRateProp, hz);
             writer.WritePropertyName(RefreshRatioProp);
             writer.WriteStartObject();

package/Runtime/Core/Serialization/JsonConverters/TypeConverter.cs

@@ -19,7 +19,7 @@ namespace WallstopStudios.UnityHelpers.Core.Serialization.JsonConverters
             string typeName = reader.GetString();
             return string.IsNullOrWhiteSpace(typeName)
                 ? null
-                : Core.Helper.ReflectionHelpers.TryResolveType(typeName);
+                : Helper.ReflectionHelpers.TryResolveType(typeName);
         }
 
         public override void Write(Utf8JsonWriter writer, Type value, JsonSerializerOptions options)