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

package/Runtime/Core/Helper/UnityMainThreadDispatcher.cs

@@ -105,8 +105,7 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
         /// </summary>
         public System.Threading.Tasks.Task RunAsync(Action action)
         {
-            TaskCompletionSource<bool> tcs =
-                new System.Threading.Tasks.TaskCompletionSource<bool>();
+            TaskCompletionSource<bool> tcs = new();
             RunOnMainThread(() =>
             {
                 try
@@ -127,7 +126,7 @@ namespace WallstopStudios.UnityHelpers.Core.Helper
         /// </summary>
         public System.Threading.Tasks.Task<T> Post<T>(Func<T> func)
         {
-            TaskCompletionSource<T> tcs = new System.Threading.Tasks.TaskCompletionSource<T>();
+            TaskCompletionSource<T> tcs = new();
             RunOnMainThread(() =>
             {
                 try

package/Runtime/Core/Random/AbstractRandom.cs

@@ -15,9 +15,6 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     using Extension;
 #endif
 
-    [Serializable]
-    [DataContract]
-    [ProtoContract]
     /// <summary>
     /// Common abstract base for all <see cref="IRandom"/> implementations with protobuf support.
     /// </summary>
@@ -58,6 +55,9 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     /// then use Serializer.ProtoDeserialize&lt;IRandom&gt;.</description></item>
     /// </list>
     /// </remarks>
+    [Serializable]
+    [DataContract]
+    [ProtoContract]
     [ProtoInclude(100, typeof(DotNetRandom))]
     [ProtoInclude(101, typeof(PcgRandom))]
     [ProtoInclude(102, typeof(XorShiftRandom))]
@@ -70,6 +70,9 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     [ProtoInclude(109, typeof(RomuDuo))]
     [ProtoInclude(110, typeof(SplitMix64))]
     [ProtoInclude(111, typeof(IllusionFlow))]
+    [ProtoInclude(112, typeof(FlurryBurstRandom))]
+    [ProtoInclude(113, typeof(PhotonSpinRandom))]
+    [ProtoInclude(114, typeof(StormDropRandom))]
     public abstract class AbstractRandom : IRandom
     {
 #if SINGLE_THREADED
@@ -107,13 +110,37 @@ namespace WallstopStudios.UnityHelpers.Core.Random
         protected int _byteCount;
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        protected RandomState BuildState(ulong state1, ulong state2 = 0, byte[] payload = null)
+        protected RandomState BuildState(
+            ulong state1,
+            ulong state2 = 0,
+            IReadOnlyList<byte> payload = null
+        )
         {
+            byte[] payloadCopy = null;
+            if (payload != null)
+            {
+                if (payload is byte[] payloadArray)
+                {
+                    int length = payloadArray.Length;
+                    payloadCopy = new byte[length];
+                    Buffer.BlockCopy(payloadArray, 0, payloadCopy, 0, length);
+                }
+                else
+                {
+                    int count = payload.Count;
+                    payloadCopy = new byte[count];
+                    for (int i = 0; i < count; ++i)
+                    {
+                        payloadCopy[i] = payload[i];
+                    }
+                }
+            }
+
             return new RandomState(
                 state1,
                 state2,
                 _cachedGaussian,
-                payload: payload,
+                payload: payloadCopy,
                 bitBuffer: _bitBuffer,
                 bitCount: _bitCount,
                 byteBuffer: _byteBuffer,
@@ -1314,5 +1341,25 @@ namespace WallstopStudios.UnityHelpers.Core.Random
         }
 
         public abstract IRandom Copy();
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        protected internal static uint RotateLeft(uint value, int count)
+        {
+            return (value << count) | (value >> (32 - count));
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        protected internal static uint Mix32(ref ulong state)
+        {
+            unchecked
+            {
+                state += 0x9E3779B97F4A7C15UL;
+                ulong z = state;
+                z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL;
+                z = (z ^ (z >> 27)) * 0x94D049BB133111EBUL;
+                z ^= z >> 31;
+                return (uint)z;
+            }
+        }
     }
 }

package/Runtime/Core/Random/DotNetRandom.cs

@@ -5,9 +5,6 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     using System.Text.Json.Serialization;
     using ProtoBuf;
 
-    [Serializable]
-    [DataContract]
-    [ProtoContract(SkipConstructor = true)]
     /// <summary>
     /// A thin wrapper around <c>System.Random</c> that exposes the <see cref="IRandom"/> API and supports state capture.
     /// </summary>
@@ -46,6 +43,9 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     /// float f = compat.NextFloat();
     /// </code>
     /// </example>
+    [Serializable]
+    [DataContract]
+    [ProtoContract(SkipConstructor = true)]
     public sealed class DotNetRandom : AbstractRandom
     {
         public static DotNetRandom Instance => ThreadLocalRandom<DotNetRandom>.Instance;

package/Runtime/Core/Random/FlurryBurstRandom.cs

@@ -0,0 +1,285 @@
+namespace WallstopStudios.UnityHelpers.Core.Random
+{
+    using System;
+    using System.Buffers.Binary;
+    using System.Runtime.CompilerServices;
+    using System.Runtime.Serialization;
+    using System.Text.Json.Serialization;
+    using Extension;
+    using Helper;
+    using ProtoBuf;
+    using WallstopStudios.UnityHelpers.Utils;
+
+    /// <summary>
+    /// FlurryBurst32: a six-word ARX-style generator offering high quality and excellent parallel sequencing.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// https://github.com/wileylooper/flurryburst
+    /// Based on <c>wileylooper/flurryburst</c>, this implementation captures the 32-bit variant that balances
+    /// speed, period (~2<sup>128</sup>) and state size for gameplay workloads. It is suitable as a drop-in
+    /// alternative to Xoshiro128** and similar families, while retaining deterministic serialization support.
+    /// </para>
+    /// <para>Pros:</para>
+    /// <list type="bullet">
+    /// <item><description>Small state (6×32-bit) with excellent statistical behaviour.</description></item>
+    /// <item><description>Deterministic snapshots via <see cref="RandomState"/> and protobuf/JSON.</description></item>
+    /// <item><description>Easy to create parallel streams by varying the <c>d</c> word.</description></item>
+    /// </list>
+    /// <para>Cons:</para>
+    /// <list type="bullet">
+    /// <item><description>Not cryptographically secure.</description></item>
+    /// <item><description>Requires a short warm-up (performed automatically) to avoid transient bias.</description></item>
+    /// </list>
+    /// <para>When to use:</para>
+    /// <list type="bullet">
+    /// <item><description>Deterministic gameplay, procedural content, Monte-Carlo style sampling.</description></item>
+    /// </list>
+    /// <para>When not to use:</para>
+    /// <list type="bullet">
+    /// <item><description>Security/adversarial contexts.</description></item>
+    /// </list>
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// using WallstopStudios.UnityHelpers.Core.Random;
+    ///
+    /// IRandom rng = new FlurryBurstRandom(seed: 123u);
+    /// int value = rng.Next(0, 100);
+    /// float weight = rng.NextFloat();
+    /// </code>
+    /// </example>
+    [Serializable]
+    [DataContract]
+    [ProtoContract]
+    public sealed class FlurryBurstRandom
+        : AbstractRandom,
+            IEquatable<FlurryBurstRandom>,
+            IComparable,
+            IComparable<FlurryBurstRandom>
+    {
+        private const uint Increment = 1_111_111_111U;
+        private const int PayloadByteCount = sizeof(uint) * 2;
+
+        public static FlurryBurstRandom Instance => ThreadLocalRandom<FlurryBurstRandom>.Instance;
+
+        public override RandomState InternalState
+        {
+            get
+            {
+                ulong state1 = ((ulong)_a << 32) | _b;
+                ulong state2 = ((ulong)_c << 32) | _d;
+                using PooledResource<byte[]> payloadLease = WallstopArrayPool<byte>.Get(
+                    PayloadByteCount,
+                    out byte[] buffer
+                );
+                Span<byte> payload = buffer.AsSpan(0, PayloadByteCount);
+                BinaryPrimitives.WriteUInt32LittleEndian(payload.Slice(0, sizeof(uint)), _e);
+                BinaryPrimitives.WriteUInt32LittleEndian(
+                    payload.Slice(sizeof(uint), sizeof(uint)),
+                    _f
+                );
+
+                return BuildState(
+                    state1,
+                    state2,
+                    new ArraySegment<byte>(buffer, 0, PayloadByteCount)
+                );
+            }
+        }
+
+        [ProtoMember(6)]
+        private uint _a;
+
+        [ProtoMember(7)]
+        private uint _b;
+
+        [ProtoMember(8)]
+        private uint _c;
+
+        [ProtoMember(9)]
+        private uint _d;
+
+        [ProtoMember(10)]
+        private uint _e;
+
+        [ProtoMember(11)]
+        private uint _f;
+
+        public FlurryBurstRandom()
+            : this(Guid.NewGuid()) { }
+
+        public FlurryBurstRandom(Guid guid)
+        {
+            InitializeFromGuid(guid);
+        }
+
+        [JsonConstructor]
+        public FlurryBurstRandom(RandomState internalState)
+        {
+            ulong state1 = internalState.State1;
+            ulong state2 = internalState.State2;
+            _a = (uint)(state1 >> 32);
+            _b = (uint)state1;
+            _c = (uint)(state2 >> 32);
+            _d = (uint)state2;
+
+            byte[] payload = internalState._payload;
+            if (payload != null && payload.Length >= sizeof(uint) * 2)
+            {
+                _e = BinaryPrimitives.ReadUInt32LittleEndian(payload.AsSpan(0, sizeof(uint)));
+                _f = BinaryPrimitives.ReadUInt32LittleEndian(
+                    payload.AsSpan(sizeof(uint), sizeof(uint))
+                );
+            }
+            else
+            {
+                _e = 0;
+                _f = 0;
+            }
+
+            RestoreCommonState(internalState);
+        }
+
+        public override uint NextUint()
+        {
+            unchecked
+            {
+                uint mix = RotateLeft(_a, 13);
+
+                _a = _b;
+                _b = _e;
+                _c += _d;
+                _d += _b;
+                _e = _f + Increment;
+                _f = _c ^ mix;
+
+                return (_e >> 1) ^ _f;
+            }
+        }
+
+        public override IRandom Copy()
+        {
+            return new FlurryBurstRandom(InternalState);
+        }
+
+        public override bool Equals(object obj)
+        {
+            return Equals(obj as FlurryBurstRandom);
+        }
+
+        public bool Equals(FlurryBurstRandom other)
+        {
+            if (other == null)
+            {
+                return false;
+            }
+
+            // ReSharper disable once CompareOfFloatsByEqualityOperator
+            return _a == other._a
+                && _b == other._b
+                && _c == other._c
+                && _d == other._d
+                && _e == other._e
+                && _f == other._f
+                && _cachedGaussian == other._cachedGaussian;
+        }
+
+        public override int GetHashCode()
+        {
+            return Objects.HashCode(_a, _b, _c, _d, _e, _f);
+        }
+
+        public override string ToString()
+        {
+            return this.ToJson();
+        }
+
+        public int CompareTo(object obj)
+        {
+            return CompareTo(obj as FlurryBurstRandom);
+        }
+
+        public int CompareTo(FlurryBurstRandom 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;
+            }
+
+            comparison = _c.CompareTo(other._c);
+            if (comparison != 0)
+            {
+                return comparison;
+            }
+
+            comparison = _d.CompareTo(other._d);
+            if (comparison != 0)
+            {
+                return comparison;
+            }
+
+            comparison = _e.CompareTo(other._e);
+            if (comparison != 0)
+            {
+                return comparison;
+            }
+
+            return _f.CompareTo(other._f);
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        private static uint RotateLeft(uint value, int count)
+        {
+            return (value << count) | (value >> (32 - count));
+        }
+
+        private void InitializeFromGuid(Guid guid)
+        {
+            (ulong seed0, ulong seed1) = RandomUtilities.GuidToUInt64Pair(guid);
+            InitializeFromUlongs(seed0, seed1);
+        }
+
+        private void InitializeFromUlongs(ulong seed0, ulong seed1)
+        {
+            ulong mixer = seed0 ^ (seed1 << 1) ^ 0x9E3779B97F4A7C15UL;
+
+            _a = Mix(ref mixer);
+            _b = Mix(ref mixer);
+            _c = Mix(ref mixer);
+            _d = Mix(ref mixer);
+            if (_d == 0)
+            {
+                _d = 1;
+            }
+            _e = Mix(ref mixer);
+            _f = Mix(ref mixer);
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        private static uint Mix(ref ulong state)
+        {
+            unchecked
+            {
+                state += 0x9E3779B97F4A7C15UL;
+                ulong z = state;
+                z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL;
+                z = (z ^ (z >> 27)) * 0x94D049BB133111EBUL;
+                z ^= z >> 31;
+                return (uint)z;
+            }
+        }
+    }
+}

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

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 83db2e5bc6be4c03966c71bbe032a519
+timeCreated: 1761435962

package/Runtime/Core/Random/IllusionFlow.cs

@@ -13,9 +13,6 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     using System.Text.Json.Serialization;
     using ProtoBuf;
 
-    [Serializable]
-    [DataContract]
-    [ProtoContract]
     /// <summary>
     /// IllusionFlow: a modern, high-performance PRNG building on Xoroshiro concepts with additional state and mixing.
     /// </summary>
@@ -60,6 +57,9 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     /// var replay = new IllusionFlow(state);
     /// </code>
     /// </example>
+    [Serializable]
+    [DataContract]
+    [ProtoContract]
     public sealed class IllusionFlow : AbstractRandom
     {
         private const int UintByteCount = sizeof(uint) * 8;

package/Runtime/Core/Random/LinearCongruentialGenerator.cs

@@ -5,9 +5,6 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     using System.Text.Json.Serialization;
     using ProtoBuf;
 
-    [Serializable]
-    [DataContract]
-    [ProtoContract]
     /// <summary>
     /// A simple Linear Congruential Generator (LCG): extremely fast with low-quality randomness.
     /// </summary>
@@ -43,6 +40,9 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     /// // Prefer PCG or IllusionFlow for production gameplay.
     /// </code>
     /// </example>
+    [Serializable]
+    [DataContract]
+    [ProtoContract]
     public sealed class LinearCongruentialGenerator : AbstractRandom
     {
         public static LinearCongruentialGenerator Instance =>

package/Runtime/Core/Random/PcgRandom.cs

@@ -5,17 +5,14 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     using System.Text.Json.Serialization;
     using ProtoBuf;
 
-    /// <summary>
-    ///     Implementation based off of the reference PCG Random, found here: https://www.pcg-random.org/index.html
-    /// </summary>
-    [Serializable]
-    [DataContract]
-    [ProtoContract]
     /// <summary>
     /// A high-quality, small-state pseudo-random number generator based on the PCG family.
     /// </summary>
     /// <remarks>
     /// <para>
+    /// Implementation based off of the reference PCG Random, found here: https://www.pcg-random.org/index.html
+    /// </para>
+    /// <para>
     /// PCG (Permuted Congruential Generator) offers excellent statistical quality with very small state
     /// and extremely fast generation. This implementation uses a 64-bit state with 32-bit outputs and
     /// an increment (stream selector) to avoid overlapping sequences when constructing multiple instances.
@@ -96,6 +93,9 @@ namespace WallstopStudios.UnityHelpers.Core.Random
     /// // var index = rng.NextWeightedIndex(new float[] { 0.1f, 0.3f, 0.6f });
     /// </code>
     /// </example>
+    [Serializable]
+    [DataContract]
+    [ProtoContract]
     public sealed class PcgRandom
         : AbstractRandom,
             IEquatable<PcgRandom>,