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

package/Runtime/Core/Random/StormDropRandom.cs

@@ -0,0 +1,271 @@
+namespace WallstopStudios.UnityHelpers.Core.Random
+{
+    using System;
+    using System.Runtime.Serialization;
+    using System.Text.Json.Serialization;
+    using ProtoBuf;
+    using WallstopStudios.UnityHelpers.Core.Extension;
+    using WallstopStudios.UnityHelpers.Core.Helper;
+    using WallstopStudios.UnityHelpers.Utils;
+
+    /// <summary>
+    /// StormDrop32: a large-state ARX generator inspired by SHISHUA-style buffer mixing, emphasizing long periods and diffusion.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// https://github.com/wileylooper/stormdrop
+    /// Ported from <c>wileylooper/stormdrop</c>. The 32-bit variant maintains a 1024-element ring buffer and two 32-bit
+    /// accumulators. Each step mixes the current index with the accumulators, rotates, and feeds the buffer to provide
+    /// high-quality sequences suitable for heavy simulation workloads.
+    /// </para>
+    /// <para>Pros:</para>
+    /// <list type="bullet">
+    /// <item><description>Large period and strong diffusion thanks to the 4 KB buffer.</description></item>
+    /// <item><description>Deterministic snapshots via <see cref="RandomState"/>.</description></item>
+    /// <item><description>Thread-local access available via <see cref="ThreadLocalRandom{T}.Instance"/>.</description></item>
+    /// </list>
+    /// <para>Cons:</para>
+    /// <list type="bullet">
+    /// <item><description>Higher per-instance memory compared to smaller generators.</description></item>
+    /// <item><description>Not cryptographically secure.</description></item>
+    /// </list>
+    /// <para>When to use:</para>
+    /// <list type="bullet">
+    /// <item><description>Procedural workloads needing long non-overlapping streams or large batches.</description></item>
+    /// </list>
+    /// <para>When not to use:</para>
+    /// <list type="bullet">
+    /// <item><description>Memory-constrained contexts; prefer smaller-state generators like FlurryBurst.</description></item>
+    /// <item><description>Security/adversarial scenarios.</description></item>
+    /// </list>
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// using WallstopStudios.UnityHelpers.Core.Random;
+    ///
+    /// StormDropRandom rng = new StormDropRandom(seed: 42u);
+    /// float noise = rng.NextFloat();
+    /// Vector3 point = rng.NextVector3InSphere(10f); // via RandomExtensions
+    /// </code>
+    /// </example>
+    [Serializable]
+    [DataContract]
+    [ProtoContract(SkipConstructor = true)]
+    public sealed class StormDropRandom
+        : AbstractRandom,
+            IEquatable<StormDropRandom>,
+            IComparable,
+            IComparable<StormDropRandom>
+    {
+        private const uint Increment = 1_111_111_111U;
+        private const int ElementCount = 1024;
+        private const int ElementMask = ElementCount - 1;
+        private const int ElementByteSize = ElementCount * sizeof(uint);
+        private const int WarmupRounds = 128;
+
+        public static StormDropRandom Instance => ThreadLocalRandom<StormDropRandom>.Instance;
+
+        public override RandomState InternalState
+        {
+            get
+            {
+                using PooledResource<byte[]> payloadLease = WallstopArrayPool<byte>.Get(
+                    ElementByteSize,
+                    out byte[] buffer
+                );
+                Buffer.BlockCopy(_elements, 0, buffer, 0, ElementByteSize);
+
+                ulong state1 = ((ulong)_a << 32) | _b;
+                return BuildState(
+                    state1,
+                    payload: new ArraySegment<byte>(buffer, 0, ElementByteSize)
+                );
+            }
+        }
+
+        [ProtoMember(6)]
+        private uint[] _elements = new uint[ElementCount];
+
+        [ProtoMember(7)]
+        private uint _a;
+
+        [ProtoMember(8)]
+        private uint _b;
+
+        public StormDropRandom()
+            : this(Guid.NewGuid()) { }
+
+        public StormDropRandom(Guid guid)
+        {
+            InitializeFromGuid(guid);
+        }
+
+        public StormDropRandom(uint seed)
+        {
+            uint seedB = seed ^ 0x9E3779B9U;
+            if (seedB == 0)
+            {
+                seedB = 1U;
+            }
+
+            InitializeFromScalars(seed, seedB);
+        }
+
+        public StormDropRandom(uint seedA, uint seedB)
+        {
+            InitializeFromScalars(seedA, seedB == 0 ? 1U : seedB);
+        }
+
+        [JsonConstructor]
+        public StormDropRandom(RandomState internalState)
+        {
+            _a = (uint)(internalState.State1 >> 32);
+            _b = (uint)internalState.State1;
+            LoadSerializedElements(internalState._payload);
+            RestoreCommonState(internalState);
+        }
+
+        public override uint NextUint()
+        {
+            unchecked
+            {
+                uint index = _b & ElementMask;
+                uint mix = (_elements[index] ^ _a) + _b;
+
+                _a = RotateLeft(_a, 17) ^ _b;
+                _b += Increment;
+
+                _elements[_b & ElementMask] += RotateLeft(mix, 13);
+
+                return mix;
+            }
+        }
+
+        public override IRandom Copy()
+        {
+            return new StormDropRandom(InternalState);
+        }
+
+        public bool Equals(StormDropRandom other)
+        {
+            if (other == null)
+            {
+                return false;
+            }
+
+            if (_a != other._a || _b != other._b)
+            {
+                return false;
+            }
+
+            if (!_elements.AsSpan().SequenceEqual(other._elements))
+            {
+                return false;
+            }
+
+            return _cachedGaussian == other._cachedGaussian;
+        }
+
+        public override bool Equals(object obj)
+        {
+            return Equals(obj as StormDropRandom);
+        }
+
+        public int CompareTo(object obj)
+        {
+            return CompareTo(obj as StormDropRandom);
+        }
+
+        public int CompareTo(StormDropRandom other)
+        {
+            if (other == null)
+            {
+                return -1;
+            }
+
+            int comparison = _a.CompareTo(other._a);
+            if (comparison != 0)
+            {
+                return comparison;
+            }
+
+            comparison = _b.CompareTo(other._b);
+            if (comparison != 0)
+            {
+                return comparison;
+            }
+
+            for (int i = 0; i < ElementCount; ++i)
+            {
+                comparison = _elements[i].CompareTo(other._elements[i]);
+                if (comparison != 0)
+                {
+                    return comparison;
+                }
+            }
+
+            return 0;
+        }
+
+        public override int GetHashCode()
+        {
+            return Objects.HashCode(_a, _b);
+        }
+
+        public override string ToString()
+        {
+            return this.ToJson();
+        }
+
+        private void InitializeFromGuid(Guid guid)
+        {
+            (ulong seed0, ulong seed1) = RandomUtilities.GuidToUInt64Pair(guid);
+            ulong mixer = seed0 ^ (seed1 << 1) ^ 0x9E3779B97F4A7C15UL;
+            InitializeFromMixer(ref mixer);
+        }
+
+        private void InitializeFromScalars(uint seedA, uint seedB)
+        {
+            ulong mixer = ((ulong)seedA << 32) | seedB;
+            mixer ^= 0xD2B74407B1CE6E93UL;
+            InitializeFromMixer(ref mixer);
+        }
+
+        private void InitializeFromMixer(ref ulong mixer)
+        {
+            if (_elements == null || _elements.Length != ElementCount)
+            {
+                _elements = new uint[ElementCount];
+            }
+
+            for (int i = 0; i < ElementCount; ++i)
+            {
+                _elements[i] = Mix32(ref mixer);
+            }
+
+            _a = Mix32(ref mixer);
+            _b = Mix32(ref mixer) | 1U;
+
+            for (int i = 0; i < WarmupRounds; ++i)
+            {
+                _ = NextUint();
+            }
+        }
+
+        private void LoadSerializedElements(byte[] payload)
+        {
+            if (_elements == null || _elements.Length != ElementCount)
+            {
+                _elements = new uint[ElementCount];
+            }
+
+            if (payload != null && payload.Length >= ElementByteSize)
+            {
+                Buffer.BlockCopy(payload, 0, _elements, 0, ElementByteSize);
+                return;
+            }
+
+            Array.Clear(_elements, 0, _elements.Length);
+        }
+    }
+}

