com.wallstop-studios.unity-helpers 2.0.3 → 2.1.0

package/Editor/Utils/ScriptableObjectSingletonCreator.cs

@@ -18,6 +18,7 @@ namespace WallstopStudios.UnityHelpers.Editor.Utils
 
         // Prevents re-entrant execution during domain reloads/asset refreshes
         private static bool _isEnsuring;
+        private static int _assetEditingScopeDepth;
 
         // Controls whether informational logs are emitted. Warnings still always log.
         internal static bool VerboseLogging { get; set; }
@@ -41,6 +42,7 @@ namespace WallstopStudios.UnityHelpers.Editor.Utils
 
             _isEnsuring = true;
             AssetDatabase.StartAssetEditing();
+            _assetEditingScopeDepth++;
             bool anyChanges = false;
             try
             {
@@ -94,10 +96,24 @@ namespace WallstopStudios.UnityHelpers.Editor.Utils
                     }
 
                     string resolvedResourcesRoot = EnsureAndResolveFolderPath(ResourcesRoot);
+                    if (string.IsNullOrWhiteSpace(resolvedResourcesRoot))
+                    {
+                        Debug.LogError(
+                            "ScriptableObjectSingletonCreator: Unable to resolve required Resources root folder. Aborting singleton auto-creation."
+                        );
+                        break;
+                    }
 
                     string resourcesSubFolder = GetResourcesSubFolder(derivedType);
                     string targetFolderRequested = CombinePaths(ResourcesRoot, resourcesSubFolder);
                     string targetFolder = EnsureAndResolveFolderPath(targetFolderRequested);
