com.wallstop-studios.unity-helpers 2.0.0-rc24 → 2.0.0-rc26

package/README.md

@@ -10,3 +10,91 @@ Various Unity Helpers. Includes many deterministic, seedable random number gener
     - URL: `https://registry.npmjs.org`
     - Scope(s): `com.wallstop-studios.unity-helpers`
 5. Resolve the latest `com.wallstop-studios.unity-helpers`
+
+# Package Contents
+- Random Number Generators
+- Spatial Trees
+- Protobuf, Binary, and JSON formatting
+- A resizable CyclicBuffer
+- Simple single-threaded thread pool
+- A LayeredImage for use with Unity's UI Toolkit
+- Geometry Helpers
+- Child/Parent/Sibling Attributes to automatically get components
+- ReadOnly attribute to disable editing of serialized properties in the inspector
+- An extensive collection of helpers
+- Simple math functions including a generic Range
+- Common buffers to reduce allocations
+- A RuntimeSingleton implementation for automatic creation/accessing of singletons
+- String helpers, like converting to PascalCase, like Unity does for variable names in the inspector
+- A randomizable PerlinNoise implementation
+- And more!
+
+# Random Number Generators
+This package implements several high quality, seedable, and serializable random number generators. The best one (currently) is the PCG Random. This has been hidden behind the `PRNG.Instance` class, which is thread-safe. As the package evolves, the exact implementation of this may change.
+
+All of these implement a custom [IRandom](./Runtime/Core/Random/IRandom.cs) interface with a significantly richer suite of methods than the standard .Net and Unity randoms offer.
+
+To use:
+
+```csharp
+IRandom random = PRNG.Instance;
+
+random.NextFloat(); // Something between 0.0f and 1.0f
+random.NextDouble(); // Something between 0.0d and 1.0d
+random.Next(); // Something between 0 and int.MaxValue
+random.NextUint(); // Something between 0 and uint.MaxValue
+
+int [] values = {1, 2, 3};
+random.NextOf(values); // 1, 2, or 3
+random.NextOf(Enumerable.Range(0, 3)); // 1, 2, or 3
+HashSet<int> setValues = new() {1, 2, 3};
+random.NextOf(setValues); // 1, 2, or 3
+
+random.NextGuid(); // A valid UUIDv4
+random.NextGaussian(); // A value sampled from a gaussian curve around mean=0, stdDev=1 (configurable via parameters)
+random.NextEnum<T>(); // A randomly selected enum of type T
+
+int width = 100;
+int height = 100;
+random.NextNoiseMap(width, height); // A configurable noise map generated using random octave offsets
+```
+
+## Implemented Random Number Generators
+- PCG
+- DotNet (uses the currently implemented .Net Random)
+- RomoDuo
+- SplitMix64
+- Squirrel
+- System (uses a port of the Windows .Net Random)
+- Unity (uses Unity's random under the hood)
+- Wy
+- XorShift
+- XorShiro
+
+# Spatial Trees
+There are three implemented 2D immutable spatial trees that can store generic objects, as long as there is some resolution function that can convert them into Vector2 spatial positions.
+
+- QuadTree (easiest to use)
+- KDTree
+- RTree
+
+Spatial trees, after construction, allow for O(log(n)) spatial query time instead of O(n). They are extremely useful if you need repeated spatial queries, or if you have relatively static spatial data.
+
+## Usage
+
+```csharp
+GameObject [] spatialStorage = { myCoolGameObject };
+QuadTree<GameObject> quadTree = new(spatialStorage, go => go.transform.position);
+
+// Might return your object, might not
+GameObject [] inBounds = quadTree.GetElementsInBounds(new Bounds(0, 0, 100, 100));
+
+// Uses a "good-enough" nearest-neighbor approximately for cheap neighbors
+List<GameObject> nearestNeighbors = new();
+quadTree.GetApproximateNearestNeighbors(myCoolGameObject.transform.position, 1, nearestNeighbors);
+Assert.AreEqual(1, nearestNeighbors.Count);
+Assert.AreEqual(myCoolGameObject, nearestNeighbors[0]);
+```
+
+## Note
+All spatial trees expect the positional data to be *immutable*. It is very important that the positions do not change. If they do, you will need to reconstruct the tree.

package/Runtime/Core/DataStructure/CyclicBuffer.cs

@@ -4,16 +4,16 @@
     using System.Collections;
     using System.Collections.Generic;
     using System.Linq;
+    using Extension;
     using Helper;
 
     [Serializable]
     public sealed class CyclicBuffer<T> : IReadOnlyList<T>
     {
+        public int Capacity { get; private set; }
         public int Count { get; private set; }
         public bool IsReadOnly => false;
 
-        public readonly int capacity;
-
         private readonly List<T> _buffer;
         private int _position;
 
@@ -38,7 +38,7 @@
                 throw new ArgumentException(nameof(capacity));
             }
 
-            this.capacity = capacity;
+            Capacity = capacity;
             _position = 0;
             Count = 0;
             _buffer = new List<T>();
@@ -64,7 +64,7 @@
 
         public void Add(T item)
         {
-            if (capacity == 0)
+            if (Capacity == 0)
             {
                 return;
             }
@@ -78,8 +78,8 @@
                 _buffer.Add(item);
             }
 
-            _position = _position.WrappedIncrement(capacity);
-            if (Count < capacity)
+            _position = _position.WrappedIncrement(Capacity);
+            if (Count < Capacity)
             {
                 ++Count;
             }
@@ -93,6 +93,31 @@
             _buffer.Clear();
         }
 
