com.wallstop-studios.unity-helpers 2.0.0-rc04 → 2.0.0-rc06

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

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 5041bafe46dc450bb37153e394011636
+timeCreated: 1732564259

package/Runtime/Core/Random/PcgRandom.cs

@@ -9,21 +9,20 @@
     /// </summary>
     [Serializable]
     [DataContract]
-    public sealed class PcgRandom : AbstractRandom, IEquatable<PcgRandom>, IComparable, IComparable<PcgRandom>
+    public sealed class PcgRandom
+        : AbstractRandom,
+            IEquatable<PcgRandom>,
+            IComparable,
+            IComparable<PcgRandom>
     {
         public static IRandom Instance => ThreadLocalRandom<PcgRandom>.Instance;
 
-        [JsonInclude]
-        [JsonPropertyName("Increment")]
-        [DataMember(Name = "Increment")]
         internal readonly ulong _increment;
 
-        [JsonInclude]
-        [JsonPropertyName("State")]
-        [DataMember(Name = "State")]
         internal ulong _state;
 
-        public PcgRandom() : this(Guid.NewGuid()) { }
+        public PcgRandom()
+            : this(Guid.NewGuid()) { }
 
         public PcgRandom(Guid guid)
         {
@@ -32,14 +31,14 @@
             _increment = BitConverter.ToUInt64(guidArray, sizeof(ulong));
         }
 
-        public PcgRandom(RandomState randomState)
+        [JsonConstructor]
+        public PcgRandom(RandomState internalState)
         {
-            _state = randomState.State1;
-            _increment = randomState.State2;
-            _cachedGaussian = randomState.Gaussian;
+            _state = internalState.State1;
+            _increment = internalState.State2;
+            _cachedGaussian = internalState.Gaussian;
         }
 
-        [JsonConstructor]
         public PcgRandom(ulong increment, ulong state)
         {
             _increment = increment;
@@ -76,7 +75,14 @@
             }
 
             // ReSharper disable once CompareOfFloatsByEqualityOperator
-            return _increment == other._increment && _state == other._state && _cachedGaussian == other._cachedGaussian;
+            return _increment == other._increment
+                && _state == other._state
+                && _cachedGaussian == other._cachedGaussian;
+        }
+
+        public override bool Equals(object obj)
+        {
+            return Equals(obj as PcgRandom);
         }
 
         public int CompareTo(PcgRandom other)
@@ -120,9 +126,9 @@
             return _cachedGaussian.Value.CompareTo(other._cachedGaussian.Value);
         }
 
-        public override bool Equals(object other)
+        public int CompareTo(object obj)
         {
-            return Equals(other as PcgRandom);
+            return CompareTo(obj as PcgRandom);
         }
 
         public override int GetHashCode()
@@ -135,14 +141,9 @@
             return $"{{\"Increment\": {_increment}, \"State\": {_state}}}";
         }
 
-        public int CompareTo(object other)
-        {
-            return CompareTo(other as PcgRandom);
-        }
-
         public override IRandom Copy()
         {
             return new PcgRandom(InternalState);
         }
     }
-}
+}

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

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: 5206bd9e6b6b7a24cb5a88faba0e4777
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 5206bd9e6b6b7a24cb5a88faba0e4777
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/Random/RandomState.cs

@@ -1,15 +1,20 @@
 namespace UnityHelpers.Core.Random
 {
     using System;
+    using System.Linq;
+    using System.Runtime.Serialization;
+    using System.Text.Json.Serialization;
     using Extension;
     using Helper;
     using ProtoBuf;
 
     [Serializable]
+    [DataContract]
     [ProtoContract]
     public struct RandomState : IEquatable<RandomState>
     {
         public ulong State1 => _state1;
+
         public ulong State2 => _state2;
 
         public double? Gaussian
@@ -25,8 +30,11 @@
             }
         }
 
+        public byte[] Payload => _payload;
+
         [ProtoMember(1)]
         private ulong _state1;
+
         [ProtoMember(2)]
         private ulong _state2;
 
@@ -36,15 +44,31 @@
         [ProtoMember(4)]
         private double _gaussian;
 
+        [ProtoMember(5)]
+        private byte[] _payload;
+
         private int _hashCode;
 
