com.wallstop-studios.unity-helpers 2.0.0-rc81.7 → 2.0.0

package/Tests/Runtime/Serialization/SerializerAdditionalTests.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 30ef1c3947b84f028e9bde6b7b8cb5c1
+timeCreated: 1759370720

package/Tests/Runtime/Serialization/SerializerFileIoTests.cs

@@ -0,0 +1,105 @@
+namespace WallstopStudios.UnityHelpers.Tests.Serialization
+{
+    using System.IO;
+    using System.Threading;
+    using System.Threading.Tasks;
+    using NUnit.Framework;
+    using UnityEngine;
+    using WallstopStudios.UnityHelpers.Core.Serialization;
+    using WallstopStudios.UnityHelpers.Tests.TestUtils;
+
+    public sealed class SerializerFileIoTests : CommonTestBase
+    {
+        private string _dir;
+
+        [SetUp]
+        public void SetUp()
+        {
+            _dir = Path.Combine(Application.persistentDataPath, "SerializerFileIoTests");
+            if (Directory.Exists(_dir))
+            {
+                Directory.Delete(_dir, recursive: true);
+            }
+            Directory.CreateDirectory(_dir);
+        }
+
+        [TearDown]
+        public override void TearDown()
+        {
+            try
+            {
+                if (Directory.Exists(_dir))
+                {
+                    Directory.Delete(_dir, recursive: true);
+                }
+            }
+            catch { }
+            base.TearDown();
+        }
+
+        private sealed class Sample
+        {
+            public int a;
+            public string b;
+        }
+
+        [Test]
+        public void TryWriteAndTryReadRoundTrip()
+        {
+            string path = Path.Combine(_dir, "sample.json");
+            Sample s = new() { a = 7, b = "test" };
+
+            bool wrote = Serializer.TryWriteToJsonFile(s, path, pretty: true);
+            Assert.IsTrue(wrote, "Expected TryWriteToJsonFile to succeed.");
+            Assert.IsTrue(File.Exists(path), "Expected file to be created.");
+
+            bool read = Serializer.TryReadFromJsonFile(path, out Sample loaded);
+            Assert.IsTrue(read, "Expected TryReadFromJsonFile to succeed.");
+            Assert.NotNull(loaded);
+            Assert.AreEqual(7, loaded.a);
+            Assert.AreEqual("test", loaded.b);
+        }
+
+        [Test]
+        public void TryReadReturnsFalseWhenMissing()
+        {
+            string path = Path.Combine(_dir, "does_not_exist.json");
+            bool read = Serializer.TryReadFromJsonFile(path, out Sample loaded);
+            Assert.IsFalse(read);
+            Assert.IsNull(loaded);
+        }
+
+        [Test]
+        public void ReadAsyncHonorsCancellation()
+        {
+            string path = Path.Combine(_dir, "big.json");
+            // Create a moderately large file
+            File.WriteAllText(path, new string('x', 200_000));
+
+            using CancellationTokenSource cts = new();
+            cts.Cancel();
+            Assert.Throws<TaskCanceledException>(() =>
+                Serializer
+                    .ReadFromJsonFileAsync<Sample>(path, cts.Token)
+                    .ConfigureAwait(false)
+                    .GetAwaiter()
+                    .GetResult()
+            );
+        }
+
+        [Test]
+        public void WriteAsyncHonorsCancellation()
+        {
+            string path = Path.Combine(_dir, "out.json");
+            using CancellationTokenSource cts = new();
+            cts.Cancel();
+            Assert.Throws<TaskCanceledException>(() =>
+                Serializer
+                    .WriteToJsonFileAsync(new Sample { a = 1, b = "x" }, path, true, cts.Token)
+                    .ConfigureAwait(false)
+                    .GetAwaiter()
+                    .GetResult()
+            );
+        }
+    }
+}

package/Tests/Runtime/Serialization/SerializerFileIoTests.cs.meta

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

package/Tests/Runtime/Serialization/TypeConverterTests.cs