+        public void Resize(int newCapacity)
+        {
+            if (newCapacity == Capacity)
+            {
+                return;
+            }
+
+            if (newCapacity < 0)
+            {
+                throw new ArgumentException(nameof(newCapacity));
+            }
+
+            int oldCapacity = Capacity;
+            Capacity = newCapacity;
+            _buffer.Shift(-_position);
+            if (newCapacity < _buffer.Count)
+            {
+                _buffer.RemoveRange(newCapacity, _buffer.Count - newCapacity);
+            }
+
+            _position =
+                newCapacity < oldCapacity && newCapacity <= _buffer.Count ? 0 : _buffer.Count;
+            Count = Math.Min(newCapacity, Count);
+        }
+
         public bool Contains(T item)
         {
             return _buffer.Contains(item);
@@ -100,7 +125,11 @@
 
         private int AdjustedIndexFor(int index)
         {
-            long longCapacity = capacity;
+            long longCapacity = Capacity;
+            if (longCapacity == 0L)
+            {
+                return 0;
+            }
             unchecked
             {
                 int adjustedIndex = (int)(

package/Runtime/Core/Extension/IListExtensions.cs

@@ -1,6 +1,8 @@
 namespace UnityHelpers.Core.Extension
 {
+    using System;
     using System.Collections.Generic;
+    using Helper;
     using Random;
 
     public static class IListExtensions
@@ -26,6 +28,44 @@
             }
         }
 
+        public static void Shift<T>(this IList<T> list, int amount)
+        {
+            int count = list.Count;
+            if (count <= 1)
+            {
+                return;
+            }
+
+            amount = amount.PositiveMod(count);
+            if (amount == 0)
+            {
+                return;
+            }
+
+            Reverse(list, 0, count - 1);
+            Reverse(list, 0, amount - 1);
+            Reverse(list, amount, count - 1);
+        }
+
+        public static void Reverse<T>(this IList<T> list, int start, int end)
+        {
+            if (start < 0 || list.Count <= start)
+            {
+                throw new ArgumentException(nameof(start));
+            }
+            if (end < 0 || list.Count <= end)
+            {
+                throw new ArgumentException(nameof(end));
+            }
+
+            while (start < end)
+            {
+                (list[start], list[end]) = (list[end], list[start]);
+                start++;
+                end--;
+            }
+        }
+
         public static void RemoveAtSwapBack<T>(this IList<T> list, int index)
         {
             if (list.Count <= 1)

package/Runtime/Core/Helper/WallMath.cs

@@ -31,6 +31,34 @@
                 );
         }
 
+        public static float PositiveMod(this float value, float max)
+        {
+            value %= max;
+            value += max;
+            return value % max;
+        }
+
+        public static double PositiveMod(this double value, double max)
+        {
+            value %= max;
+            value += max;
+            return value % max;
+        }
+
+        public static int PositiveMod(this int value, int max)
+        {
+            value %= max;
+            value += max;
+            return value % max;
+        }
+
+        public static long PositiveMod(this long value, long max)
+        {
+            value %= max;
+            value += max;
+            return value % max;
+        }
+
         public static int WrappedAdd(this int value, int increment, int max)
         {
             WrappedAdd(ref value, increment, max);

package/Tests/Runtime/DataStructures/CyclicBufferTests.cs

@@ -32,7 +32,7 @@
             {
                 int capacity = PRNG.Instance.Next(1, int.MaxValue);
                 CyclicBuffer<int> buffer = new(capacity);
-                Assert.AreEqual(capacity, buffer.capacity);
+                Assert.AreEqual(capacity, buffer.Capacity);
             }
         }
 
@@ -74,7 +74,7 @@
                 if (!expected.SequenceEqual(buffer))
                 {
                     Assert.Fail(
-                        $"Failure at iteration {i}, capacity={buffer.capacity}, "
+                        $"Failure at iteration {i}, capacity={buffer.Capacity}, "
                             + $"capacityMultiplier={CapacityMultiplier}\n"
                             + $"Expected: [{string.Join(",", expected)}], Actual: [{string.Join(",", buffer)}]"
                     );
@@ -168,7 +168,7 @@
                     if (!expected.SequenceEqual(buffer))
                     {
                         Assert.Fail(
-                            $"Failure at iteration {i}, j={j}, capacity={buffer.capacity}, "
+                            $"Failure at iteration {i}, j={j}, capacity={buffer.Capacity}, "
                                 + $"capacityMultiplier={CapacityMultiplier}\n"
                                 + $"Expected: [{string.Join(",", expected)}], Actual: [{string.Join(",", buffer)}]"
                         );
@@ -190,14 +190,18 @@
         [Test]
         public void ClearOk()
         {
+            HashSet<int> seen = new();
             for (int i = 0; i < NumTries; ++i)
             {
                 int capacity = PRNG.Instance.Next(100, 1_000);
                 CyclicBuffer<int> buffer = new(capacity);
                 float fillPercent = PRNG.Instance.NextFloat(0.5f, 1.5f);
+                seen.Clear();
                 for (int j = 0; j < capacity * fillPercent; ++j)
                 {
-                    buffer.Add(PRNG.Instance.Next());
+                    int value = PRNG.Instance.Next();
+                    seen.Add(value);
+                    buffer.Add(value);
                 }
 
                 Assert.AreNotEqual(0, buffer.Count);
@@ -205,8 +209,115 @@
                 buffer.Clear();
 
                 Assert.AreEqual(0, buffer.Count);
-                Assert.AreEqual(capacity, buffer.capacity);
+                Assert.AreEqual(capacity, buffer.Capacity);
                 Assert.IsTrue(Array.Empty<int>().SequenceEqual(buffer));
+
+                // Make sure our data is actually cleaned up, none of our input data should be "Contained"
+                foreach (int value in seen)
+                {
+                    Assert.IsFalse(buffer.Contains(value));
+                }
+            }
+        }
+
+        [Test]
+        public void ResizeFullOk()
+        {
+            for (int i = 0; i < NumTries; ++i)
+            {
+                int capacity = PRNG.Instance.Next(100, 1_000);
+                CyclicBuffer<int> buffer = new(capacity);
+                float fillPercent = PRNG.Instance.NextFloat(1f, 2f);
+                float capacityPercent = PRNG.Instance.NextFloat(0.3f, 0.9f);
+                for (int j = 0; j < capacity * fillPercent; ++j)
+                {
+                    int value = PRNG.Instance.Next();
+                    buffer.Add(value);
+                }
+
+                int[] values = buffer.ToArray();
+
+                int newCapacity = Math.Max(0, (int)(capacity * capacityPercent));
+                buffer.Resize(newCapacity);
+                int[] newValues = buffer.ToArray();
+                Assert.AreEqual(newCapacity, buffer.Capacity);
+                Assert.AreEqual(newCapacity, newValues.Length);
+                Assert.That(values.Take(newCapacity), Is.EqualTo(newValues));
+
+                buffer.Add(1);
+                buffer.Add(2);
+                int[] afterAddition = buffer.ToArray();
+                Assert.That(afterAddition, Is.EqualTo(newValues.Skip(2).Concat(new[] { 1, 2 })));
+
+                newCapacity = 0;
+                buffer.Resize(newCapacity);
+                newValues = buffer.ToArray();
+                Assert.AreEqual(newCapacity, buffer.Capacity);
+                Assert.AreEqual(newCapacity, newValues.Length);
+            }
+        }
+
+        [Test]
+        public void ResizePartialOk()
+        {
+            for (int i = 0; i < NumTries; ++i)
+            {
+                int capacity = PRNG.Instance.Next(100, 1_000);
+                CyclicBuffer<int> buffer = new(capacity);
+                float fillPercent = PRNG.Instance.NextFloat(0.3f, 0.9f);
+                float capacityPercent = PRNG.Instance.NextFloat(0.3f, 0.9f);
+                int filled = (int)(capacity * fillPercent);
+                for (int j = 0; j < filled; ++j)
+                {
+                    int value = PRNG.Instance.Next();
+                    buffer.Add(value);
+                }
+
+                int[] values = buffer.ToArray();
+
+                int newCapacity = Math.Max(0, (int)(capacity * capacityPercent));
+                buffer.Resize(newCapacity);
+                int[] newValues = buffer.ToArray();
+                Assert.AreEqual(newCapacity, buffer.Capacity);
+                Assert.AreEqual(Math.Min(filled, newCapacity), newValues.Length);
+                Assert.That(values.Take(newCapacity), Is.EqualTo(newValues));
+
+                buffer.Add(1);
+                buffer.Add(2);
+                int[] afterAddition = buffer.ToArray();
+                if (newCapacity <= filled)
+                {
+                    Assert.That(
+                        afterAddition,
+                        Is.EqualTo(newValues.Skip(2).Concat(new[] { 1, 2 })),
+                        $"Resize failed for iteration {i}, fillPercent {fillPercent:0.00}, capacityPercent: {capacityPercent:0.00}. "
+                            + $"Capacity: {capacity}, newCapacity: {newCapacity}, filled: {filled}."
+                    );
+                }
+                else if (newCapacity == filled + 1)
+                {
+                    Assert.That(
+                        afterAddition,
+                        Is.EqualTo(newValues.Skip(1).Concat(new[] { 1, 2 })),
+                        $"Resize failed for iteration {i}, fillPercent {fillPercent:0.00}, capacityPercent: {capacityPercent:0.00}. "
+                            + $"Capacity: {capacity}, newCapacity: {newCapacity}, filled: {filled}."
+                    );
+                }
+                else
+                {
+                    Assert.That(
+                        afterAddition,
+                        Is.EqualTo(newValues.Concat(new[] { 1, 2 })),
+                        $"Resize failed for iteration {i}, fillPercent {fillPercent:0.00}, capacityPercent: {capacityPercent:0.00}. "
+                            + $"Capacity: {capacity}, newCapacity: {newCapacity}, filled: {filled}."
+                    );
+                }
+
+                newCapacity = 0;
+                buffer.Resize(newCapacity);
+                newValues = buffer.ToArray();
+                Assert.AreEqual(newCapacity, buffer.Capacity);
+                Assert.AreEqual(newCapacity, newValues.Length);
             }
         }
     }

package/Tests/Runtime/Extensions/IListExtensionTests.cs

@@ -0,0 +1,76 @@
+namespace UnityHelpers.Tests.Extensions
+{
+    using System;
+    using System.Linq;
+    using Core.Extension;
+    using NUnit.Framework;
+
+    public sealed class IListExtensionTests
+    {
+        [Test]
+        public void ShiftLeft()
+        {
+            int[] input = Enumerable.Range(0, 10).ToArray();
+            for (int i = 0; i < input.Length * 2; ++i)
+            {
+                int[] shifted = input.ToArray();
+                shifted.Shift(-1 * i);
+                Assert.That(
+                    input.Skip(i % input.Length).Concat(input.Take(i % input.Length)),
+                    Is.EqualTo(shifted)
+                );
+            }
+        }
+
+        [Test]
+        public void ShiftRight()
+        {
+            int[] input = Enumerable.Range(0, 10).ToArray();
+            for (int i = 0; i < input.Length * 2; ++i)
+            {
+                int[] shifted = input.ToArray();
+                shifted.Shift(i);
+                Assert.That(
+                    input
+                        .Skip((input.Length * 3 - i) % input.Length)
+                        .Concat(input.Take((input.Length * 3 - i) % input.Length)),
+                    Is.EqualTo(shifted),
+                    $"Shift failed for amount {i}."
+                );
+            }
+        }
+
+        [Test]
+        public void Reverse()
+        {
+            int[] input = Enumerable.Range(0, 10).ToArray();
+            for (int i = 0; i < input.Length; ++i)
+            {
+                int[] shifted = input.ToArray();
+                shifted.Reverse(0, i);
+                Assert.That(
+                    input.Take(i + 1).Reverse().Concat(input.Skip(i + 1)),
+                    Is.EqualTo(shifted),
+                    $"Reverse failed for reversal from [0, {i}]."
+                );
+            }
+
+            // TODO
+        }
+
+        [Test]
+        public void ReverseInvalidArguments()
+        {
+            int[] input = Enumerable.Range(0, 10).ToArray();
+            Assert.Throws<ArgumentException>(() => input.Reverse(-1, 1));
+            Assert.Throws<ArgumentException>(() => input.Reverse(input.Length, 1));
+            Assert.Throws<ArgumentException>(() => input.Reverse(int.MaxValue, 1));
+            Assert.Throws<ArgumentException>(() => input.Reverse(int.MinValue, 1));
+
+            Assert.Throws<ArgumentException>(() => input.Reverse(1, -1));
+            Assert.Throws<ArgumentException>(() => input.Reverse(1, input.Length));
+            Assert.Throws<ArgumentException>(() => input.Reverse(1, int.MaxValue));
+            Assert.Throws<ArgumentException>(() => input.Reverse(1, int.MinValue));
+        }
+    }
+}

package/Tests/Runtime/Extensions/IListExtensionTests.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 53f10c10d1a14859a9a8616477fd318a
+timeCreated: 1741982863

package/Tests/Runtime/Helper/WallMathTests.cs

@@ -44,6 +44,19 @@
             }
         }
 
+        [Test]
+        public void PositiveMod()
+        {
+            Assert.AreEqual(9, (-1).PositiveMod(10));
+            Assert.AreEqual(1, 1.PositiveMod(10));
+            Assert.AreEqual(9f, (-1f).PositiveMod(10f));
+            Assert.AreEqual(1f, 1f.PositiveMod(10f));
+            Assert.AreEqual(9.0, (-1.0).PositiveMod(10.0));
+            Assert.AreEqual(1.0, 1.0.PositiveMod(10.0));
+            Assert.AreEqual(9L, (-1L).PositiveMod(10L));
+            Assert.AreEqual(1L, 1L.PositiveMod(10L));
+        }
+
         [Test]
         public void ApproximatelyExpected()
         {
@@ -51,7 +64,6 @@
             Assert.IsTrue(0f.Approximately(0.5f, 1f));
             Assert.IsFalse(0.001f.Approximately(0f, 0f));
             Assert.IsFalse(100f.Approximately(5f, 2.4f));
-
             Assert.IsTrue(0.001f.Approximately(0.0001f));
         }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.wallstop-studios.unity-helpers",
-  "version": "2.0.0-rc24",
+  "version": "2.0.0-rc26",
   "displayName": "Unity Helpers",
   "description": "Various Unity Helper Library",
   "dependencies": {},