+                    if (string.IsNullOrWhiteSpace(targetFolder))
+                    {
+                        Debug.LogError(
+                            $"ScriptableObjectSingletonCreator: Unable to ensure folder '{targetFolderRequested}' for singleton {derivedType.FullName}. Skipping asset creation."
+                        );
+                        continue;
+                    }
 
                     string targetAssetPath = CombinePaths(
                         targetFolder,
@@ -156,6 +172,10 @@ namespace WallstopStudios.UnityHelpers.Editor.Utils
             finally
             {
                 AssetDatabase.StopAssetEditing();
+                if (_assetEditingScopeDepth > 0)
+                {
+                    _assetEditingScopeDepth--;
+                }
                 _isEnsuring = false;
 
                 if (anyChanges)
@@ -448,31 +468,119 @@ namespace WallstopStudios.UnityHelpers.Editor.Utils
             {
                 string desiredName = parts[i];
 
-                // Find an existing subfolder that matches the desired segment, ignoring case
-                string[] subFolders = AssetDatabase.GetSubFolders(current);
-                string matchedExisting = null;
-                if (subFolders != null)
+                string matchedExisting = FindMatchingSubfolder(current, desiredName);
+
+                if (string.IsNullOrEmpty(matchedExisting))
                 {
-                    foreach (string sub in subFolders)
+                    string intendedPath = current + "/" + desiredName;
+                    string createdGuid = AssetDatabase.CreateFolder(current, desiredName);
+                    string createdPath = string.Empty;
+                    if (!string.IsNullOrEmpty(createdGuid))
+                    {
+                        createdPath = NormalizePath(AssetDatabase.GUIDToAssetPath(createdGuid));
+                    }
+
+                    string actualPath = FindMatchingSubfolder(current, desiredName);
+                    if (string.IsNullOrEmpty(actualPath))
+                    {
+                        actualPath = createdPath;
+                    }
+
+                    bool intendedValid = AssetDatabase.IsValidFolder(intendedPath);
+                    bool actualValid =
+                        !string.IsNullOrEmpty(actualPath)
+                        && AssetDatabase.IsValidFolder(actualPath);
+
+                    if (!intendedValid && !actualValid)
+                    {
+                        bool directoryExists =
+                            Directory.Exists(intendedPath)
+                            || (!string.IsNullOrEmpty(actualPath) && Directory.Exists(actualPath));
+                        if (directoryExists || !string.IsNullOrEmpty(createdGuid))
+                        {
+                            ForceAssetDatabaseSync();
+                        }
+
+                        intendedValid = AssetDatabase.IsValidFolder(intendedPath);
+                        if (!intendedValid)
+                        {
+                            actualPath = FindMatchingSubfolder(current, desiredName);
+                            if (
+                                string.IsNullOrEmpty(actualPath)
+                                && !string.IsNullOrEmpty(createdGuid)
+                            )
+                            {
+                                actualPath = NormalizePath(
+                                    AssetDatabase.GUIDToAssetPath(createdGuid)
+                                );
+                            }
+
+                            actualValid =
+                                !string.IsNullOrEmpty(actualPath)
+                                && AssetDatabase.IsValidFolder(actualPath);
+                        }
+                        else
+                        {
+                            actualPath = intendedPath;
+                            actualValid = true;
+                        }
+                    }
+
+                    if (intendedValid)
                     {
-                        // sub is like "Assets/Resources" — compare only the terminal name
-                        int lastSlash = sub.LastIndexOf('/', sub.Length - 1);
-                        string terminal = lastSlash >= 0 ? sub.Substring(lastSlash + 1) : sub;
-                        if (
-                            string.Equals(terminal, desiredName, StringComparison.OrdinalIgnoreCase)
+                        current = ResolveExistingFolderPath(intendedPath);
+                        LogVerbose(
+                            $"ScriptableObjectSingletonCreator: Created folder '{current}'."
+                        );
+                        continue;
+                    }
+
+                    if (
+                        actualValid
+                        && string.Equals(
+                            actualPath,
+                            intendedPath,
+                            StringComparison.OrdinalIgnoreCase
                         )
+                    )
+                    {
+                        string renameError = AssetDatabase.MoveAsset(actualPath, intendedPath);
+                        if (string.IsNullOrEmpty(renameError))
+                        {
+                            LogVerbose(
+                                $"ScriptableObjectSingletonCreator: Renamed folder '{actualPath}' to '{intendedPath}' to correct casing."
+                            );
+                            current = ResolveExistingFolderPath(intendedPath);
+                            continue;
+                        }
+
+                        LogVerbose(
+                            $"ScriptableObjectSingletonCreator: Reusing newly created folder '{actualPath}' when casing correction to '{intendedPath}' failed: {renameError}."
+                        );
+                        current = ResolveExistingFolderPath(actualPath);
+                        continue;
+                    }
+
+                    if (actualValid && AssetDatabase.IsValidFolder(actualPath))
+                    {
+                        bool deleted = AssetDatabase.DeleteAsset(actualPath);
+                        if (!deleted)
                         {
-                            matchedExisting = sub;
-                            break;
+                            Debug.LogWarning(
+                                $"ScriptableObjectSingletonCreator: Unexpected folder '{actualPath}' was created while attempting to create '{intendedPath}', but it could not be removed."
+                            );
                         }
+
+                        Debug.LogError(
+                            $"ScriptableObjectSingletonCreator: Expected to create folder '{intendedPath}', but Unity created '{actualPath}'. Aborting to avoid duplicate folders."
+                        );
+                        return string.Empty;
                     }
-                }
 
-                if (string.IsNullOrEmpty(matchedExisting))
-                {
-                    AssetDatabase.CreateFolder(current, desiredName);
-                    current = current + "/" + desiredName;
-                    LogVerbose($"ScriptableObjectSingletonCreator: Created folder '{current}'.");
+                    Debug.LogError(
+                        $"ScriptableObjectSingletonCreator: Failed to create folder '{intendedPath}'."
+                    );
+                    return string.Empty;
                 }
                 else
                 {
@@ -561,6 +669,33 @@ namespace WallstopStudios.UnityHelpers.Editor.Utils
             return current;
         }
 
+        private static string FindMatchingSubfolder(string parent, string desiredName)
+        {
+            if (string.IsNullOrWhiteSpace(parent) || string.IsNullOrWhiteSpace(desiredName))
+            {
+                return null;
+            }
+
+            string[] subFolders = AssetDatabase.GetSubFolders(parent);
+            if (subFolders == null || subFolders.Length == 0)
+            {
+                return null;
+            }
+
+            for (int i = 0; i < subFolders.Length; i++)
+            {
+                string sub = subFolders[i];
+                int lastSlash = sub.LastIndexOf('/', sub.Length - 1);
+                string terminal = lastSlash >= 0 ? sub.Substring(lastSlash + 1) : sub;
+                if (string.Equals(terminal, desiredName, StringComparison.OrdinalIgnoreCase))
+                {
+                    return sub;
+                }
+            }
+
+            return null;
+        }
+
         private static string ResolveExistingFolderPath(string intended)
         {
             if (string.IsNullOrWhiteSpace(intended))
@@ -621,6 +756,28 @@ namespace WallstopStudios.UnityHelpers.Editor.Utils
             return current;
         }
 
+        private static void ForceAssetDatabaseSync()
+        {
+            if (_assetEditingScopeDepth > 0)
+            {
+                AssetDatabase.StopAssetEditing();
+                try
+                {
+                    AssetDatabase.SaveAssets();
+                    AssetDatabase.Refresh();
+                }
+                finally
+                {
+                    AssetDatabase.StartAssetEditing();
+                }
+            }
+            else
+            {
+                AssetDatabase.SaveAssets();
+                AssetDatabase.Refresh();
+            }
+        }
+
         private static void LogVerbose(string message)
         {
             if (VerboseLogging)

package/README.md

@@ -77,7 +77,7 @@ void Awake() {
 void Awake() => this.AssignRelationalComponents();
 ```
 
-**Bonus:** Works with VContainer/Zenject for automatic DI + relational wiring!
+**Bonus:** Works with VContainer/Zenject/Reflex for automatic DI + relational wiring!
 
 [📖 Learn More](Docs/RELATIONAL_COMPONENTS.md) | [🎯 DI – VContainer](Samples~/DI%20-%20VContainer/README.md) | [🎯 DI – Zenject](Samples~/DI%20-%20Zenject/README.md) | [🎯 DI – Reflex](Samples~/DI%20-%20Reflex/README.md)
 
@@ -1018,7 +1018,7 @@ void ProcessLargeDataset(int size)
 
 - When the define is present, optional assemblies under `Runtime/Integrations/*` compile automatically and expose helpers like `RelationalComponentsInstaller` (Zenject/Reflex) and `RegisterRelationalComponents()` (VContainer).
 - If you use UPM, no manual defines are required — the package IDs above trigger symbols via `versionDefines` in the asmdefs.
-- For test scenarios without LifetimeScope (VContainer) or SceneContext (Zenject), see [DI Integrations: Testing and Edge Cases](Docs/RELATIONAL_COMPONENTS.md#di-integrations-testing-and-edge-cases) for step‑by‑step patterns.
+- For test scenarios without LifetimeScope (VContainer), SceneContext (Zenject), or SceneScope (Reflex), see [DI Integrations: Testing and Edge Cases](Docs/RELATIONAL_COMPONENTS.md#di-integrations-testing-and-edge-cases) for step‑by‑step patterns.
 
 **Quick start:**
 
@@ -1046,6 +1046,12 @@ using Zenject;
 using WallstopStudios.UnityHelpers.Integrations.Zenject;
 
 var enemy = Container.InstantiateComponentWithRelations(enemyPrefab, parent);
+
+// Reflex — prefab instantiation with DI + relations
+using Reflex.Core;
+using WallstopStudios.UnityHelpers.Integrations.Reflex;
+
+var enemy = container.InstantiateComponentWithRelations(enemyPrefab, parent);
 ```
 
 See the full guide with scenarios, troubleshooting, and testing patterns: [Relational Components Guide](Docs/RELATIONAL_COMPONENTS.md)
@@ -1064,10 +1070,17 @@ See the full guide with scenarios, troubleshooting, and testing patterns: [Relat
   - `container.InjectGameObjectWithRelations(root, includeInactiveChildren)` — inject hierarchy + assign
   - `container.InstantiateGameObjectWithRelations(prefab, parent)` — instantiate GO + inject + assign
 
+- Reflex:
+  - `container.InjectWithRelations(component)` — inject + assign a single instance
+  - `container.InstantiateComponentWithRelations(prefab, parent)` — instantiate + inject + assign
+  - `container.InjectGameObjectWithRelations(root, includeInactiveChildren)` — inject hierarchy + assign
+  - `container.InstantiateGameObjectWithRelations(prefab, parent)` — instantiate GO + inject + assign
+
 ### Additive Scene Loads
 
 - VContainer: `RegisterRelationalComponents(..., enableAdditiveSceneListener: true)` registers a listener that hydrates components in newly loaded scenes.
-- Zenject: `RelationalComponentsInstaller` exposes a toggle “Listen For Additive Scenes” to register the same behavior.
+- Zenject: `RelationalComponentsInstaller` exposes a toggle "Listen For Additive Scenes" to register the same behavior.
+- Reflex: `RelationalComponentsInstaller` exposes a toggle "Listen For Additive Scenes" to register the same behavior.
   - Only the newly loaded scene is processed; other loaded scenes are not re‑scanned.
 
 ### Performance Options
@@ -1076,6 +1089,7 @@ See the full guide with scenarios, troubleshooting, and testing patterns: [Relat
 - Single-pass scan (default) reduces `FindObjectsOfType` calls by scanning once and checking type ancestry.
   - VContainer: `new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true)`
   - Zenject: `new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true)`
+  - Reflex: `new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true)`
 - Per-object paths (instantiate/inject helpers, pools) avoid global scans entirely for objects created via DI.
 
 ---

package/Runtime/Core/Helper/UnityMainThreadDispatcher.cs

@@ -2,6 +2,7 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
 {
     using System;
     using System.Collections.Concurrent;
+    using System.Threading.Tasks;
     using UnityEngine;
     using Utils;
 #if UNITY_EDITOR
@@ -104,7 +105,8 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
         /// </summary>
         public System.Threading.Tasks.Task RunAsync(Action action)
         {
-            var tcs = new System.Threading.Tasks.TaskCompletionSource<bool>();
+            TaskCompletionSource<bool> tcs =
+                new System.Threading.Tasks.TaskCompletionSource<bool>();
             RunOnMainThread(() =>
             {
                 try
@@ -125,7 +127,7 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
         /// </summary>
         public System.Threading.Tasks.Task<T> Post<T>(Func<T> func)
         {
-            var tcs = new System.Threading.Tasks.TaskCompletionSource<T>();
+            TaskCompletionSource<T> tcs = new System.Threading.Tasks.TaskCompletionSource<T>();
             RunOnMainThread(() =>
             {
                 try

package/Runtime/Tags/Attribute.cs

@@ -4,6 +4,7 @@ namespace WallstopStudios.UnityHelpers.Tags
     using System.Collections.Generic;
     using System.ComponentModel;
     using System.Globalization;
+    using System.Runtime.CompilerServices;
     using System.Runtime.Serialization;
     using System.Text.Json.Serialization;
     using Core.Extension;
@@ -40,7 +41,6 @@ namespace WallstopStudios.UnityHelpers.Tags
     /// </para>
     /// </remarks>
     [Serializable]
-    [ProtoContract]
     public sealed class Attribute
         : IEquatable<Attribute>,
             IEquatable<float>,
@@ -91,6 +91,38 @@ namespace WallstopStudios.UnityHelpers.Tags
 
         private bool _currentValueCalculated;
 
+        private readonly Dictionary<EffectHandle, List<AttributeModification>> _modifications =
+            new();
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Attribute"/> class with a base value of 0.
+        /// </summary>
+        public Attribute()
+            : this(0) { }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Attribute"/> class with the specified base value.
+        /// </summary>
+        /// <param name="value">The base value for this attribute.</param>
+        public Attribute(float value)
+        {
+            _baseValue = value;
+            _currentValueCalculated = false;
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Attribute"/> class for JSON deserialization.
+        /// </summary>
+        /// <param name="baseValue">The base value for this attribute.</param>
+        /// <param name="currentValue">The cached current value.</param>
+        [JsonConstructor]
+        public Attribute(float baseValue, float currentValue)
+        {
+            _baseValue = baseValue;
+            _currentValue = currentValue;
+            _currentValueCalculated = true;
+        }
+
         /// <summary>
         /// Recalculates the current value by applying all active modifications to the base value.
         /// Modifications are sorted and applied in order: Addition, Multiplication, then Override.
@@ -99,8 +131,9 @@ namespace WallstopStudios.UnityHelpers.Tags
         {
             float calculatedValue = _baseValue;
             using PooledResource<List<AttributeModification>> modificationBuffer =
-                Buffers<AttributeModification>.List.Get();
-            List<AttributeModification> modifications = modificationBuffer.resource;
+                Buffers<AttributeModification>.List.Get(
+                    out List<AttributeModification> modifications
+                );
             foreach (
                 KeyValuePair<EffectHandle, List<AttributeModification>> entry in _modifications
             )
@@ -108,8 +141,7 @@ namespace WallstopStudios.UnityHelpers.Tags
                 modifications.AddRange(entry.Value);
             }
 
-            modifications.Sort((a, b) => ((int)a.action).CompareTo((int)b.action));
-
+            modifications.Sort();
             foreach (AttributeModification attributeModification in modifications)
             {
                 ApplyAttributeModification(attributeModification, ref calculatedValue);
@@ -119,9 +151,6 @@ namespace WallstopStudios.UnityHelpers.Tags
             _currentValueCalculated = true;
         }
 
-        private readonly Dictionary<EffectHandle, List<AttributeModification>> _modifications =
-            new();
-
         /// <summary>
         /// Implicitly converts an Attribute to its current float value.
         /// </summary>
@@ -137,32 +166,112 @@ namespace WallstopStudios.UnityHelpers.Tags
         public static implicit operator Attribute(float value) => new(value);
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="Attribute"/> class with a base value of 0.
+        /// Applies a temporary additive modification to the attribute.
         /// </summary>
-        public Attribute()
-            : this(0) { }
+        /// <param name="value">The amount to add to the attribute's calculated value.</param>
+        /// <returns>
+        /// An effect handle that can later be supplied to <see cref="RemoveAttributeModification(EffectHandle)"/>
+        /// to revoke this addition.
+        /// </returns>
+        /// <exception cref="ArgumentException">
+        /// Thrown when <paramref name="value"/> is not a finite number.
+        /// </exception>
+        public EffectHandle Add(float value)
+        {
+            ValidateInput(value);
+
+            EffectHandle handle = EffectHandle.CreateInstanceInternal();
+            AttributeModification modification = new()
+            {
+                action = ModificationAction.Addition,
+                value = value,
+            };
+            ApplyAttributeModification(modification, handle);
+            return handle;
+        }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="Attribute"/> class with the specified base value.
+        /// Applies a temporary subtractive modification to the attribute.
         /// </summary>
-        /// <param name="value">The base value for this attribute.</param>
-        public Attribute(float value)
+        /// <param name="value">The amount to subtract from the attribute's calculated value.</param>
+        /// <returns>
+        /// An effect handle that can later be supplied to <see cref="RemoveAttributeModification(EffectHandle)"/>
+        /// to revoke this subtraction.
+        /// </returns>
+        /// <exception cref="ArgumentException">
+        /// Thrown when <paramref name="value"/> is not a finite number.
+        /// </exception>
+        public EffectHandle Subtract(float value)
         {
-            _baseValue = value;
-            _currentValueCalculated = false;
+            ValidateInput(value);
+
+            EffectHandle handle = EffectHandle.CreateInstanceInternal();
+            AttributeModification modification = new()
+            {
+                action = ModificationAction.Addition,
+                // Subtraction is represented as a negative additive modifier to preserve modifier ordering.
+                value = -value,
+            };
+            ApplyAttributeModification(modification, handle);
+            return handle;
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="Attribute"/> class for JSON deserialization.
+        /// Applies a temporary division-based modification to the attribute.
         /// </summary>
-        /// <param name="baseValue">The base value for this attribute.</param>
-        /// <param name="currentValue">The cached current value.</param>
-        [JsonConstructor]
-        public Attribute(float baseValue, float currentValue)
+        /// <param name="value">
+        /// The divisor that will be applied to the attribute's calculated value.
+        /// </param>
+        /// <returns>
+        /// An effect handle that can later be supplied to <see cref="RemoveAttributeModification(EffectHandle)"/>
+        /// to revoke this division.
+        /// </returns>
+        /// <exception cref="ArgumentException">
+        /// Thrown when <paramref name="value"/> is zero or not a finite number.
+        /// </exception>
+        public EffectHandle Divide(float value)
         {
-            _baseValue = baseValue;
-            _currentValue = currentValue;
-            _currentValueCalculated = true;
+            ValidateInput(value);
+
+            if (value == 0f)
+            {
+                throw new ArgumentException("Cannot divide by zero.", nameof(value));
+            }
+
+            EffectHandle handle = EffectHandle.CreateInstanceInternal();
+            AttributeModification modification = new()
+            {
+                action = ModificationAction.Multiplication,
+                // Apply division by multiplying by the reciprocal to maintain multiplication ordering guarantees.
+                value = 1f / value,
+            };
+            ApplyAttributeModification(modification, handle);
+            return handle;
+        }
+
+        /// <summary>
+        /// Applies a temporary multiplicative modification to the attribute.
+        /// </summary>
+        /// <param name="value">The multiplier to apply to the attribute's calculated value.</param>
+        /// <returns>
+        /// An effect handle that can later be supplied to <see cref="RemoveAttributeModification(EffectHandle)"/>
+        /// to revoke this multiplication.
+        /// </returns>
+        /// <exception cref="ArgumentException">
+        /// Thrown when <paramref name="value"/> is not a finite number.
+        /// </exception>
+        public EffectHandle Multiply(float value)
+        {
+            ValidateInput(value);
+
+            EffectHandle handle = EffectHandle.CreateInstanceInternal();
+            AttributeModification modification = new()
+            {
+                action = ModificationAction.Multiplication,
+                value = value,
+            };
+            ApplyAttributeModification(modification, handle);
+            return handle;
         }
 
         /// <summary>
@@ -173,6 +282,17 @@ namespace WallstopStudios.UnityHelpers.Tags
             _currentValueCalculated = false;
         }
 
+        private static void ValidateInput(float value, [CallerMemberName] string caller = null)
+        {
+            if (!float.IsFinite(value))
+            {
+                throw new ArgumentException(
+                    $"Cannot {caller?.ToLowerInvariant()} by infinity or NaN.",
+                    nameof(value)
+                );
+            }
+        }
+
         /// <summary>
         /// Applies an attribute modification to this attribute.
         /// If a handle is provided, the modification is temporary and can be removed.