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

package/Editor/Sprites/AnimationViewerWindow.cs

@@ -598,8 +598,8 @@ namespace WallstopStudios.UnityHelpers.Editor.Sprites
                 // Prefer Assets-relative paths for UI components that expect them
                 if (!candidate.StartsWith("Assets", StringComparison.OrdinalIgnoreCase))
                 {
-                    string assetsRoot = Application.dataPath.Replace('\\', '/');
-                    string full = candidate.Replace('\\', '/');
+                    string assetsRoot = Application.dataPath.SanitizePath();
+                    string full = candidate.SanitizePath();
                     if (full.StartsWith(assetsRoot, StringComparison.OrdinalIgnoreCase))
                     {
                         candidate = "Assets" + full.Substring(assetsRoot.Length);
@@ -622,10 +622,10 @@ namespace WallstopStudios.UnityHelpers.Editor.Sprites
             }
 
             // Ensure Assets-relative if possible
-            string path = assetsRelativeDir.Replace('\\', '/');
+            string path = assetsRelativeDir.SanitizePath();
             if (!path.StartsWith("Assets", StringComparison.OrdinalIgnoreCase))
             {
-                string assetsRoot = Application.dataPath.Replace('\\', '/');
+                string assetsRoot = Application.dataPath.SanitizePath();
                 string full = path;
                 if (full.StartsWith(assetsRoot, StringComparison.OrdinalIgnoreCase))
                 {

package/Editor/Sprites/SpriteSettingsApplierAPI.cs

@@ -7,6 +7,7 @@ namespace WallstopStudios.UnityHelpers.Editor.Sprites
     using System.Text.RegularExpressions;
     using UnityEditor;
     using UnityEngine;
+    using WallstopStudios.UnityHelpers.Core.Helper;
 
     /// <summary>
     /// Public API to apply SpriteSettings profiles to assets. Mirrors the window logic
@@ -83,7 +84,7 @@ namespace WallstopStudios.UnityHelpers.Editor.Sprites
 
         private static string SanitizePath(string p)
         {
-            return string.IsNullOrEmpty(p) ? p : p.Replace('\\', '/');
+            return string.IsNullOrEmpty(p) ? p : p.SanitizePath();
         }
 
         public static SpriteSettings FindMatchingSettings(

package/Editor/Sprites/TextureResizerWizard.cs

@@ -10,6 +10,7 @@ namespace WallstopStudios.UnityHelpers.Editor.Sprites
     using UnityEngine;
     using UnityEngine.Serialization;
     using WallstopStudios.UnityHelpers.Core.Extension;
+    using WallstopStudios.UnityHelpers.Core.Helper;
     using WallstopStudios.UnityHelpers.Utils;
     using Object = UnityEngine.Object;
 
@@ -299,7 +300,7 @@ namespace WallstopStudios.UnityHelpers.Editor.Sprites
                             {
                                 string fileName = Path.GetFileName(assetPath);
                                 finalAssetPath = Path.Combine(outputDirAssetPath, fileName)
-                                    .Replace('\\', '/');
+                                    .SanitizePath();
                                 EnsureDirectory(finalAssetPath);
                             }
 
@@ -420,12 +421,12 @@ namespace WallstopStudios.UnityHelpers.Editor.Sprites
                 0,
                 Application.dataPath.Length - "Assets".Length
             );
-            return Path.Combine(projectRoot, assetPath).Replace('\\', '/');
+            return Path.Combine(projectRoot, assetPath).SanitizePath();
         }
 
         private static void EnsureDirectory(string assetPath)
         {
-            string dirAsset = Path.GetDirectoryName(assetPath)?.Replace('\\', '/');
+            string dirAsset = Path.GetDirectoryName(assetPath)?.SanitizePath();
             if (string.IsNullOrEmpty(dirAsset))
             {
                 return;

package/Editor/Utils/ScriptableObjectSingletonCreator.cs

@@ -214,7 +214,7 @@ namespace WallstopStudios.UnityHelpers.Editor.Utils
             string assetName = Path.GetFileName(targetAssetPath);
 
             // Ensure the target parent folder exists and use its exact-cased path
-            string targetParent = Path.GetDirectoryName(normalizedTarget)?.Replace('\\', '/');
+            string targetParent = Path.GetDirectoryName(normalizedTarget)?.SanitizePath();
             if (!string.IsNullOrWhiteSpace(targetParent))
             {
                 string resolvedParent = EnsureAndResolveFolderPath(targetParent);
@@ -303,7 +303,7 @@ namespace WallstopStudios.UnityHelpers.Editor.Utils
                 }
 
                 // Final guard: ensure parent exists just before moving
-                string parent = Path.GetDirectoryName(normalizedTarget)?.Replace('\\', '/');
+                string parent = Path.GetDirectoryName(normalizedTarget)?.SanitizePath();
                 if (!string.IsNullOrWhiteSpace(parent) && !AssetDatabase.IsValidFolder(parent))
                 {
                     string ensured = EnsureAndResolveFolderPath(parent);
@@ -324,7 +324,7 @@ namespace WallstopStudios.UnityHelpers.Editor.Utils
                 }
 
                 // Retry after ensuring parent and performing save/refresh if parent folder may not yet be registered
-                string parentDir = Path.GetDirectoryName(normalizedTarget)?.Replace('\\', '/');
+                string parentDir = Path.GetDirectoryName(normalizedTarget)?.SanitizePath();
                 bool retried = false;
                 if (!string.IsNullOrWhiteSpace(parentDir))
                 {

package/README.md

@@ -454,24 +454,27 @@ Already read the [Top 5 Time-Savers](#-top-5-time-savers)? Jump directly to the
 
 ### Random Number Generators
 
-Unity Helpers includes **12 high-quality random number generators**, all implementing a rich `IRandom` interface:
+Unity Helpers includes **15 high-quality random number generators**, all implementing a rich `IRandom` interface:
 
 #### Available Generators
 
-| Generator                       | Speed     | Quality   | Use Case                                 |
-| ------------------------------- | --------- | --------- | ---------------------------------------- |
-| **IllusionFlow** ⭐             | Fast      | Good      | Default choice (via PRNG.Instance)       |
-| **PcgRandom**                   | Very Fast | Excellent | Deterministic gameplay; explicit seeding |
-| **RomuDuo**                     | Fastest   | Good      | Maximum performance needed               |
-| **LinearCongruentialGenerator** | Fastest   | Fair      | Simple, fast generation                  |
-| **XorShiftRandom**              | Very Fast | Good      | General purpose                          |
-| **XoroShiroRandom**             | Very Fast | Good      | General purpose                          |
-| **SplitMix64**                  | Very Fast | Good      | Initialization, hashing                  |
-| **SquirrelRandom**              | Moderate  | Good      | Hash-based generation                    |
-| **WyRandom**                    | Moderate  | Good      | Hashing applications                     |
-| **DotNetRandom**                | Moderate  | Good      | .NET compatibility                       |
-| **SystemRandom**                | Slow      | Good      | Backward compatibility                   |
-| **UnityRandom**                 | Very Slow | Good      | Unity compatibility                      |
+| Generator                       | Speed     | Quality   | Use Case                                   |
+| ------------------------------- | --------- | --------- | ------------------------------------------ |
+| **IllusionFlow** ⭐             | Very Fast | Excellent | Default choice (via PRNG.Instance)         |
+| **PcgRandom** ⭐                | Very Fast | Excellent | Deterministic gameplay; explicit seeding   |
+| **FlurryBurstRandom**           | Very Fast | Excellent | High-quality PCG/Xoshiro alternative       |
+| **RomuDuo**                     | Very Fast | Good      | Maximum performance needed                 |
+| **LinearCongruentialGenerator** | Fastest   | Fair      | Simple, fast generation                    |
+| **XorShiftRandom**              | Very Fast | Good      | General purpose                            |
+| **XoroShiroRandom**             | Very Fast | Good      | General purpose                            |
+| **SplitMix64**                  | Very Fast | Good      | Initialization, hashing                    |
+| **StormDropRandom**             | Fast      | Excellent | Large-buffer streams for heavy simulations |
+| **PhotonSpinRandom**            | Moderate  | Excellent | Bulk generation; long non-overlapping runs |
+| **SquirrelRandom**              | Moderate  | Good      | Hash-based generation                      |
+| **WyRandom**                    | Moderate  | Good      | Hashing applications                       |
+| **DotNetRandom**                | Moderate  | Good      | .NET compatibility                         |
+| **SystemRandom**                | Slow      | Good      | Backward compatibility                     |
+| **UnityRandom**                 | Very Slow | Good      | Unity compatibility                        |
 
 ⭐ **Recommended**: Use `PRNG.Instance` (currently IllusionFlow)
 
@@ -657,6 +660,7 @@ public class Enemy : MonoBehaviour
 ```
 
 See the in-depth guide: [Relational Components](Docs/RELATIONAL_COMPONENTS.md).
+Performance snapshots: [Relational Component Performance Benchmarks](Docs/RELATIONAL_COMPONENT_PERFORMANCE.md).
 
 ---
 
@@ -1120,9 +1124,16 @@ Unity Helpers is built with performance as a top priority:
 
 **Reflection:**
 
-- IL-emitted delegates 10-100x faster than System.Reflection
-- Safe for IL2CPP and AOT platforms
-- [📊 Reflection Performance](Docs/REFLECTION_HELPERS.md)
+- Cached delegates are 10-100x faster than raw `System.Reflection` (boxed scenarios improve the most)
+- Safe for IL2CPP and AOT platforms; capability overrides (`ReflectionHelpers.OverrideReflectionCapabilities`) let tests force expression/IL fallbacks
+- Run the benchmarks via **ReflectionPerformanceTests.Benchmark** (EditMode Test Runner) and commit the updated markdown section
+- [📘 Reflection Performance Guide](Docs/ReflectionPerformance.md) and [📊 Benchmarks](Docs/REFLECTION_PERFORMANCE.md)
+
+**List Sorting:**
+
+- Multiple adaptive algorithms (`Ghost`, `Meteor`, `Power`, `Grail`, `Pattern-Defeating QuickSort`, `Insertion`) tuned for `IList<T>`
+- Deterministic datasets (sorted, nearly sorted, shuffled) across sizes from 100 to 1,000,000
+- [📊 IList Sorting Performance Benchmarks](Docs/ILIST_SORTING_PERFORMANCE.md)
 
 ---
 
@@ -1155,8 +1166,12 @@ Unity Helpers is built with performance as a top priority:
 
 **Performance & Reference:**
 
+- Reflection Performance Guide — [Reflection Performance](Docs/ReflectionPerformance.md)
+- Reflection AOT/Burst Validation — [IL2CPP & Burst Validation](Docs/ReflectionAotBurstValidation.md)
+- Reflection Benchmark CI Proposal — [Benchmark CI Proposal](Docs/ReflectionBenchmarkCIProposal.md)
 - Random Performance — [Random Performance](Docs/RANDOM_PERFORMANCE.md)
 - Reflection Helpers — [Reflection Helpers](Docs/REFLECTION_HELPERS.md)
+- IList Sorting Performance — [IList Sorting Performance](Docs/ILIST_SORTING_PERFORMANCE.md)
 
 **Project Info:**
 

package/Runtime/Core/Attributes/BaseRelationalComponentAttribute.cs

@@ -84,6 +84,12 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
     /// </summary>
     internal static class RelationalComponentProcessor
     {
+        private static readonly MethodInfo CreateFieldAccessorGenericMethod =
+            typeof(RelationalComponentProcessor).GetMethod(
+                nameof(CreateFieldAccessorGeneric),
+                BindingFlags.NonPublic | BindingFlags.Static
+            );
+
         internal enum FieldKind : byte
         {
             Single = 0,
@@ -168,42 +174,135 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
         {
             public readonly FieldInfo field;
             public readonly TAttribute attribute;
-            public readonly Action<object, object> setter;
-            public readonly Func<object, object> getter;
+            private readonly FieldAccessor accessor;
+            private readonly FilterParameters filters;
             public readonly FieldKind kind;
             public readonly Type elementType;
             public readonly Func<int, Array> arrayCreator;
             public readonly Func<int, IList> listCreator;
             public readonly Func<int, object> hashSetCreator;
             public readonly Action<object, object> hashSetAdder;
+            public readonly Action<object> hashSetClearer;
             public readonly bool isInterface;
 
             public FieldMetadata(
                 FieldInfo field,
                 TAttribute attribute,
-                Action<object, object> setter,
-                Func<object, object> getter,
+                FilterParameters filters,
+                FieldAccessor accessor,
                 FieldKind kind,
                 Type elementType,
                 Func<int, Array> arrayCreator,
                 Func<int, IList> listCreator,
                 Func<int, object> hashSetCreator,
                 Action<object, object> hashSetAdder,
+                Action<object> hashSetClearer,
                 bool isInterface
             )
             {
                 this.field = field;
                 this.attribute = attribute;
-                this.setter = setter;
-                this.getter = getter;
+                this.accessor = accessor ?? FieldAccessor.Null;
+                this.filters = filters;
                 this.kind = kind;
                 this.elementType = elementType;
                 this.arrayCreator = arrayCreator;
                 this.listCreator = listCreator;
                 this.hashSetCreator = hashSetCreator;
                 this.hashSetAdder = hashSetAdder;
+                this.hashSetClearer = hashSetClearer;
                 this.isInterface = isInterface;
             }
+
+            public bool HasFilters => this.filters.RequiresPostProcessing;
+
+            public FilterParameters Filters => this.filters;
+
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            public object GetValue(Component component)
+            {
+                return this.accessor.Get(component);
+            }
+
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            public void SetValue(Component component, object value)
+            {
+                this.accessor.Set(component, value);
+            }
+        }
+
+        internal abstract class FieldAccessor
+        {
+            public static readonly FieldAccessor Null = new NullFieldAccessor();
+
+            public abstract object Get(Component component);
+            public abstract void Set(Component component, object value);
+
+            private sealed class NullFieldAccessor : FieldAccessor
+            {
+                public override object Get(Component component)
+                {
+                    return null;
+                }
+
+                public override void Set(Component component, object value) { }
+            }
+        }
+
+        private sealed class FieldAccessor<TComponent, TValue> : FieldAccessor
+            where TComponent : Component
+        {
+            private readonly FieldSetter<TComponent, TValue> setter;
+            private readonly Func<TComponent, TValue> getter;
+
+            public FieldAccessor(FieldInfo field)
+            {
+                this.setter = ReflectionHelpers.GetFieldSetter<TComponent, TValue>(field);
+                this.getter = ReflectionHelpers.GetFieldGetter<TComponent, TValue>(field);
+            }
+
+            public override object Get(Component component)
+            {
+                if (component == null)
+                {
+                    return null;
+                }
+
+                TComponent typedComponent = (TComponent)component;
+                return this.getter(typedComponent);
+            }
+
+            public override void Set(Component component, object value)
+            {
+                if (component == null)
+                {
+                    return;
+                }
+
+                TComponent typedComponent = (TComponent)component;
+                TValue typedValue = value != null ? (TValue)value : default;
+                this.setter(ref typedComponent, typedValue);
+            }
+        }
+
+        private static FieldAccessor CreateFieldAccessor(Type componentType, FieldInfo field)
+        {
+            if (componentType == null || !typeof(Component).IsAssignableFrom(componentType))
+            {
+                return FieldAccessor.Null;
+            }
+
+            MethodInfo generic = CreateFieldAccessorGenericMethod.MakeGenericMethod(
+                componentType,
+                field.FieldType
+            );
+            return (FieldAccessor)generic.Invoke(null, new object[] { field });
+        }
+
+        private static FieldAccessor CreateFieldAccessorGeneric<TComponent, TValue>(FieldInfo field)
+            where TComponent : Component
+        {
+            return new FieldAccessor<TComponent, TValue>(field);
         }
 
         internal static FieldMetadata<TAttribute>[] GetFieldMetadata<TAttribute>(Type componentType)
@@ -275,6 +374,7 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
                     Func<int, IList> listCreator = null;
                     Func<int, object> hashSetCreator = null;
                     Action<object, object> hashSetAdder = null;
+                    Action<object> hashSetClearer = null;
 
                     switch (kind)
                     {
@@ -291,6 +391,9 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
                                 resolvedElementType
                             );
                             hashSetAdder = ReflectionHelpers.GetHashSetAdder(resolvedElementType);
+                            hashSetClearer = ReflectionHelpers.GetHashSetClearer(
+                                resolvedElementType
+                            );
                             break;
                     }
 
@@ -304,18 +407,21 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
                             )
                         );
 
+                    FilterParameters filters = new(attribute);
+
                     result.Add(
                         new FieldMetadata<TAttribute>(
                             field,
                             attribute,
-                            ReflectionHelpers.GetFieldSetter(field),
-                            ReflectionHelpers.GetFieldGetter(field),
+                            filters,
+                            CreateFieldAccessor(componentType, field),
                             kind,
                             resolvedElementType,
                             arrayCreator,
                             listCreator,
                             hashSetCreator,
                             hashSetAdder,
+                            hashSetClearer,
                             isInterface
                         )
                     );
@@ -343,6 +449,7 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
                     Func<int, IList> listCreator = null;
                     Func<int, object> hashSetCreator = null;
                     Action<object, object> hashSetAdder = null;
+                    Action<object> hashSetClearer = null;
 
                     switch (kind)
                     {
@@ -357,6 +464,7 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
                                 elementType
                             );
                             hashSetAdder = ReflectionHelpers.GetHashSetAdder(elementType);
+                            hashSetClearer = ReflectionHelpers.GetHashSetClearer(elementType);
                             break;
                     }
 
@@ -367,18 +475,21 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
                             || (!elementType.IsSealed && elementType != typeof(Component))
                         );
 
+                    FilterParameters filters = new(attribute);
+
                     return (FieldMetadata<TAttribute>?)
                         new FieldMetadata<TAttribute>(
                             field,
                             attribute,
-                            ReflectionHelpers.GetFieldSetter(field),
-                            ReflectionHelpers.GetFieldGetter(field),
+                            filters,
+                            CreateFieldAccessor(componentType, field),
                             kind,
                             elementType,
                             arrayCreator,
                             listCreator,
                             hashSetCreator,
                             hashSetAdder,
+                            hashSetClearer,
                             isInterface
                         );
                 })
@@ -414,7 +525,7 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
 
         internal static bool ShouldSkipAssignment<TAttribute>(
             FieldMetadata<TAttribute> metadata,
-            object component
+            Component component
         )
             where TAttribute : BaseRelationalComponentAttribute
         {
@@ -423,7 +534,7 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
                 return false;
             }
 
-            object currentValue = metadata.getter(component);
+            object currentValue = metadata.GetValue(component);
 
             return ValueHelpers.IsAssigned(currentValue);
         }
@@ -453,26 +564,42 @@ namespace WallstopStudios.UnityHelpers.Core.Attributes
             {
                 case FieldKind.Array:
 
-                    metadata.setter(component, metadata.arrayCreator(0));
+                    metadata.SetValue(component, metadata.arrayCreator(0));
 
                     break;
 
                 case FieldKind.List:
-
-                    metadata.setter(component, metadata.listCreator(0));
-
+                    {
+                        object existing = metadata.GetValue(component);
+                        if (existing is IList list)
+                        {
+                            list.Clear();
+                        }
+                        else
+                        {
+                            metadata.SetValue(component, metadata.listCreator(0));
+                        }
+                    }
                     break;
 
                 case FieldKind.HashSet:
-
-                    metadata.setter(component, metadata.hashSetCreator(0));
-
+                    {
+                        object existing = metadata.GetValue(component);
+                        if (existing != null && metadata.hashSetClearer != null)
+                        {
+                            metadata.hashSetClearer(existing);
+                        }
+                        else
+                        {
+                            metadata.SetValue(component, metadata.hashSetCreator(0));
+                        }
+                    }
                     break;
             }
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private static bool PassesStateAndFilters(
+        internal static bool PassesStateAndFilters(
             Component candidate,
             FilterParameters filters,
             bool filterDisabledComponents = true