CHANGELOG.md

@@ -18,7 +18,7 @@ Additions
 - Added GetDownTime, GetUpTime, GetTimeSincePress, WasModifierDown and WasDown to Keybind and Combination
 - Added the ability for UniformTextureAtlases to have padding for each region
 - Added UniformTextureAtlas methods ToList and ToDictionary
-- Added SingleRandom and SeedSource
+- Added the SingleRandom utility class
 - **Added the ability to find paths to one of multiple goals using AStar**
 
 Improvements

MLEM/Misc/SeedSource.cs

@@ -1,104 +0,0 @@
-using System;
-
-namespace MLEM.Misc {
-    /// <summary>
-    /// A seed source contains an <see cref="int"/> value which can be used as a seed for a <see cref="System.Random"/> or <see cref="SingleRandom"/>. Seed sources feature a convenient way to add multiple seeds using <see cref="Add(int)"/>, which will be sufficiently scrambled to be deterministically pseudorandom and combined into a single <see cref="int"/>.
-    /// This struct behaves similarly to <c>System.HashCode</c> in many ways, with an important distinction being that <see cref="SeedSource"/>'s scrambling procedure is not considered an implementation detail, and will stay consistent between process executions.
-    /// </summary>
-    /// <example>
-    /// For example, a seed source can be used to create a new <see cref="System.Random"/> based on an object's <c>x</c> and <c>y</c> coordinates by combining them into a <see cref="SeedSource"/> using <see cref="Add(int)"/>. The values generated by the <see cref="System.Random"/> created using <see cref="Random()"/> will then be determined by the specific pair of <c>x</c> and <c>y</c> values used.
-    /// </example>
-    public readonly struct SeedSource {
-
-        private readonly int? value;
-
-        /// <summary>
-        /// Creates a new seed source from the given seed, which will be added automatically using <see cref="Add(int)"/>.
-        /// </summary>
-        /// <param name="seed">The initial seed to use.</param>
-        public SeedSource(int seed) : this() {
-            this = this.Add(seed);
-        }
-
-        /// <summary>
-        /// Creates a new seed source from the given set of seeds, which will be added automatically using <see cref="Add(int)"/>.
-        /// </summary>
-        /// <param name="seeds">The initial seeds to use.</param>
-        public SeedSource(params int[] seeds) : this() {
-            foreach (var seed in seeds)
-                this = this.Add(seed);
-        }
-
-        private SeedSource(int? value) {
-            this.value = value;
-        }
-
-        /// <summary>
-        /// Adds the given seed to this seed source's value and returns the result as a new seed source.
-        /// The algorithm used for adding involves various scrambling operations that sufficiently pseudo-randomize the seed and final value.
-        /// </summary>
-        /// <param name="seed">The seed to add.</param>
-        /// <returns>A new seed source with the seed added.</returns>
-        public SeedSource Add(int seed) {
-            return new SeedSource(new int?(SeedSource.Scramble(this.Get()) + SeedSource.Scramble(seed)));
-        }
-
-        /// <summary>
-        /// Adds the given seed to this seed source's value and returns the result as a new seed source.
-        /// Floating point values are scrambled by invoking <see cref="Add(int)"/> using a typecast version, followed by invoking <see cref="Add(int)"/> using the decimal value multiplied by <see cref="int.MaxValue"/>.
-        /// </summary>
-        /// <param name="seed">The seed to add.</param>
-        /// <returns>A new seed source with the seed added.</returns>
-        public SeedSource Add(float seed) {
-            return this.Add((int) seed).Add((seed - (int) seed) * int.MaxValue);
-        }
-
-        /// <summary>
-        /// Adds the given seed to this seed source's value and returns the result as a new seed source.
-        /// Strings are scrambled by invoking <see cref="Add(int)"/> using every character contained in the string, in order.
-        /// </summary>
-        /// <param name="seed">The seed to add.</param>
-        /// <returns>A new seed source with the seed added.</returns>
-        public SeedSource Add(string seed) {
-            var ret = this;
-            foreach (var c in seed)
-                ret = ret.Add(c);
-            return ret;
-        }
-
-        /// <summary>
-        /// Returns a new seed source whose value is this seed source's value, but scrambled further.
-        /// In essence, this creates a new seed source whose value is determined by the current seed source.
-        /// </summary>
-        /// <returns>A new seed source with a rotated value.</returns>
-        public SeedSource Rotate() {
-            return new SeedSource(new int?(SeedSource.Scramble(this.Get())));
-        }
-
-        /// <summary>
-        /// Returns this seed source's seed value, which can then be used in <see cref="SingleRandom"/> or elsewhere.
-        /// </summary>
-        /// <returns>This seed source's value.</returns>
-        public int Get() {
-            return this.value ?? 1623487;
-        }
-
-        /// <summary>
-        /// Returns a new <see cref="Random"/> instance using this source seed's value, retrieved using <see cref="Get"/>.
-        /// </summary>
-        /// <returns>A new <see cref="Random"/> using this seed source's value.</returns>
-        public Random Random() {
-            return new Random(this.Get());
-        }
-
-        private static int Scramble(int x) {
-            x += 84317;
-            x ^= x << 7;
-            x *= 207398809;
-            x ^= x << 17;
-            x *= 928511849;
-            return x;
-        }
-
-    }
-}

