com.wallstop-studios.unity-helpers 2.0.4 → 2.1.0

package/Tests/Runtime/Tags/AttributeEffectTests.cs

@@ -0,0 +1,135 @@
+namespace WallstopStudios.UnityHelpers.Tests.Tags
+{
+    using System.Text.Json;
+    using NUnit.Framework;
+    using UnityEngine;
+    using WallstopStudios.UnityHelpers.Tags;
+
+    [TestFixture]
+    public sealed class AttributeEffectTests : AttributeTagsTestBase
+    {
+        [Test]
+        public void HumanReadableDescriptionFormatsAllModificationTypes()
+        {
+            AttributeEffect effect = Track(ScriptableObject.CreateInstance<AttributeEffect>());
+            effect.name = "Composite";
+            effect.modifications.Add(
+                new AttributeModification
+                {
+                    attribute = "health",
+                    action = ModificationAction.Addition,
+                    value = 5f,
+                }
+            );
+            effect.modifications.Add(
+                new AttributeModification
+                {
+                    attribute = "attack_speed",
+                    action = ModificationAction.Multiplication,
+                    value = 1.5f,
+                }
+            );
+            effect.modifications.Add(
+                new AttributeModification
+                {
+                    attribute = "armor",
+                    action = ModificationAction.Override,
+                    value = 10f,
+                }
+            );
+
+            string description = effect.HumanReadableDescription;
+            Assert.AreEqual("+5 Health, +50% Attack Speed, 10 Armor", description);
+        }
+
+        [Test]
+        public void HumanReadableDescriptionSkipsNeutralModifications()
+        {
+            AttributeEffect effect = Track(ScriptableObject.CreateInstance<AttributeEffect>());
+            effect.modifications.Add(
+                new AttributeModification
+                {
+                    attribute = "health",
+                    action = ModificationAction.Addition,
+                    value = 0f,
+                }
+            );
+            effect.modifications.Add(
+                new AttributeModification
+                {
+                    attribute = "speed",
+                    action = ModificationAction.Multiplication,
+                    value = 1f,
+                }
+            );
+
+            Assert.IsEmpty(effect.HumanReadableDescription);
+        }
+
+        [Test]
+        public void ToStringSerializesSummaryAndCollections()
+        {
+            AttributeEffect effect = Track(ScriptableObject.CreateInstance<AttributeEffect>());
+            effect.name = "JsonEffect";
+            effect.durationType = ModifierDurationType.Duration;
+            effect.duration = 3.25f;
+            effect.resetDurationOnReapplication = true;
+            effect.modifications.Add(
+                new AttributeModification
+                {
+                    attribute = "health",
+                    action = ModificationAction.Addition,
+                    value = 10f,
+                }
+            );
+            effect.effectTags.Add("Buff");
+
+            GameObject cosmeticHolder = Track(new GameObject("Glow", typeof(CosmeticEffectData)));
+            CosmeticEffectData cosmeticData = cosmeticHolder.GetComponent<CosmeticEffectData>();
+            effect.cosmeticEffects.Add(cosmeticData);
+
+            using JsonDocument document = JsonDocument.Parse(effect.ToString());
+            JsonElement root = document.RootElement;
+            Assert.AreEqual(
+                effect.HumanReadableDescription,
+                root.GetProperty("Description").GetString()
+            );
+            Assert.AreEqual("Duration", root.GetProperty("durationType").GetString());
+            Assert.AreEqual(3.25f, root.GetProperty("duration").GetSingle());
+            Assert.AreEqual("Buff", root.GetProperty("tags")[0].GetString());
+            Assert.AreEqual("Glow", root.GetProperty("CosmeticEffects")[0].GetString());
+            Assert.AreEqual(1, root.GetProperty("modifications").GetArrayLength());
+        }
+
+        [Test]
+        public void EqualsRequiresMatchingState()
+        {
+            AttributeEffect left = Track(ScriptableObject.CreateInstance<AttributeEffect>());
+            AttributeEffect right = Track(ScriptableObject.CreateInstance<AttributeEffect>());
+            left.name = right.name = "Stack";
+            left.durationType = right.durationType = ModifierDurationType.Duration;
+            left.duration = right.duration = 2f;
+            left.resetDurationOnReapplication = right.resetDurationOnReapplication = false;
+
+            AttributeModification modification = new()
+            {
+                attribute = "health",
+                action = ModificationAction.Addition,
+                value = 5f,
+            };
+
+            left.modifications.Add(modification);
+            right.modifications.Add(modification);
+            Assert.IsTrue(left.Equals(right));
+
+            right.modifications[0] = new AttributeModification
+            {
+                attribute = "health",
+                action = ModificationAction.Addition,
+                value = 10f,
+            };
+
+            Assert.IsFalse(left.Equals(right));
+        }
+    }
+}

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

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: f9cf8158bca5461c9fba12c31ab373b6
+timeCreated: 1761249361

