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

package/RELATIONAL_COMPONENTS.md

@@ -314,114 +314,102 @@ Notes:
 
 ## Dependency Injection Integrations
 
-Unity Helpers provides optional integration assemblies that only compile when Zenject or VContainer is present in your project. Install the corresponding DI package via the Unity Package Manager and the helpers become available automatically (no additional scripting defines required).
+**Stop choosing between DI and clean hierarchy references** - Unity Helpers provides seamless integrations with Zenject and VContainer that automatically wire up your relational component fields right after dependency injection completes.
 
-Why use the DI integrations
+### The DI Pain Point
 
-- Eliminate boilerplate: hydrate relational fields after DI injection automatically.
-- Consistent behavior: integrates with constructor/property injection and works with runtime instantiation.
-- Safe fallback: if the DI binding is missing, falls back to the non-DI path so fields still populate.
+Without these integrations, you're stuck writing `Awake()` methods full of `GetComponent` boilerplate **even when using a DI framework**:
 
-Supported package IDs (auto-detected)
-
-- Zenject/Extenject: `com.extenject.zenject`, `com.modesttree.zenject`, `com.svermeulen.extenject`
-- VContainer: `jp.cysharp.vcontainer`, `jp.hadashikick.vcontainer`
+```csharp
+public class Enemy : MonoBehaviour
+{
+    [Inject] private IHealthSystem _health;  // ✅ DI handles this
 
-Manual or source imports (no UPM)
+    private Animator _animator;               // ❌ Still manual boilerplate
+    private Rigidbody2D _rigidbody;          // ❌ Still manual boilerplate
 
-- If you import Zenject/VContainer as source, a .unitypackage, or a plain DLL, Unity cannot infer package IDs and the `versionDefines` in the asmdefs won’t trigger.
-- Add scripting defines in Project Settings to enable the integrations:
-  - `Project Settings > Player > Other Settings > Scripting Define Symbols`
-  - Add `ZENJECT_PRESENT` when Zenject/Extenject is present and/or `VCONTAINER_PRESENT` when VContainer is present.
-  - Set defines per target platform (Standalone, Android, iOS, etc.).
-  - After adding, Unity recompiles and the optional assemblies under `Runtime/Integrations/*` compile automatically.
+    void Awake()
+    {
+        _animator = GetComponent<Animator>();
+        _rigidbody = GetComponent<Rigidbody2D>();
+        // ... 15 more lines of GetComponent hell
+    }
+}
+```
 
-### Quick Start — VContainer
+### The Integration Solution
 
-1. Register integration in your `LifetimeScope`
+With the DI integrations, **everything just works**:
 
 ```csharp
-using VContainer;
-using VContainer.Unity;
-using WallstopStudios.UnityHelpers.Integrations.VContainer;
-
-public sealed class GameLifetimeScope : LifetimeScope
+public class Enemy : MonoBehaviour
 {
-    protected override void Configure(IContainerBuilder builder)
-    {
-        // Registers IRelationalComponentAssigner and a scene entry point
-        builder.RegisterRelationalComponents();
+    [Inject] private IHealthSystem _health;         // ✅ DI injection
+    [SiblingComponent] private Animator _animator;  // ✅ Relational auto-wiring
+    [SiblingComponent] private Rigidbody2D _rigidbody; // ✅ Relational auto-wiring
 
-        // Or customize scanning (active objects only)
-        // builder.RegisterRelationalComponents(new RelationalSceneAssignmentOptions(includeInactive: false));
-    }
+    // No Awake() needed! Both DI and hierarchy references wired automatically
 }
 ```
 
-1. Build up runtime instances (DI + relational fields)
+### Why Use the DI Integrations
 
-```csharp
-using UnityEngine;
-using VContainer;
-using WallstopStudios.UnityHelpers.Integrations.VContainer;
+- **Zero boilerplate** - No `Awake()` method needed, no manual `GetComponent` calls, no validation code
+- **Consistent behavior** - Works seamlessly with constructor/property/field injection and runtime instantiation
+- **Safe fallback** - Gracefully degrades to standard behavior if DI binding is missing
+- **Risk-free adoption** - Use incrementally, mix DI and non-DI components freely
 
-public sealed class Spawner : MonoBehaviour
-{
-    [Inject] private IObjectResolver _resolver;
-    [SerializeField] private Enemy _enemyPrefab;
+### Supported Packages (Auto-detected)
 
-    public Enemy Spawn(Transform parent)
-    {
-        Enemy enemy = Instantiate(_enemyPrefab, parent);
-        return _resolver.BuildUpWithRelations(enemy);
-    }
-}
-```
+Unity Helpers automatically detects these packages via UPM:
 
-1. Apply to whole hierarchies when needed
+- **Zenject/Extenject**: `com.extenject.zenject`, `com.modesttree.zenject`, `com.svermeulen.extenject`
+- **VContainer**: `jp.cysharp.vcontainer`, `jp.hadashikick.vcontainer`
 
-```csharp
-_resolver.AssignRelationalHierarchy(root, includeInactiveChildren: false);
-```
+> 💡 **UPM packages work out-of-the-box** - No scripting defines needed!
 
-### Quick Start — Zenject
+### Manual or Source Imports (Non-UPM)
 
-1. Add the installer to your SceneContext
+If you import Zenject/VContainer as source code, .unitypackage, or raw DLLs (not via UPM), you need to manually add scripting defines:
 
-- Add a `SceneContext` to your scene.
-- Add `RelationalComponentsInstaller` to the same GameObject.
-- Toggle "Assign Scene On Initialize" to run a one-time scene scan after the container builds.
+1. Open `Project Settings > Player > Other Settings > Scripting Define Symbols`
+2. Add the appropriate define(s) for your target platforms:
+   - `ZENJECT_PRESENT` - When using Zenject/Extenject
+   - `VCONTAINER_PRESENT` - When using VContainer
+3. Unity will recompile and the integration assemblies under `Runtime/Integrations/*` will activate automatically
 
-1. Instantiate prefabs with DI + relational assignment
+### VContainer at a Glance
 
-```csharp
-using UnityEngine;
-using Zenject;
-using WallstopStudios.UnityHelpers.Integrations.Zenject;
+- **Enable once per scope**
 
-public sealed class Spawner
-{
-    readonly DiContainer _container;
-    readonly Enemy _enemyPrefab;
+  ```csharp
+  builder.RegisterRelationalComponents(
+      new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true),
+      enableAdditiveSceneListener: true
+  );
+  ```
 
-    public Spawner(DiContainer container, Enemy enemyPrefab)
-    {
-        _container = container;
-        _enemyPrefab = enemyPrefab;
-    }
+- **Runtime helpers**
+  - `_resolver.InstantiateComponentWithRelations(componentPrefab, parent)`
+  - `_resolver.InstantiateGameObjectWithRelations(rootPrefab, parent, includeInactiveChildren: true)`
+  - `_resolver.AssignRelationalHierarchy(existingRoot, includeInactiveChildren: true)`
+  - `RelationalObjectPools.CreatePoolWithRelations(...)` + `pool.GetWithRelations(resolver)`
 
-    public Enemy Spawn(Transform parent)
-    {
-        return _container.InstantiateComponentWithRelations(_enemyPrefab, parent);
-    }
-}
-```
+- **Full walkthrough**: [DI – VContainer sample](Samples~/DI%20-%20VContainer/README.md)
 
-1. Apply to whole hierarchies
+### Zenject at a Glance
 
-```csharp
-Container.AssignRelationalHierarchy(root, includeInactiveChildren: true);
-```
+- **Install once per scene**
+  - Add `RelationalComponentsInstaller` to your `SceneContext`.
+  - Toggles cover include-inactive scanning, single-pass strategy, and additive-scene listening.
+
+- **Runtime helpers**
+  - `_container.InstantiateComponentWithRelations(componentPrefab, parent)`
+  - `_container.InstantiateGameObjectWithRelations(rootPrefab, parent, includeInactiveChildren: true)`
+  - `_container.AssignRelationalHierarchy(existingRoot, includeInactiveChildren: true)`
+  - Subclass `RelationalMemoryPool<T>` to hydrate pooled items on spawn.
+
+- **Full walkthrough**: [DI – Zenject sample](Samples~/DI%20-%20Zenject/README.md)
 
 Notes
 
@@ -479,7 +467,21 @@ Beginner-friendly overview
 
 VContainer (1.16.x)
 
-- Runtime usage (LifetimeScope): Call `builder.RegisterRelationalComponents()` in `LifetimeScope.Configure`. The entry point runs automatically after the container builds.
+- Runtime usage (LifetimeScope): Call `builder.RegisterRelationalComponents()` in `LifetimeScope.Configure`. The entry point runs automatically after the container builds. You can enable an additive-scene listener and customize scan options:
+
+  ```csharp
+  using VContainer;
+  using VContainer.Unity;
+  using WallstopStudios.UnityHelpers.Integrations.VContainer;
+
+  protected override void Configure(IContainerBuilder builder)
+  {
+      // Single-pass scan + additive scene listener
+      var options = new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true);
+      builder.RegisterRelationalComponents(options, enableAdditiveSceneListener: true);
+  }
+  ```
+
 - Tests without LifetimeScope: Construct the entry point and call `Initialize()` yourself, and register your `AttributeMetadataCache` instance so the assigner uses it:
 
   ```csharp
@@ -500,7 +502,8 @@ VContainer (1.16.x)
   entry.Initialize();
   ```
 
-  - Inject vs BuildUp: Use `resolver.Inject(component)` before calling `resolver.AssignRelationalComponents(component)`.
+  - Inject vs BuildUp: Use `resolver.InjectWithRelations(component)` to inject + assign in one call, or `resolver.Inject(component)` then `resolver.AssignRelationalComponents(component)`.
+  - Prefabs & GameObjects: `resolver.InstantiateComponentWithRelations(prefab, parent)` or `resolver.InstantiateGameObjectWithRelations(prefab, parent)`; to inject existing hierarchies use `resolver.InjectGameObjectWithRelations(root)`.
 
 - EditMode reliability: In EditMode tests, prefer `[UnityTest]` and `yield return null` after creating objects and after initializing the entry point so Unity has a frame to register new objects before `FindObjectsOfType` runs and to allow assignments to complete.
 - Active scene filter: Entry points operate on the active scene only. In EditMode, create a new scene with `SceneManager.CreateScene`, set it active, and move your test hierarchy into it before calling `Initialize()`.
@@ -508,10 +511,16 @@ VContainer (1.16.x)
 
 Zenject/Extenject
 
-- Runtime usage: Add `RelationalComponentsInstaller` to your `SceneContext`. It binds `IRelationalComponentAssigner` and runs `RelationalComponentSceneInitializer` once the container is ready.
+- Runtime usage: Add `RelationalComponentsInstaller` to your `SceneContext`. It binds `IRelationalComponentAssigner` and runs `RelationalComponentSceneInitializer` once the container is ready. The installer exposes toggles to assign on initialize and to listen for additive scenes.
 - Tests: Bind a concrete `AttributeMetadataCache` instance and construct the assigner with that cache. Then resolve `IInitializable` and call `Initialize()`.
 - EditMode reliability: As with VContainer, consider `[UnityTest]` with a `yield return null` after creating objects and after calling `Initialize()` to allow Unity to register objects and complete assignments.
-- Active scene filter: The initializer operates on the active scene only. Create and set an active scene and move your test hierarchy into it before calling `Initialize()`.
+- Active scene filter: Initial one-time scan operates on the active scene only. The additive-scene listener processes only newly loaded scenes (not all loaded scenes).
+  - Prefabs & GameObjects: `container.InstantiateComponentWithRelations(...)`, `container.InstantiateGameObjectWithRelations(...)`, or `container.InjectGameObjectWithRelations(root)`; to inject + assign a single instance: `container.InjectWithRelations(component)`.
+
+### Object Pools (DI-aware)
+
+- Zenject: use `RelationalMemoryPool<T>` (or `<TParam, T>`) to assign relational fields in `OnSpawned` automatically.
+- VContainer: create pools with `RelationalObjectPools.CreatePoolWithRelations(...)` and rent via `pool.GetWithRelations(resolver)` to inject + assign.
 
 Common pitfalls and how to avoid them
 

package/Runtime/AssemblyInfo.cs

@@ -5,3 +5,5 @@ 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.Editor.VContainer")]
+[assembly: InternalsVisibleTo("WallstopStudios.UnityHelpers.Tests.Editor.Zenject")]

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/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)