@@ -0,0 +1,34 @@
+namespace WallstopStudios.UnityHelpers.Tests.Serialization
+{
+    using System;
+    using System.Text.Json;
+    using System.Text.Json.Serialization;
+    using NUnit.Framework;
+    using WallstopStudios.UnityHelpers.Core.Helper;
+    using WallstopStudios.UnityHelpers.Core.Serialization.JsonConverters;
+
+    public sealed class TypeConverterTests
+    {
+        private sealed class TypeHolder
+        {
+            public Type T { get; set; }
+        }
+
+        [Test]
+        public void JsonTypeConverterResolvesTypes()
+        {
+            TypeHolder holder = new() { T = typeof(ReflectionHelpers) };
+            JsonSerializerOptions options = new()
+            {
+                IncludeFields = true,
+                PropertyNameCaseInsensitive = true,
+                Converters = { new JsonStringEnumConverter(), TypeConverter.Instance },
+            };
+
+            string json = JsonSerializer.Serialize(holder, options);
+            TypeHolder roundtrip = JsonSerializer.Deserialize<TypeHolder>(json, options);
+            Assert.IsNotNull(roundtrip);
+            Assert.AreEqual(typeof(ReflectionHelpers), roundtrip.T);
+        }
+    }
+}

package/Tests/Runtime/Serialization/TypeConverterTests.cs.meta

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

package/Tests/Runtime/Serialization/UnityEngineObjectJsonTests.cs