package/Tests/Runtime/Tags/AttributeModificationTests.cs

@@ -0,0 +1,137 @@
+namespace WallstopStudios.UnityHelpers.Tests.Tags
+{
+    using System;
+    using System.Text.Json;
+    using NUnit.Framework;
+    using WallstopStudios.UnityHelpers.Core.Serialization;
+    using WallstopStudios.UnityHelpers.Tags;
+    using WallstopStudios.UnityHelpers.Tests.TestUtils;
+
+    public abstract class AttributeTagsTestBase : CommonTestBase
+    {
+        protected static void ResetEffectHandleId(long value = 0)
+        {
+            EffectHandle.Id = value;
+        }
+    }
+
+    [TestFixture]
+    public sealed class AttributeModificationTests
+    {
+        [Test]
+        public void EqualityOperatorsRespectFields()
+        {
+            AttributeModification baseline = new()
+            {
+                attribute = "health",
+                action = ModificationAction.Multiplication,
+                value = 1.5f,
+            };
+
+            AttributeModification clone = baseline;
+            Assert.IsTrue(baseline == clone);
+            Assert.IsFalse(baseline != clone);
+            Assert.AreEqual(baseline, clone);
+            Assert.AreEqual(baseline.GetHashCode(), clone.GetHashCode());
+
+            AttributeModification differentAttribute = baseline;
+            differentAttribute.attribute = "armor";
+            Assert.IsFalse(baseline == differentAttribute);
+            Assert.IsTrue(baseline != differentAttribute);
+
+            AttributeModification differentAction = baseline;
+            differentAction.action = ModificationAction.Addition;
+            Assert.IsFalse(baseline.Equals(differentAction));
+
+            AttributeModification differentValue = baseline;
+            differentValue.value = 2f;
+            Assert.IsFalse(baseline.Equals(differentValue));
+        }
+
+        [Test]
+        public void ToStringSerializesAllFields()
+        {
+            AttributeModification modification = new()
+            {
+                attribute = "health",
+                action = ModificationAction.Override,
+                value = 42.5f,
+            };
+
+            using JsonDocument document = JsonDocument.Parse(modification.ToString());
+            JsonElement root = document.RootElement;
+            Assert.AreEqual(
+                "health",
+                root.GetProperty(nameof(AttributeModification.attribute)).GetString()
+            );
+            Assert.AreEqual(
+                "Override",
+                root.GetProperty(nameof(AttributeModification.action)).GetString()
+            );
+            Assert.AreEqual(
+                42.5f,
+                root.GetProperty(nameof(AttributeModification.value)).GetSingle()
+            );
+        }
+
+        [Test]
+        public void SystemTextJsonRoundtripPreservesFields()
+        {
+            AttributeModification modification = new(
+                "armor",
+                ModificationAction.Multiplication,
+                1.25f
+            );
+            string json = Serializer.JsonStringify(modification);
+            AttributeModification clone = Serializer.JsonDeserialize<AttributeModification>(json);
+
+            Assert.AreEqual(modification, clone);
+        }
+
+        [Test]
+        public void ProtoBufRoundtripPreservesFields()
+        {
+            AttributeModification modification = new("speed", ModificationAction.Addition, -3f);
+            byte[] payload = Serializer.ProtoSerialize(modification);
+            AttributeModification clone = Serializer.ProtoDeserialize<AttributeModification>(
+                payload
+            );
+            Assert.AreEqual(modification, clone);
+        }
+
+        [Test]
+        public void CompareToOrdersBasedOnAction()
+        {
+            AttributeModification addition = new("health", ModificationAction.Addition, 10f);
+            AttributeModification multiplication = new(
+                "health",
+                ModificationAction.Multiplication,
+                2f
+            );
+            AttributeModification overrideValue = new("health", ModificationAction.Override, 0f);
+
+            AttributeModification[] unsorted = { overrideValue, multiplication, addition };
+
+            Array.Sort(unsorted);
+
+            Assert.AreEqual(addition, unsorted[0], "Addition should be applied first when sorted.");
+            Assert.AreEqual(
+                multiplication,
+                unsorted[1],
+                "Multiplication should appear after additions when sorted."
+            );
+            Assert.AreEqual(
+                overrideValue,
+                unsorted[2],
+                "Override should be processed last when sorted."
+            );
+        }
+
+        [Test]
+        public void CompareToObjectReturnsMinusOneForNonAttributeModification()
+        {
+            AttributeModification addition = new("health", ModificationAction.Addition, 5f);
+            Assert.AreEqual(-1, addition.CompareTo("not a modification"));
+        }
+    }
+}