package/Runtime/Core/Random/StormDropRandom.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: c0ca8e2683c74d1fb77e8f1f5a54b490
+timeCreated: 1761441026

package/Runtime/Core/Random/UnityRandom.cs

@@ -5,9 +5,6 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     using System.Text.Json.Serialization;
     using ProtoBuf;
 
-    [Serializable]
-    [DataContract]
-    [ProtoContract]
     /// <summary>
     /// An adapter over <c>UnityEngine.Random</c> exposing the <see cref="IRandom"/> interface.
     /// </summary>
@@ -47,6 +44,9 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     /// // Note: calling UnityEngine.Random elsewhere will affect this sequence.
     /// </code>
     /// </example>
+    [Serializable]
+    [DataContract]
+    [ProtoContract]
     public sealed class UnityRandom : AbstractRandom
     {
         public static readonly UnityRandom Instance = new();

package/Runtime/Core/Random/WyRandom.cs

@@ -7,15 +7,14 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     using System.Text.Json.Serialization;
     using ProtoBuf;
 
-    // https://github.com/cocowalla/wyhash-dotnet/blob/master/src/WyHash/WyRng.cs
-    [Serializable]
-    [DataContract]
-    [ProtoContract(SkipConstructor = true)]
     /// <summary>
     /// A wyhash-inspired PRNG variant (WyRandom) leveraging multiply-mix operations for speed and good distribution.
     /// </summary>
     /// <remarks>
     /// <para>
+    /// Reference implementation: https://github.com/cocowalla/wyhash-dotnet/blob/master/src/WyHash/WyRng.cs
+    /// </para>
+    /// <para>
     /// Designed around 64-bit multiply-and-mix steps, this generator is fast and suitable for general-purpose
     /// randomness and hashing-like use cases. It is not a cryptographic hash nor a CSPRNG.
     /// </para>
@@ -45,6 +44,9 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     /// var color = rng.NextColor(); // via RandomExtensions
     /// </code>
     /// </example>
+    [Serializable]
+    [DataContract]
+    [ProtoContract(SkipConstructor = true)]
     public sealed class WyRandom : AbstractRandom
     {
         private const ulong Prime0 = 0xa0761d6478bd642f;

package/Runtime/Core/Random/XorShiftRandom.cs

@@ -5,9 +5,6 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     using System.Text.Json.Serialization;
     using ProtoBuf;
 
-    [Serializable]
-    [DataContract]
-    [ProtoContract]
     /// <summary>
     /// A classic, extremely fast XorShift PRNG with small state and modest quality.
     /// </summary>
@@ -53,6 +50,9 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     /// var fast = XorShiftRandom.Instance; // per-thread instance
     /// </code>
     /// </example>
+    [Serializable]
+    [DataContract]
+    [ProtoContract]
     public sealed class XorShiftRandom : AbstractRandom
     {
         public static XorShiftRandom Instance => ThreadLocalRandom<XorShiftRandom>.Instance;

package/Runtime/Core/Random/XoroShiroRandom.cs

@@ -8,9 +8,6 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     using Helper;
     using ProtoBuf;
 
-    [Serializable]
-    [DataContract]
-    [ProtoContract]
     /// <summary>
     /// A fast 128-bit state Xoroshiro-based PRNG with good quality and tiny footprint.
     /// </summary>
@@ -55,6 +52,9 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     /// var replay = new XoroShiroRandom(state);
     /// </code>
     /// </example>
+    [Serializable]
+    [DataContract]
+    [ProtoContract]
     public sealed class XoroShiroRandom
         : AbstractRandom,
             IEquatable<XoroShiroRandom>,

package/Runtime/Tags/AttributeMetadataCache.cs

@@ -484,9 +484,15 @@ namespace WallstopStudios.UnityHelpers.Tags
             RelationalTypeMetadata[] relationalTypeMetadata
         )
         {
-            _allAttributeNames = allAttributeNames;
-            _typeMetadata = typeMetadata;
-            _relationalTypeMetadata = relationalTypeMetadata;
+            string[] normalizedAttributeNames = SortAttributeNames(allAttributeNames);
+            TypeFieldMetadata[] normalizedTypeMetadata = SortTypeMetadata(typeMetadata);
+            RelationalTypeMetadata[] normalizedRelationalMetadata = SortRelationalTypeMetadata(
+                relationalTypeMetadata
+            );
+
+            _allAttributeNames = normalizedAttributeNames;
+            _typeMetadata = normalizedTypeMetadata;
+            _relationalTypeMetadata = normalizedRelationalMetadata;
             _computedAllAttributeNames = null;
             _computedAllAttributeNamesIncludesTests = false;
             _typeFieldsLookup = null;
@@ -495,6 +501,309 @@ namespace WallstopStudios.UnityHelpers.Tags
             _elementTypeLookup = null;
             UnityEditor.EditorUtility.SetDirty(this);
         }
+
+        private static string[] SortAttributeNames(string[] attributeNames)
+        {
+            if (attributeNames == null || attributeNames.Length == 0)
+            {
+                return Array.Empty<string>();
+            }
+
+            string[] result = new string[attributeNames.Length];
+            Array.Copy(attributeNames, result, attributeNames.Length);
+            Array.Sort(result, StringComparer.Ordinal);
+            return result;
+        }
+
+        private static TypeFieldMetadata[] SortTypeMetadata(TypeFieldMetadata[] typeMetadata)
+        {
+            if (typeMetadata == null || typeMetadata.Length == 0)
+            {
+                return Array.Empty<TypeFieldMetadata>();
+            }
+
+            int nonNullCount = 0;
+            for (int i = 0; i < typeMetadata.Length; i++)
+            {
+                if (typeMetadata[i] != null)
+                {
+                    nonNullCount++;
+                }
+            }
+
+            if (nonNullCount == 0)
+            {
+                return Array.Empty<TypeFieldMetadata>();
+            }
+
+            TypeFieldMetadata[] result = new TypeFieldMetadata[nonNullCount];
+            int resultIndex = 0;
+            for (int i = 0; i < typeMetadata.Length; i++)
+            {
+                TypeFieldMetadata metadata = typeMetadata[i];
+                if (metadata == null)
+                {
+                    continue;
+                }
+
+                string typeName = metadata.typeName ?? string.Empty;
+                string[] fieldNames = metadata.fieldNames ?? Array.Empty<string>();
+                string[] sortedFieldNames =
+                    fieldNames.Length == 0 ? Array.Empty<string>() : CopyAndSort(fieldNames);
+
+                result[resultIndex] = new TypeFieldMetadata(typeName, sortedFieldNames);
+                resultIndex++;
+            }
+
+            Array.Sort(result, CompareTypeFieldMetadata);
+            return result;
+        }
+
+        private static RelationalTypeMetadata[] SortRelationalTypeMetadata(
+            RelationalTypeMetadata[] relationalTypeMetadata
+        )
+        {
+            if (relationalTypeMetadata == null || relationalTypeMetadata.Length == 0)
+            {
+                return Array.Empty<RelationalTypeMetadata>();
+            }
+
+            int nonNullCount = 0;
+            for (int i = 0; i < relationalTypeMetadata.Length; i++)
+            {
+                if (relationalTypeMetadata[i] != null)
+                {
+                    nonNullCount++;
+                }
+            }
+
+            if (nonNullCount == 0)
+            {
+                return Array.Empty<RelationalTypeMetadata>();
+            }
+
+            RelationalTypeMetadata[] result = new RelationalTypeMetadata[nonNullCount];
+            int resultIndex = 0;
+            for (int i = 0; i < relationalTypeMetadata.Length; i++)
+            {
+                RelationalTypeMetadata metadata = relationalTypeMetadata[i];
+                if (metadata == null)
+                {
+                    continue;
+                }
+
+                string typeName = metadata.typeName ?? string.Empty;
+                RelationalFieldMetadata[] sortedFields = SortRelationalFields(metadata.fields);
+                result[resultIndex] = new RelationalTypeMetadata(typeName, sortedFields);
+                resultIndex++;
+            }
+
+            Array.Sort(result, CompareRelationalTypeMetadata);
+            return result;
+        }
+
+        private static RelationalFieldMetadata[] SortRelationalFields(
+            RelationalFieldMetadata[] relationalFields
+        )
+        {
+            if (relationalFields == null || relationalFields.Length == 0)
+            {
+                return Array.Empty<RelationalFieldMetadata>();
+            }
+
+            int nonNullCount = 0;
+            for (int i = 0; i < relationalFields.Length; i++)
+            {
+                if (relationalFields[i] != null)
+                {
+                    nonNullCount++;
+                }
+            }
+
+            if (nonNullCount == 0)
+            {
+                return Array.Empty<RelationalFieldMetadata>();
+            }
+
+            RelationalFieldMetadata[] result = new RelationalFieldMetadata[nonNullCount];
+            int resultIndex = 0;
+            for (int i = 0; i < relationalFields.Length; i++)
+            {
+                RelationalFieldMetadata field = relationalFields[i];
+                if (field == null)
+                {
+                    continue;
+                }
+
+                result[resultIndex] = new RelationalFieldMetadata(
+                    field.fieldName,
+                    field.attributeKind,
+                    field.fieldKind,
+                    field.elementTypeName,
+                    field.isInterface
+                );
+                resultIndex++;
+            }
+
+            Array.Sort(result, CompareRelationalFieldMetadata);
+            return result;
+        }
+
+        private static string[] CopyAndSort(string[] values)
+        {
+            string[] result = new string[values.Length];
+            Array.Copy(values, result, values.Length);
+            Array.Sort(result, StringComparer.Ordinal);
+            return result;
+        }
+
+        private static int CompareTypeFieldMetadata(TypeFieldMetadata left, TypeFieldMetadata right)
+        {
+            if (ReferenceEquals(left, right))
+            {
+                return 0;
+            }
+
+            if (left == null)
+            {
+                return -1;
+            }
+
+            if (right == null)
+            {
+                return 1;
+            }
+
+            int typeNameComparison = string.CompareOrdinal(left.typeName, right.typeName);
+            if (typeNameComparison != 0)
+            {
+                return typeNameComparison;
+            }
+
+            string[] leftFields = left.fieldNames ?? Array.Empty<string>();
+            string[] rightFields = right.fieldNames ?? Array.Empty<string>();
+
+            int lengthComparison = leftFields.Length.CompareTo(rightFields.Length);
+            if (lengthComparison != 0)
+            {
+                return lengthComparison;
+            }
+
+            for (int i = 0; i < leftFields.Length; i++)
+            {
+                int fieldComparison = string.CompareOrdinal(leftFields[i], rightFields[i]);
+                if (fieldComparison != 0)
+                {
+                    return fieldComparison;
+                }
+            }
+
+            return 0;
+        }
+
+        private static int CompareRelationalTypeMetadata(
+            RelationalTypeMetadata left,
+            RelationalTypeMetadata right
+        )
+        {
+            if (ReferenceEquals(left, right))
+            {
+                return 0;
+            }
+
+            if (left == null)
+            {
+                return -1;
+            }
+
+            if (right == null)
+            {
+                return 1;
+            }
+
+            int typeNameComparison = string.CompareOrdinal(left.typeName, right.typeName);
+            if (typeNameComparison != 0)
+            {
+                return typeNameComparison;
+            }
+
+            RelationalFieldMetadata[] leftFields =
+                left.fields ?? Array.Empty<RelationalFieldMetadata>();
+            RelationalFieldMetadata[] rightFields =
+                right.fields ?? Array.Empty<RelationalFieldMetadata>();
+
+            int lengthComparison = leftFields.Length.CompareTo(rightFields.Length);
+            if (lengthComparison != 0)
+            {
+                return lengthComparison;
+            }
+
+            for (int i = 0; i < leftFields.Length; i++)
+            {
+                int fieldComparison = CompareRelationalFieldMetadata(leftFields[i], rightFields[i]);
+                if (fieldComparison != 0)
+                {
+                    return fieldComparison;
+                }
+            }
+
+            return 0;
+        }
+
+        private static int CompareRelationalFieldMetadata(
+            RelationalFieldMetadata left,
+            RelationalFieldMetadata right
+        )
+        {
+            if (ReferenceEquals(left, right))
+            {
+                return 0;
+            }
+
+            if (left == null)
+            {
+                return -1;
+            }
+
+            if (right == null)
+            {
+                return 1;
+            }
+
+            int fieldNameComparison = string.CompareOrdinal(left.fieldName, right.fieldName);
+            if (fieldNameComparison != 0)
+            {
+                return fieldNameComparison;
+            }
+
+            int attributeComparison = left.attributeKind.CompareTo(right.attributeKind);
+            if (attributeComparison != 0)
+            {
+                return attributeComparison;
+            }
+
+            int fieldKindComparison = left.fieldKind.CompareTo(right.fieldKind);
+            if (fieldKindComparison != 0)
+            {
+                return fieldKindComparison;
+            }
+
+            int elementTypeComparison = string.CompareOrdinal(
+                left.elementTypeName,
+                right.elementTypeName
+            );
+            if (elementTypeComparison != 0)
+            {
+                return elementTypeComparison;
+            }
+
+            if (left.isInterface == right.isInterface)
+            {
+                return 0;
+            }
+
+            return left.isInterface ? -1 : 1;
+        }
 #endif
     }
 }