-        public RandomState(ulong state1, ulong state2 = 0, double? gaussian = null)
+        [JsonConstructor]
+        public RandomState(
+            ulong state1,
+            ulong state2 = 0,
+            double? gaussian = null,
+            byte[] payload = null
+        )
         {
             _state1 = state1;
             _state2 = state2;
             _hasGaussian = gaussian.HasValue;
             _gaussian = gaussian ?? 0;
-            _hashCode = Objects.ValueTypeHashCode(state1, state2, _hasGaussian, _gaussian);
+            _payload = payload?.ToArray();
+            _hashCode = Objects.ValueTypeHashCode(
+                state1,
+                state2,
+                _hasGaussian,
+                _gaussian,
+                _payload != null
+            );
         }
 
         public RandomState(Guid guid)
@@ -54,7 +78,14 @@
             _state2 = BitConverter.ToUInt64(guidBytes, sizeof(ulong));
             _hasGaussian = false;
             _gaussian = 0;
-            _hashCode = Objects.ValueTypeHashCode(_state1, _state2, _hasGaussian, _gaussian);
+            _payload = null;
+            _hashCode = Objects.ValueTypeHashCode(
+                _state1,
+                _state2,
+                _hasGaussian,
+                _gaussian,
+                _payload != null
+            );
         }
 
         [ProtoAfterDeserialization]