package/Tests/Runtime/Tags/AttributeTests.cs

@@ -0,0 +1,192 @@
+namespace WallstopStudios.UnityHelpers.Tests.Tags
+{
+    using System;
+    using NUnit.Framework;
+    using UnityEngine;
+    using WallstopStudios.UnityHelpers.Tags;
+    using Attribute = WallstopStudios.UnityHelpers.Tags.Attribute;
+
+    [TestFixture]
+    public sealed class AttributeTests : AttributeTagsTestBase
+    {
+        [SetUp]
+        public void SetUp()
+        {
+            ResetEffectHandleId();
+        }
+
+        [Test]
+        public void CurrentValueReflectsBaseValueWhenUnmodified()
+        {
+            Attribute attribute = new(12f);
+            Assert.AreEqual(12f, attribute.CurrentValue);
+            Assert.AreEqual(12f, attribute.BaseValue);
+        }
+
+        [Test]
+        public void ApplyAttributeModificationWithoutHandleMutatesBase()
+        {
+            Attribute attribute = new(10f);
+            AttributeModification modification = new()
+            {
+                attribute = "health",
+                action = ModificationAction.Addition,
+                value = 5f,
+            };
+
+            attribute.ApplyAttributeModification(modification);
+            Assert.AreEqual(15f, attribute.BaseValue);
+            Assert.AreEqual(15f, attribute.CurrentValue);
+        }
+
+        [Test]
+        public void ApplyAndRemoveAttributeModificationWithHandleRecalculates()
+        {
+            Attribute attribute = new(100f);
+            AttributeModification addition = new()
+            {
+                attribute = "health",
+                action = ModificationAction.Addition,
+                value = 25f,
+            };
+
+            AttributeEffect effect = Track(ScriptableObject.CreateInstance<AttributeEffect>());
+            effect.name = "Buff";
+            EffectHandle handle = EffectHandle.CreateInstance(effect);
+
+            attribute.ApplyAttributeModification(addition, handle);
+            Assert.AreEqual(125f, attribute.CurrentValue);
+            Assert.AreEqual(100f, attribute.BaseValue);
+
+            bool removed = attribute.RemoveAttributeModification(handle);
+            Assert.IsTrue(removed);
+            Assert.AreEqual(100f, attribute.CurrentValue);
+        }
+
+        [Test]
+        public void ApplyAttributeModificationWithMultiplicationExecutesInOrder()
+        {
+            Attribute attribute = new(10f);
+            AttributeEffect effect = Track(ScriptableObject.CreateInstance<AttributeEffect>());
+            effect.name = "Stacking";
+            EffectHandle handle = EffectHandle.CreateInstance(effect);
+
+            attribute.ApplyAttributeModification(
+                new AttributeModification
+                {
+                    attribute = "health",
+                    action = ModificationAction.Addition,
+                    value = 5f,
+                },
+                handle
+            );
+            attribute.ApplyAttributeModification(
+                new AttributeModification
+                {
+                    attribute = "health",
+                    action = ModificationAction.Multiplication,
+                    value = 2f,
+                },
+                handle
+            );
+
+            Assert.AreEqual(30f, attribute.CurrentValue);
+        }
+
+        [Test]
+        public void AttributeEqualsSupportsFloatComparisons()
+        {
+            Attribute attribute = new(7.25f);
+            Assert.IsTrue(attribute.Equals(7.25f));
+            Assert.IsTrue(attribute.Equals((double)7.25f));
+            Assert.IsFalse(attribute.Equals(7.5f));
+            Assert.AreEqual("7.25", attribute.ToString());
+        }
+
+        [Test]
+        public void ClearCacheForcesRecalculation()
+        {
+            Attribute attribute = new(10f);
+            AttributeModification addition = new()
+            {
+                attribute = "health",
+                action = ModificationAction.Addition,
+                value = 5f,
+            };
+
+            attribute.ApplyAttributeModification(addition);
+            Assert.AreEqual(15f, attribute.CurrentValue);
+
+            attribute.ClearCache();
+            Assert.AreEqual(15f, attribute.CurrentValue);
+        }
+
+        [Test]
+        public void AddProducesHandleAndAppliesAddition()
+        {
+            Attribute attribute = new(10f);
+
+            EffectHandle handle = attribute.Add(5f);
+            Assert.AreEqual(15f, attribute.CurrentValue);
+            Assert.AreEqual(1L, handle.id);
+
+            bool removed = attribute.RemoveAttributeModification(handle);
+            Assert.IsTrue(removed);
+            Assert.AreEqual(10f, attribute.CurrentValue);
+        }
+
+        [Test]
+        public void SubtractStacksAsNegativeAddition()
+        {
+            Attribute attribute = new(20f);
+
+            EffectHandle addition = attribute.Add(5f);
+            EffectHandle subtraction = attribute.Subtract(8f);
+            EffectHandle multiplier = attribute.Multiply(2f);
+
+            Assert.AreEqual(34f, attribute.CurrentValue);
+
+            bool subtractionRemoved = attribute.RemoveAttributeModification(subtraction);
+            Assert.IsTrue(subtractionRemoved);
+            Assert.AreEqual(50f, attribute.CurrentValue);
+
+            attribute.RemoveAttributeModification(addition);
+            attribute.RemoveAttributeModification(multiplier);
+        }
+
+        [Test]
+        public void DivideAppliesReciprocalMultiplication()
+        {
+            Attribute attribute = new(12f);
+
+            EffectHandle addition = attribute.Add(6f);
+            EffectHandle division = attribute.Divide(3f);
+
+            Assert.AreEqual(6f, attribute.CurrentValue);
+
+            bool divisionRemoved = attribute.RemoveAttributeModification(division);
+            Assert.IsTrue(divisionRemoved);
+            Assert.AreEqual(18f, attribute.CurrentValue);
+
+            attribute.RemoveAttributeModification(addition);
+        }
+
+        [Test]
+        public void DivideThrowsWhenValueIsZero()
+        {
+            Attribute attribute = new(10f);
+            Assert.Throws<ArgumentException>(() => attribute.Divide(0f));
+        }
+
+        [Test]
+        public void ArithmeticHelpersThrowWhenValueIsNotFinite()
+        {
+            Attribute attribute = new(5f);
+
+            Assert.Throws<ArgumentException>(() => attribute.Add(float.NaN));
+            Assert.Throws<ArgumentException>(() => attribute.Subtract(float.PositiveInfinity));
+            Assert.Throws<ArgumentException>(() => attribute.Multiply(float.NegativeInfinity));
+            Assert.Throws<ArgumentException>(() => attribute.Divide(float.PositiveInfinity));
+        }
+    }
+}

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

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 6cef49ba760748098e3c1fc18a7b1142
+timeCreated: 1761249381

