com.wallstop-studios.unity-helpers 2.0.4 → 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/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.