@@ -0,0 +1,247 @@
+namespace WallstopStudios.UnityHelpers.Tests.Serialization
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Text;
+    using System.Text.Json;
+    using NUnit.Framework;
+    using UnityEngine;
+    using UnityEngine.TestTools;
+    using WallstopStudios.UnityHelpers.Core.Helper;
+    using WallstopStudios.UnityHelpers.Core.Serialization;
+    using WallstopStudios.UnityHelpers.Tests.TestUtils;
+
+    [TestFixture]
+    public sealed class UnityEngineObjectJsonTests : CommonTestBase
+    {
+        [Test]
+        public void GameObjectSerializationContainsExpectedFields()
+        {
+            GameObject go = Track(new GameObject("GO_Main"));
+            int expectedId = go.GetInstanceID();
+            string json = Serializer.JsonStringify(go);
+            Assert.IsFalse(string.IsNullOrWhiteSpace(json), json);
+
+            using JsonDocument doc = JsonDocument.Parse(json);
+            JsonElement root = doc.RootElement;
+            Assert.AreEqual(JsonValueKind.Object, root.ValueKind);
+            Assert.True(root.TryGetProperty("name", out JsonElement name));
+            Assert.True(root.TryGetProperty("type", out JsonElement type));
+            Assert.True(root.TryGetProperty("instanceId", out JsonElement id));
+            Assert.AreEqual("GO_Main", name.GetString());
+            StringAssert.Contains("UnityEngine.GameObject", type.GetString());
+            Assert.AreEqual(expectedId, id.GetInt32());
+        }
+
+        [Test]
+        public void GameObjectSerializationHandlesQuotesAndEscapes()
+        {
+            string tricky = "Quote \" and Backslash \\ and Newline\n and Unicode ☺";
+            GameObject go = Track(new GameObject(tricky));
+            string json = Serializer.JsonStringify(go);
+            using JsonDocument doc = JsonDocument.Parse(json);
+            Assert.AreEqual(tricky, doc.RootElement.GetProperty("name").GetString());
+        }
+
+        [Test]
+        public void ObjectTypedSerializationUsesRuntimeTypeConverter()
+        {
+            GameObject go = Track(new GameObject("ObjectTypedGO"));
+            int expectedId = go.GetInstanceID();
+            object goAsObject = go;
+            string json = Serializer.JsonStringify(goAsObject);
+            using JsonDocument doc = JsonDocument.Parse(json);
+            JsonElement root = doc.RootElement;
+            Assert.AreEqual("ObjectTypedGO", root.GetProperty("name").GetString());
+            StringAssert.Contains("UnityEngine.GameObject", root.GetProperty("type").GetString());
+            Assert.AreEqual(expectedId, root.GetProperty("instanceId").GetInt32());
+        }
+
+        [Test]
+        public void GameObjectSerializationPrettyPrintFormatsAndParses()
+        {
+            GameObject go = Track(new GameObject("Pretty ☃ Object ✓"));
+            int expectedId = go.GetInstanceID();
+            string json = Serializer.JsonStringify(go, pretty: true);
+            Assert.IsFalse(string.IsNullOrWhiteSpace(json), json);
+            StringAssert.Contains("\n", json);
+
+            using JsonDocument doc = JsonDocument.Parse(json);
+            JsonElement root = doc.RootElement;
+            Assert.True(root.TryGetProperty("name", out JsonElement name));
+            Assert.AreEqual("Pretty ☃ Object ✓", name.GetString());
+            Assert.True(root.TryGetProperty("instanceId", out JsonElement id));
+            Assert.AreEqual(expectedId, id.GetInt32());
+        }
+
+        [Test]
+        public void GameObjectSerializationStableInstanceIdAcrossSerializations()
+        {
+            GameObject go = Track(new GameObject("StableId"));
+            int expectedId = go.GetInstanceID();
+            string j1 = Serializer.JsonStringify(go);
+            string j2 = Serializer.JsonStringify(go);
+
+            using JsonDocument d1 = JsonDocument.Parse(j1);
+            using JsonDocument d2 = JsonDocument.Parse(j2);
+            int id1 = d1.RootElement.GetProperty("instanceId").GetInt32();
+            int id2 = d2.RootElement.GetProperty("instanceId").GetInt32();
+            Assert.AreEqual(expectedId, id1);
+            Assert.AreEqual(id1, id2);
+        }
+
+        [Test]
+        public void GameObjectDeserializationIsNotSupported()
+        {
+            GameObject go = Track(new GameObject("NoReadSupport"));
+            string json = Serializer.JsonStringify(go);
+
+            // Our converter intentionally does not implement Read. Ensure this throws.
+            Assert.Throws<NotImplementedException>(() =>
+                Serializer.JsonDeserialize<GameObject>(json)
+            );
+        }
+
+        [UnityTest]
+        public System.Collections.IEnumerator GameObjectArraySerializationWorksWithNullAndDestroyed()
+        {
+            GameObject alive = Track(new GameObject("Alive"));
+            int aliveId = alive.GetInstanceID();
+            GameObject dead = Track(new GameObject("Dead"));
+            dead.Destroy();
+            yield return null; // ensure Unity nullification
+            Assert.IsTrue(dead == null);
+
+            GameObject[] data = { null, alive, dead };
+            string json = Serializer.JsonStringify(data);
+            Assert.IsFalse(string.IsNullOrWhiteSpace(json), json);
+
+            using JsonDocument doc = JsonDocument.Parse(json);
+            JsonElement root = doc.RootElement;
+            Assert.AreEqual(JsonValueKind.Array, root.ValueKind);
+            Assert.AreEqual(3, root.GetArrayLength());
+            Assert.AreEqual(JsonValueKind.Null, root[0].ValueKind);
+
+            JsonElement mid = root[1];
+            Assert.AreEqual(JsonValueKind.Object, mid.ValueKind);
+            Assert.AreEqual("Alive", mid.GetProperty("name").GetString());
+            Assert.AreEqual(aliveId, mid.GetProperty("instanceId").GetInt32());
+
+            Assert.AreEqual(JsonValueKind.Null, root[2].ValueKind);
+        }
+
+        [UnityTest]
+        public System.Collections.IEnumerator GameObjectDictionarySerializationWorksWithNullAndDestroyed()
+        {
+            GameObject alive = Track(new GameObject("Alive_Dict"));
+            int aliveId = alive.GetInstanceID();
+            GameObject dead = Track(new GameObject("Dead_Dict"));
+            dead.Destroy();
+            yield return null; // ensure Unity nullification
+            Assert.IsTrue(dead == null);
+
+            Dictionary<string, GameObject> dict = new()
+            {
+                ["none"] = null,
+                ["alive"] = alive,
+                ["dead"] = dead,
+            };
+
+            string json = Serializer.JsonStringify(dict);
+            Assert.IsFalse(string.IsNullOrWhiteSpace(json), json);
+
+            using JsonDocument doc = JsonDocument.Parse(json);
+            JsonElement root = doc.RootElement;
+            Assert.AreEqual(JsonValueKind.Object, root.ValueKind);
+
+            Assert.True(root.TryGetProperty("none", out JsonElement none));
+            Assert.AreEqual(JsonValueKind.Null, none.ValueKind);
+
+            Assert.True(root.TryGetProperty("alive", out JsonElement aliveEl));
+            Assert.AreEqual("Alive_Dict", aliveEl.GetProperty("name").GetString());
+            Assert.AreEqual(aliveId, aliveEl.GetProperty("instanceId").GetInt32());
+
+            Assert.True(root.TryGetProperty("dead", out JsonElement deadEl));
+            Assert.AreEqual(JsonValueKind.Null, deadEl.ValueKind);
+        }
+
+        private sealed class GoHolder
+        {
+            public GameObject Go { get; set; }
+        }
+
+        private sealed class GoFieldHolder
+        {
+            public GameObject go;
+        }
+
+        [Test]
+        public void NestedObjectSerializationWithGameObjectProperty()
+        {
+            GameObject go = Track(new GameObject("Nested"));
+            int expectedId = go.GetInstanceID();
+            GoHolder holder = new() { Go = go };
+            string json = Serializer.JsonStringify(holder);
+            Assert.IsFalse(string.IsNullOrWhiteSpace(json), json);
+
+            using JsonDocument doc = JsonDocument.Parse(json);
+            JsonElement root = doc.RootElement;
+            Assert.True(root.TryGetProperty("Go", out JsonElement goEl));
+            Assert.AreEqual("Nested", goEl.GetProperty("name").GetString());
+            Assert.AreEqual(expectedId, goEl.GetProperty("instanceId").GetInt32());
+        }
+
+        [Test]
+        public void NestedObjectSerializationWithGameObjectField()
+        {
+            GameObject go = Track(new GameObject("NestedField"));
+            int expectedId = go.GetInstanceID();
+            GoFieldHolder holder = new() { go = go };
+            string json = Serializer.JsonStringify(holder);
+            Assert.IsFalse(string.IsNullOrWhiteSpace(json), json);
+
+            using JsonDocument doc = JsonDocument.Parse(json);
+            JsonElement root = doc.RootElement;
+            Assert.True(root.TryGetProperty("go", out JsonElement goEl));
+            Assert.AreEqual("NestedField", goEl.GetProperty("name").GetString());
+            Assert.AreEqual(expectedId, goEl.GetProperty("instanceId").GetInt32());
+        }
+
+        [Test]
+        public void FastSerializerProducesValidGameObjectJson()
+        {
+            GameObject go = Track(new GameObject("FastGO"));
+            int expectedId = go.GetInstanceID();
+            byte[] bytes = Serializer.JsonSerializeFast(go);
+            Assert.NotNull(bytes);
+            string json = Encoding.UTF8.GetString(bytes);
+            Assert.IsFalse(string.IsNullOrWhiteSpace(json), json);
+
+            using JsonDocument doc = JsonDocument.Parse(json);
+            JsonElement root = doc.RootElement;
+            Assert.AreEqual("FastGO", root.GetProperty("name").GetString());
+            Assert.AreEqual(expectedId, root.GetProperty("instanceId").GetInt32());
+        }
+
+        [Test]
+        public void SerializeIntoCallerBufferProducesValidGameObjectJson()
+        {
+            GameObject go = Track(new GameObject("BufferedGO"));
+            int expectedId = go.GetInstanceID();
+            byte[] buffer = null;
+            int len = Serializer.JsonSerialize(
+                go,
+                SerializerEncoding.GetNormalJsonOptions(),
+                ref buffer
+            );
+            Assert.Greater(len, 0);
+            Assert.NotNull(buffer);
+
+            string json = Encoding.UTF8.GetString(buffer, 0, len);
+            using JsonDocument doc = JsonDocument.Parse(json);
+            JsonElement root = doc.RootElement;
+            Assert.AreEqual("BufferedGO", root.GetProperty("name").GetString());
+            Assert.AreEqual(expectedId, root.GetProperty("instanceId").GetInt32());
+        }
+    }
+}