package/Tests/Runtime/Tags/EffectBehaviorTests.cs

@@ -0,0 +1,184 @@
+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 EffectBehaviorTests : TagsTestBase
+    {
+        [SetUp]
+        public void SetUp()
+        {
+            ResetEffectHandleId();
+            RecordingEffectBehavior.Reset();
+        }
+
+        [UnityTest]
+        public IEnumerator LifecycleCallbacksProvideContextData()
+        {
+            (GameObject entity, EffectHandler handler, _, _) = CreateEntity();
+
+            PeriodicEffectDefinition periodicDefinition = new()
+            {
+                name = "Pulse",
+                initialDelay = 0f,
+                interval = 0.05f,
+                maxTicks = 1,
+            };
+
+            AttributeEffect effect = CreateEffect(
+                "Lifecycle",
+                e =>
+                {
+                    e.periodicEffects.Add(periodicDefinition);
+                }
+            );
+
+            RecordingEffectBehavior behavior = Track(
+                ScriptableObject.CreateInstance<RecordingEffectBehavior>()
+            );
+            effect.behaviors.Add(behavior);
+
+            EffectHandle handle = handler.ApplyEffect(effect).Value;
+            Assert.AreEqual(1, RecordingEffectBehavior.ApplyCount);
+            Assert.AreEqual(
+                1,
+                RecordingEffectBehavior.ApplyContexts.Count,
+                "OnApply should fire immediately."
+            );
+
+            yield return null;
+            yield return null;
+
+            Assert.IsNotEmpty(
+                RecordingEffectBehavior.TickContexts,
+                "OnTick should run after Update."
+            );
+
+            yield return new WaitForSeconds(0.08f);
+
+            Assert.AreEqual(
+                1,
+                RecordingEffectBehavior.PeriodicInvocations.Count,
+                "Expected one periodic tick."
+            );
+
+            int removeCountBefore = RecordingEffectBehavior.RemoveCount;
+            handler.RemoveEffect(handle);
+            Assert.AreEqual(removeCountBefore + 1, RecordingEffectBehavior.RemoveCount);
+            Assert.AreEqual(
+                1,
+                RecordingEffectBehavior.RemoveContexts.Count,
+                "OnRemove should fire once."
+            );
+
+            EffectBehaviorContext applyContext = RecordingEffectBehavior.ApplyContexts[0];
+            Assert.AreSame(handler, applyContext.handler);
+            Assert.AreSame(entity, applyContext.Target);
+            Assert.AreEqual(effect, applyContext.Effect);
+            Assert.AreEqual(0f, applyContext.deltaTime);
+
+            EffectBehaviorContext tickContext = RecordingEffectBehavior.TickContexts[0];
+            Assert.AreSame(handler, tickContext.handler);
+            Assert.AreSame(entity, tickContext.Target);
+            Assert.AreEqual(effect, tickContext.Effect);
+            Assert.Greater(tickContext.deltaTime, 0f);
+
+            RecordingEffectBehavior.PeriodicInvocation periodicInvocation =
+                RecordingEffectBehavior.PeriodicInvocations[0];
+            Assert.AreSame(handler, periodicInvocation.Context.handler);
+            Assert.AreSame(entity, periodicInvocation.Context.Target);
+            Assert.AreEqual(effect, periodicInvocation.Context.Effect);
+            Assert.Greater(periodicInvocation.Context.deltaTime, 0f);
+            Assert.AreSame(periodicDefinition, periodicInvocation.TickContext.definition);
+            Assert.AreEqual(1, periodicInvocation.TickContext.executedTicks);
+            Assert.GreaterOrEqual(periodicInvocation.TickContext.currentTime, 0f);
+
+            EffectBehaviorContext removeContext = RecordingEffectBehavior.RemoveContexts[0];
+            Assert.AreSame(handler, removeContext.handler);
+            Assert.AreSame(entity, removeContext.Target);
+            Assert.AreEqual(effect, removeContext.Effect);
+            Assert.AreEqual(0f, removeContext.deltaTime);
+        }
+
+        [UnityTest]
+        public IEnumerator PeriodicTickContextTracksExecutedTicksAndTime()
+        {
+            (GameObject entity, EffectHandler handler, _, _) = CreateEntity();
+
+            PeriodicEffectDefinition periodicDefinition = new()
+            {
+                name = "Stacking Pulse",
+                initialDelay = 0f,
+                interval = 0.05f,
+                maxTicks = 3,
+            };
+
+            AttributeEffect effect = CreateEffect(
+                "Periodic",
+                e =>
+                {
+                    e.periodicEffects.Add(periodicDefinition);
+                }
+            );
+
+            RecordingEffectBehavior behavior = Track(
+                ScriptableObject.CreateInstance<RecordingEffectBehavior>()
+            );
+            effect.behaviors.Add(behavior);
+
+            EffectHandle handle = handler.ApplyEffect(effect).Value;
+
+            yield return new WaitForSeconds(0.18f);
+
+            Assert.AreEqual(
+                3,
+                RecordingEffectBehavior.PeriodicInvocations.Count,
+                "Expected periodic callbacks for each executed tick."
+            );
+
+            for (int i = 0; i < RecordingEffectBehavior.PeriodicInvocations.Count; ++i)
+            {
+                RecordingEffectBehavior.PeriodicInvocation invocation =
+                    RecordingEffectBehavior.PeriodicInvocations[i];
+                Assert.AreSame(periodicDefinition, invocation.TickContext.definition);
+                Assert.AreEqual(i + 1, invocation.TickContext.executedTicks);
+                Assert.Greater(invocation.Context.deltaTime, 0f);
+
+                if (i > 0)
+                {
+                    float previousTime = RecordingEffectBehavior
+                        .PeriodicInvocations[i - 1]
+                        .TickContext
+                        .currentTime;
+                    Assert.GreaterOrEqual(invocation.TickContext.currentTime, previousTime);
+                }
+            }
+
+            handler.RemoveEffect(handle);
+        }
+
+        private (
+            GameObject entity,
+            EffectHandler handler,
+            TestAttributesComponent attributes,
+            TagHandler tags
+        ) CreateEntity()
+        {
+            GameObject entity = CreateTrackedGameObject(
+                "EffectBehaviorEntity",
+                typeof(TestAttributesComponent)
+            );
+            return (
+                entity,
+                entity.GetComponent<EffectHandler>(),
+                entity.GetComponent<TestAttributesComponent>(),
+                entity.GetComponent<TagHandler>()
+            );
+        }
+    }
+}

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

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 978c882cc7a7493b934680f4aef33214
+timeCreated: 1761254817