@@ -71,14 +102,22 @@
         public bool Equals(RandomState other)
         {
             // ReSharper disable once CompareOfFloatsByEqualityOperator
-            return _state1 == other._state1 && _state2 == other._state2 && _hasGaussian == other._hasGaussian && (!_hasGaussian || _gaussian == other._gaussian);
+            return _state1 == other._state1
+                && _state2 == other._state2
+                && _hasGaussian == other._hasGaussian
+                && (!_hasGaussian || _gaussian == other._gaussian);
         }
 
         public override int GetHashCode()
         {
             if (_hashCode == 0)
             {
-                return _hashCode = Objects.ValueTypeHashCode(_state1, _state2, _hasGaussian, _gaussian);
+                return _hashCode = Objects.ValueTypeHashCode(
+                    _state1,
+                    _state2,
+                    _hasGaussian,
+                    _gaussian
+                );
             }
 
             return _hashCode;

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

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: 41d80559b2118924ba94e768d005a4e6
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 41d80559b2118924ba94e768d005a4e6
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/Random/SquirrelRandom.cs

@@ -1,8 +1,12 @@
 namespace UnityHelpers.Core.Random
 {
     using System;
+    using System.Runtime.Serialization;
+    using System.Text.Json.Serialization;
 
     // https://youtu.be/LWFzPP8ZbdU?t=2673
+    [DataContract]
+    [Serializable]
     public sealed class SquirrelRandom : AbstractRandom
     {
         private const uint BitNoise1 = 0xB5297A4D;
@@ -10,28 +14,27 @@
         private const uint BitNoise3 = 0x1B56C4E9;
         private const int LargePrime = 198491317;
 
-        public static readonly SquirrelRandom Instance = new();
+        public static readonly SquirrelRandom Instance = ThreadLocalRandom<SquirrelRandom>.Instance;
+
+        public override RandomState InternalState => new(_position, gaussian: _cachedGaussian);
 
         private uint _position;
 
-        public SquirrelRandom() : this(Guid.NewGuid().GetHashCode())
-        {
-
-        }
+        public SquirrelRandom()
+            : this(Guid.NewGuid().GetHashCode()) { }
 
         public SquirrelRandom(int seed)
         {
             _position = unchecked((uint)seed);
         }
 
-        public SquirrelRandom(RandomState randomState)
+        [JsonConstructor]
+        public SquirrelRandom(RandomState internalState)
         {
-            _position = unchecked((uint)randomState.State1);
-            _cachedGaussian = randomState.Gaussian;
+            _position = unchecked((uint)internalState.State1);
+            _cachedGaussian = internalState.Gaussian;
         }
 
-        public override RandomState InternalState => new(_position, gaussian: _cachedGaussian);
-
         public override uint NextUint()
         {
             return _position = NextUintInternal(_position);

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

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: 3f2a41ab545b08e4b9bd2a8025bf839a
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 3f2a41ab545b08e4b9bd2a8025bf839a
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/Random/SystemRandom.cs

@@ -1,25 +1,38 @@
 namespace UnityHelpers.Core.Random
 {
     using System;
+    using System.Runtime.Serialization;
+    using System.Text.Json.Serialization;
+    using Helper;
 
     /// <summary>
     ///     Implementation dependent upon .Net's Random class.
     /// </summary>
+    [Serializable]
+    [DataContract]
     public sealed class SystemRandom : AbstractRandom
     {
+        public static IRandom Instance => ThreadLocalRandom<SystemRandom>.Instance;
+
+        public override RandomState InternalState =>
+            new(
+                unchecked((ulong)inext),
+                unchecked((ulong)inextp),
+                _cachedGaussian,
+                ArrayConverter.IntArrayToByteArrayBlockCopy(SeedArray)
+            );
+
         /*
             Copied from Random.cs source. Apparently it isn't guaranteed to be the
-            same across platforms and we depend on that.
+            same across platforms, a fact which defeats the purpose of these serializable
+            randoms.
          */
         private int inext;
         private int inextp;
         private readonly int[] SeedArray = new int[56];
 
-        public static IRandom Instance => ThreadLocalRandom<SystemRandom>.Instance;
-
-        public SystemRandom() : this (Environment.TickCount)
-        {
-        }
+        public SystemRandom()
+            : this(Guid.NewGuid().GetHashCode()) { }
 
         public SystemRandom(int seed)
         {
@@ -48,15 +61,18 @@
             this.inextp = 21;
         }
 
-        public SystemRandom(RandomState randomState)
+        [JsonConstructor]
+        public SystemRandom(RandomState internalState)
         {
-            inext = unchecked((int)randomState.State1);
-            inextp = unchecked((int)randomState.State2);
-            _cachedGaussian = randomState.Gaussian;
+            unchecked
+            {
+                inext = (int)internalState.State1;
+                inextp = (int)internalState.State2;
+            }
+            _cachedGaussian = internalState.Gaussian;
+            SeedArray = ArrayConverter.ByteArrayToIntArrayBlockCopy(internalState.Payload);
         }
 
-        public override RandomState InternalState => new(unchecked((ulong)inext), unchecked((ulong)inextp), _cachedGaussian);
-
         public override uint NextUint()
         {
             int inext = this.inext;
@@ -75,7 +91,7 @@
             this.SeedArray[index1] = num;
             this.inext = index1;
             this.inextp = index2;
-            return unchecked((uint) num);
+            return unchecked((uint)num);
         }
 
         public override double NextDouble()
@@ -84,15 +100,14 @@
             do
             {
                 generated = unchecked((int)NextUint()) * 4.6566128752458E-10;
-            }
-            while (generated < 0 || 1 <= generated);
+            } while (generated < 0 || 1 <= generated);
 
             return generated;
         }
 
         public override float NextFloat()
         {
-            return (float) NextDouble();
+            return (float)NextDouble();
         }
 
         public override IRandom Copy()

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

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: d00769758e05b2f478ea85ce53650d44
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: d00769758e05b2f478ea85ce53650d44
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/Random/ThreadLocalRandom.cs

@@ -2,7 +2,8 @@
 {
     using System.Threading;
 
-    public static class ThreadLocalRandom<T> where T : IRandom, new()
+    public static class ThreadLocalRandom<T>
+        where T : IRandom, new()
     {
         private static readonly ThreadLocal<T> RandomCache = new ThreadLocal<T>(() => new T());
 

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

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: 0d9f5b15009b2ff48ba3d66fd8a7fc53
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 0d9f5b15009b2ff48ba3d66fd8a7fc53
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/Random/UnityRandom.cs

@@ -1,16 +1,49 @@
 namespace UnityHelpers.Core.Random
 {
     using System;
+    using System.Runtime.Serialization;
+    using System.Text.Json.Serialization;
 
+    [Serializable]
+    [DataContract]
     public sealed class UnityRandom : AbstractRandom
     {
-        public static readonly UnityRandom Instance = new UnityRandom();
+        public static readonly UnityRandom Instance = new();
 
-        private UnityRandom()
+        public override RandomState InternalState
         {
+            get
+            {
+                unchecked
+                {
+                    return new RandomState(
+                        (ulong)(_seed ?? 0),
+                        gaussian: _seed != null ? 0.0 : null
+                    );
+                }
+            }
+        }
+
+        private readonly int? _seed;
+
+        public UnityRandom(int? seed = null)
+        {
+            if (seed != null)
+            {
+                _seed = seed.Value;
+                UnityEngine.Random.InitState(seed.Value);
+            }
+        }
+
+        [JsonConstructor]
+        public UnityRandom(RandomState internalState)
+        {
+            unchecked
+            {
+                _seed = internalState.Gaussian != null ? (int)internalState.State1 : null;
+            }
         }
 
-        public override RandomState InternalState => throw new NotSupportedException("Unity Random does not expose its internal state");
         public override uint NextUint()
         {
             return unchecked((uint)UnityEngine.Random.Range(int.MinValue, int.MaxValue));
@@ -18,7 +51,7 @@
 
         public override IRandom Copy()
         {
-            throw new NotSupportedException("Unity Random does not support copying / seeding");
+            return new UnityRandom(_seed);
         }
     }
 }

package/Runtime/Core/Random/WyRandom.cs

@@ -0,0 +1,121 @@
+namespace UnityHelpers.Core.Random
+{
+    using System;
+    using System.Diagnostics.CodeAnalysis;
+    using System.Runtime.CompilerServices;
+    using System.Runtime.Serialization;
+    using System.Text.Json.Serialization;
+
+    // https://github.com/cocowalla/wyhash-dotnet/blob/master/src/WyHash/WyRng.cs
+    [Serializable]
+    [DataContract]
+    public sealed class WyRandom : AbstractRandom
+    {
+        private const ulong Prime0 = 0xa0761d6478bd642f;
+        private const ulong Prime1 = 0xe7037ed1a0b428db;
+
+        public static IRandom Instance => ThreadLocalRandom<WyRandom>.Instance;
+
+        public override RandomState InternalState => new RandomState(_state);
+
+        private ulong _state;
+
+        public WyRandom()
+            : this(Guid.NewGuid()) { }
+
+        public WyRandom(Guid guid)
+        {
+            byte[] guidArray = guid.ToByteArray();
+            _state = BitConverter.ToUInt64(guidArray, 0);
+        }
+
+        [JsonConstructor]
+        public WyRandom(RandomState internalState)
+        {
+            _state = internalState.State1;
+        }
+
+        public WyRandom(ulong state)
+        {
+            _state = state;
+        }
+
+        public override uint NextUint()
+        {
+            unchecked
+            {
+                _state += Prime0;
+                return (uint)Mum(_state ^ Prime1, _state);
+            }
+        }
+
+        /// <summary>
+        /// Perform a MUM (MUltiply and Mix) operation. Multiplies 2 unsigned 64-bit integers, then combines the
+        /// hi and lo bits of the resulting 128-bit integer using XOR
+        /// </summary>
+        /// <param name="x">First 64-bit integer</param>
+        /// <param name="y">Second 64-bit integer</param>
+        /// <returns>Result of the MUM (MUltiply and Mix) operation</returns>
+        private static ulong Mum(ulong x, ulong y)
+        {
+            (ulong hi, ulong lo) = Multiply64(x, y);
+            return hi ^ lo;
+        }
+
+        /// <summary>
+        /// Multiplies 2 unsigned 64-bit integers, returning the result in 2 ulongs representing the hi and lo bits
+        /// of the resulting 128-bit integer
+        ///
+        /// Source: https://stackoverflow.com/a/51587262/25758, but with a faster lo calculation
+        /// </summary>
+        /// <remarks>
+        /// <seealso cref="System.Numerics.BigInteger"/> can perform multiplication on large integers, but it's
+        /// comparatively slow, and an equivalent method allocates around 360B/call
+        /// </remarks>
+        /// <param name="x">First 64-bit integer</param>
+        /// <param name="y">Second 64-bit integer</param>
+        /// <returns>Product of <paramref name="x"/> and <paramref name="y"/></returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        [SuppressMessage("ReSharper", "JoinDeclarationAndInitializer")]
+        private static unsafe (ulong Hi, ulong Lo) Multiply64(ulong x, ulong y)
+        {
+            ulong hi;
+            ulong lo;
+
+            // Use BMI2 intrinsics where available
+#if NETCOREAPP3_0_OR_GREATER
+            if (System.Runtime.Intrinsics.X86.Bmi2.X64.IsSupported)
+            {
+                hi = System.Runtime.Intrinsics.X86.Bmi2.X64.MultiplyNoFlags(x, y, &lo);
+                return (hi, lo);
+            }
+#endif
+
+            lo = x * y;
+
+            ulong x0 = (uint)x;
+            ulong x1 = x >> 32;
+
+            ulong y0 = (uint)y;
+            ulong y1 = y >> 32;
+
+            ulong p11 = x1 * y1;
+            ulong p01 = x0 * y1;
+            ulong p10 = x1 * y0;
+            ulong p00 = x0 * y0;
+
+            // 64-bit product + two 32-bit values
+            ulong middle = p10 + (p00 >> 32) + (uint)p01;
+
+            // 64-bit product + two 32-bit values
+            hi = p11 + (middle >> 32) + (p01 >> 32);
+
+            return (hi, lo);
+        }
+
+        public override IRandom Copy()
+        {
+            return new WyRandom(_state);
+        }
+    }
+}

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

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: bdbd63a5a5794111b6f4d3e965137f3f
+timeCreated: 1732479831