package/Tests/Runtime/Serialization/UnityEngineObjectJsonTests.cs.meta

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

package/Tests/Runtime/Serialization.meta

@@ -1,3 +1,3 @@
-fileFormatVersion: 2
-guid: f8d204ab204344dc9099d505a15f872f
+fileFormatVersion: 2
+guid: f8d204ab204344dc9099d505a15f872f
 timeCreated: 1730847832

package/Tests/Runtime/Tags/AttributeComponentTests.cs

@@ -0,0 +1,174 @@
+namespace WallstopStudios.UnityHelpers.Tests.Tags
+{
+    using System.Collections;
+    using NUnit.Framework;
+    using UnityEngine;
+    using UnityEngine.TestTools;
+    using WallstopStudios.UnityHelpers.Tags;
+    using WallstopStudios.UnityHelpers.Tests.Tags.Helpers;
+
+    [TestFixture]
+    public sealed class AttributesComponentTests : TagsTestBase
+    {
+        [SetUp]
+        public void SetUp()
+        {
+            ResetEffectHandleId();
+        }
+
+        [UnityTest]
+        public IEnumerator ApplyAttributeModificationsWithoutHandleUpdatesBaseValue()
+        {
+            GameObject entity = CreateTrackedGameObject(
+                "Attributes",
+                typeof(TestAttributesComponent)
+            );
+            TestAttributesComponent component = entity.GetComponent<TestAttributesComponent>();
+
+            AttributeModification modification = new()
+            {
+                attribute = nameof(TestAttributesComponent.health),
+                action = ModificationAction.Addition,
+                value = 10f,
+            };
+
+            component.ApplyAttributeModifications(new[] { modification }, null);
+            Assert.AreEqual(110f, component.health.CurrentValue);
+            Assert.AreEqual(1, component.notifications.Count);
+            yield return null;
+        }
+
+        [UnityTest]
+        public IEnumerator ForceApplyAttributeModificationsAppliesOncePerHandle()
+        {
+            GameObject entity = CreateTrackedGameObject(
+                "Attributes",
+                typeof(TestAttributesComponent)
+            );
+            TestAttributesComponent component = entity.GetComponent<TestAttributesComponent>();
+
+            AttributeEffect effect = CreateEffect(
+                "Buff",
+                e =>
+                {
+                    e.modifications.Add(
+                        new AttributeModification
+                        {
+                            attribute = nameof(TestAttributesComponent.health),
+                            action = ModificationAction.Addition,
+                            value = 5f,
+                        }
+                    );
+                }
+            );
+            EffectHandle handle = EffectHandle.CreateInstance(effect);
+
+            component.ForceApplyAttributeModifications(handle);
+            Assert.AreEqual(105f, component.health.CurrentValue);
+            Assert.AreEqual(1, component.notifications.Count);
+
+            component.notifications.Clear();
+            component.ForceApplyAttributeModifications(handle);
+            Assert.IsEmpty(component.notifications);
+            yield return null;
+        }
+
+        [UnityTest]
+        public IEnumerator ForceRemoveAttributeModificationsRestoresValue()
+        {
+            GameObject entity = CreateTrackedGameObject(
+                "Attributes",
+                typeof(TestAttributesComponent)
+            );
+            TestAttributesComponent component = entity.GetComponent<TestAttributesComponent>();
+
+            AttributeEffect effect = CreateEffect(
+                "Buff",
+                e =>
+                {
+                    e.modifications.Add(
+                        new AttributeModification
+                        {
+                            attribute = nameof(TestAttributesComponent.health),
+                            action = ModificationAction.Multiplication,
+                            value = 2f,
+                        }
+                    );
+                }
+            );
+            EffectHandle handle = EffectHandle.CreateInstance(effect);
+
+            component.ForceApplyAttributeModifications(handle);
+            component.notifications.Clear();
+            component.ForceRemoveAttributeModifications(handle);
+
+            Assert.AreEqual(100f, component.health.CurrentValue);
+            Assert.AreEqual(1, component.notifications.Count);
+            Assert.AreEqual(
+                nameof(TestAttributesComponent.health),
+                component.notifications[0].attribute
+            );
+            yield return null;
+        }
+
+        [UnityTest]
+        public IEnumerator ApplyAttributeModificationsWithHandleDelegatesToForce()
+        {
+            GameObject entity = CreateTrackedGameObject(
+                "Attributes",
+                typeof(TestAttributesComponent)
+            );
+            TestAttributesComponent component = entity.GetComponent<TestAttributesComponent>();
+
+            AttributeEffect effect = CreateEffect(
+                "Buff",
+                e =>
+                {
+                    e.modifications.Add(
+                        new AttributeModification
+                        {
+                            attribute = nameof(TestAttributesComponent.health),
+                            action = ModificationAction.Addition,
+                            value = 5f,
+                        }
+                    );
+                }
+            );
+            EffectHandle handle = EffectHandle.CreateInstance(effect);
+
+            component.ApplyAttributeModifications(effect.modifications, handle);
+            Assert.AreEqual(105f, component.health.CurrentValue);
+            yield return null;
+        }
+
+        [UnityTest]
+        public IEnumerator ForceApplyAttributeModificationsSkipsUnknownAttributes()
+        {
+            GameObject entity = CreateTrackedGameObject(
+                "Attributes",
+                typeof(TestAttributesComponent)
+            );
+            TestAttributesComponent component = entity.GetComponent<TestAttributesComponent>();
+
+            AttributeEffect effect = CreateEffect(
+                "Buff",
+                e =>
+                {
+                    e.modifications.Add(
+                        new AttributeModification
+                        {
+                            attribute = "missing",
+                            action = ModificationAction.Addition,
+                            value = 5f,
+                        }
+                    );
+                }
+            );
+            EffectHandle handle = EffectHandle.CreateInstance(effect);
+
+            component.ForceApplyAttributeModifications(handle);
+            Assert.IsEmpty(component.notifications);
+            yield return null;
+        }
+    }
+}

package/Tests/Runtime/Tags/AttributeComponentTests.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: ce74948f54b94073a4d582579ba575f2
+timeCreated: 1759352481