MLEM/Misc/SingleRandom.cs

@@ -1,6 +1,8 @@
-namespace MLEM.Misc {
+using System;
+
+namespace MLEM.Misc {
     /// <summary>
-    /// The SingleRandom class allows generating single, one-off pseudorandom numbers based on a seed or a <see cref="SeedSource"/>.
+    /// The SingleRandom class allows generating single, one-off pseudorandom numbers based on a seed, or a set of seeds.
     /// The types of numbers that can be generated are <see cref="int"/> and <see cref="float"/>, both of which can be generated with specific minimum and maximum values if desired.
     /// Methods in this class are tested to be sufficiently "random", that is, to be sufficiently distributed throughout their range, as well as sufficiently different for neighboring seeds.
     /// </summary>
@@ -17,13 +19,13 @@
         }
 
         /// <summary>
-        /// Generates a single, one-off pseudorandom integer between 0 and <see cref="int.MaxValue"/> based on a given <paramref name="source"/>.
+        /// Generates a single, one-off pseudorandom integer between 0 and <see cref="int.MaxValue"/> based on a given set of <paramref name="seeds"/>.
-        /// This method is guaranteed to return the same result for the same <paramref name="source"/>.
+        /// This method is guaranteed to return the same result for the same set of <paramref name="seeds"/>.
         /// </summary>
-        /// <param name="source">The <see cref="SeedSource"/> to use.</param>
+        /// <param name="seeds">The seeds to use.</param>
         /// <returns>The generated number.</returns>
-        public static int Int(SeedSource source) {
+        public static int Int(params int[] seeds) {
-            return (int) (SingleRandom.Single(source) * int.MaxValue);
+            return (int) (SingleRandom.Single(seeds) * int.MaxValue);
         }
 
         /// <summary>
@@ -38,14 +40,14 @@
         }
 
         /// <summary>
-        /// Generates a single, one-off pseudorandom integer between 0 and <paramref name="maxValue"/> based on a given <paramref name="source"/>.
+        /// Generates a single, one-off pseudorandom integer between 0 and <paramref name="maxValue"/> based on a given set of <paramref name="seeds"/>.
-        /// This method is guaranteed to return the same result for the same <paramref name="source"/>.
+        /// This method is guaranteed to return the same result for the same set of <paramref name="seeds"/>.
         /// </summary>
         /// <param name="maxValue">The (exclusive) maximum value.</param>
-        /// <param name="source">The <see cref="SeedSource"/> to use.</param>
+        /// <param name="seeds">The seeds to use.</param>
         /// <returns>The generated number.</returns>
-        public static int Int(int maxValue, SeedSource source) {
+        public static int Int(int maxValue, params int[] seeds) {
-            return (int) (maxValue * SingleRandom.Single(source));
+            return (int) (maxValue * SingleRandom.Single(seeds));
         }
 
         /// <summary>
@@ -61,15 +63,15 @@
         }
 
         /// <summary>
-        /// Generates a single, one-off pseudorandom integer between <paramref name="minValue"/> and <paramref name="maxValue"/> based on a given <paramref name="source"/>.
+        /// Generates a single, one-off pseudorandom integer between <paramref name="minValue"/> and <paramref name="maxValue"/> based on a given set of <paramref name="seeds"/>.
-        /// This method is guaranteed to return the same result for the same <paramref name="source"/>.
+        /// This method is guaranteed to return the same result for the same set of <paramref name="seeds"/>.
         /// </summary>
         /// <param name="minValue">The (inclusive) minimum value.</param>
         /// <param name="maxValue">The (exclusive) maximum value.</param>
-        /// <param name="source">The <see cref="SeedSource"/> to use.</param>
+        /// <param name="seeds">The seeds to use.</param>
         /// <returns>The generated number.</returns>
-        public static int Int(int minValue, int maxValue, SeedSource source) {
+        public static int Int(int minValue, int maxValue, params int[] seeds) {
-            return (int) ((maxValue - minValue) * SingleRandom.Single(source)) + minValue;
+            return (int) ((maxValue - minValue) * SingleRandom.Single(seeds)) + minValue;
         }
 
         /// <summary>
@@ -79,17 +81,17 @@
         /// <param name="seed">The seed to use.</param>
         /// <returns>The generated number.</returns>
         public static float Single(int seed) {
-            return (new SeedSource(seed).Get() / (float) int.MaxValue + 1) / 2;
+            return (SingleRandom.Scramble(seed) / (float) int.MaxValue + 1) / 2;
         }
 
         /// <summary>
-        /// Generates a single, one-off pseudorandom floating point number between 0 and 1 based on a given <paramref name="source"/>.
+        /// Generates a single, one-off pseudorandom floating point number between 0 and 1 based on a given set of <paramref name="seeds"/>.
-        /// This method is guaranteed to return the same result for the same <paramref name="source"/>.
+        /// This method is guaranteed to return the same result for the same set of <paramref name="seeds"/>.
         /// </summary>
-        /// <param name="source">The <see cref="SeedSource"/> to use.</param>
+        /// <param name="seeds">The seeds to use.</param>
         /// <returns>The generated number.</returns>
-        public static float Single(SeedSource source) {
+        public static float Single(params int[] seeds) {
-            return (source.Get() / (float) int.MaxValue + 1) / 2;
+            return (SingleRandom.Scramble(seeds) / (float) int.MaxValue + 1) / 2;
         }
 
         /// <summary>
@@ -104,14 +106,14 @@
         }
 
         /// <summary>
-        /// Generates a single, one-off pseudorandom floating point number between 0 and <paramref name="maxValue"/> based on a given <paramref name="source"/>.
+        /// Generates a single, one-off pseudorandom floating point number between 0 and <paramref name="maxValue"/> based on a given set of <paramref name="seeds"/>.
-        /// This method is guaranteed to return the same result for the same <paramref name="source"/>.
+        /// This method is guaranteed to return the same result for the same set of <paramref name="seeds"/>.
         /// </summary>
         /// <param name="maxValue">The (exclusive) maximum value.</param>
-        /// <param name="source">The <see cref="SeedSource"/> to use.</param>
+        /// <param name="seeds">The seeds to use.</param>
         /// <returns>The generated number.</returns>
-        public static float Single(float maxValue, SeedSource source) {
+        public static float Single(float maxValue, params int[] seeds) {
-            return maxValue * SingleRandom.Single(source);
+            return maxValue * SingleRandom.Single(seeds);
         }
 
         /// <summary>
@@ -127,15 +129,37 @@
         }
 
         /// <summary>
-        /// Generates a single, one-off pseudorandom floating point number between <paramref name="minValue"/> and <paramref name="maxValue"/> based on a given <paramref name="source"/>.
+        /// Generates a single, one-off pseudorandom floating point number between <paramref name="minValue"/> and <paramref name="maxValue"/> based on a given set of <paramref name="seeds"/>.
-        /// This method is guaranteed to return the same result for the same <paramref name="source"/>.
+        /// This method is guaranteed to return the same result for the same set of <paramref name="seeds"/>.
         /// </summary>
         /// <param name="minValue">The (inclusive) minimum value.</param>
         /// <param name="maxValue">The (exclusive) maximum value.</param>
-        /// <param name="source">The <see cref="SeedSource"/> to use.</param>
+        /// <param name="seeds">The seeds to use.</param>
         /// <returns>The generated number.</returns>
-        public static float Single(float minValue, float maxValue, SeedSource source) {
+        public static float Single(float minValue, float maxValue, params int[] seeds) {
-            return (maxValue - minValue) * SingleRandom.Single(source) + minValue;
+            return (maxValue - minValue) * SingleRandom.Single(seeds) + minValue;
+        }
+
+        private static int Scramble(int[] seeds) {
+            if (seeds == null || seeds.Length <= 0)
+                throw new ArgumentOutOfRangeException(nameof(seeds));
+            var ret = 1623487;
+            for (var i = 0; i < seeds.Length; i++)
+                ret += SingleRandom.ScrambleStep(seeds[i]) * 68659;
+            return ret;
+        }
+
+        private static int Scramble(int seed) {
+            return SingleRandom.ScrambleStep(seed) * 68659 + 1623487;
+        }
+
+        private static int ScrambleStep(int seed) {
+            seed ^= (seed << 7);
+            seed *= 207398809;
+            seed ^= (seed << 17);
+            seed *= 928511849;
+            seed ^= (seed << 12);
+            return seed + 3;
         }
 
     }

Tests/SingleRandomTests.cs

@@ -1,6 +1,4 @@
 using System.Collections.Generic;
-using System.Globalization;
-using System.IO;
 using System.Linq;
 using MLEM.Misc;
 using NUnit.Framework;
@@ -12,10 +10,8 @@ public class SingleRandomTests {
     [Test]
     public void TestEquality() {
         for (var i = 0; i < 1000000; i++) {
-            Assert.AreEqual(SingleRandom.Single(i), SingleRandom.Single(new SeedSource().Add(i)));
+            Assert.AreEqual(SingleRandom.Single(i), SingleRandom.Single(new[] {i}));
-            Assert.AreEqual(SingleRandom.Single(i), SingleRandom.Single(new SeedSource(i)));
+            Assert.AreEqual(SingleRandom.Int(i), SingleRandom.Int(new[] {i}));
-            Assert.AreEqual(SingleRandom.Int(i), SingleRandom.Int(new SeedSource().Add(i)));
-            Assert.AreEqual(SingleRandom.Int(i), SingleRandom.Int(new SeedSource(i)));
 
             // test if all methods that accept mins and max are identical
             Assert.AreEqual(SingleRandom.Int(i), SingleRandom.Int(int.MaxValue, i));
@@ -50,15 +46,4 @@ public class SingleRandomTests {
         Assert.AreEqual(0.5, flts.Average(), 0.001);
     }
 
-    [Test]
-    public void TestExpectedValues() {
-        var distributed = File.ReadAllLines("Content/DistributedSingleRandoms.txt");
-        for (var i = 0; i < 10000; i++)
-            Assert.AreEqual(SingleRandom.Single(i * 10000).ToString(CultureInfo.InvariantCulture), distributed[i]);
-
-        var consecutive = File.ReadAllLines("Content/ConsecutiveSingleRandoms.txt");
-        for (var i = 0; i < 10000; i++)
-            Assert.AreEqual(SingleRandom.Single(i).ToString(CultureInfo.InvariantCulture), consecutive[i]);
-    }
-
 }