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

package/Runtime/Tags/PeriodicEffectDefinition.cs

@@ -0,0 +1,102 @@
+namespace WallstopStudios.UnityHelpers.Tags
+{
+    using System;
+    using System.Collections.Generic;
+    using ProtoBuf;
+    using UnityEngine;
+
+    /// <summary>
+    /// Authoring data for a periodic modifier bundle that executes on a cadence while an effect is active.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The owning <see cref="EffectHandler"/> evaluates each periodic definition after <see cref="initialDelay"/>, applies the configured
+    /// <see cref="modifications"/>, and repeats every <see cref="interval"/> seconds until <see cref="maxTicks"/> is reached or the effect ends.
+    /// </para>
+    /// <para>
+    /// Definitions are processed in list order and maintain independent runtime state per <see cref="EffectHandle"/>, enabling designers to mix
+    /// damage-over-time, heal-over-time, or custom triggers alongside bespoke <see cref="EffectBehavior"/> implementations.
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// <code language="csharp">
+    /// using System.Collections.Generic;
+    /// using UnityEngine;
+    /// using WallstopStudios.UnityHelpers.Tags;
+    ///
+    /// public sealed class BurnEffectAuthoring : MonoBehaviour
+    /// {
+    ///     [SerializeField]
+    ///     private AttributeEffect burnEffect;
+    ///
+    ///     [SerializeField]
+    ///     private EffectHandler effectHandler;
+    ///
+    ///     public void ApplyBurn(GameObject target)
+    ///     {
+    ///         PeriodicEffectDefinition burnTick = new PeriodicEffectDefinition
+    ///         {
+    ///             name = "Burn Damage",
+    ///             initialDelay = 0.5f,
+    ///             interval = 1.0f,
+    ///             maxTicks = 5,
+    ///             modifications = new List<AttributeModification>
+    ///             {
+    ///                 new AttributeModification("Health", ModificationAction.Addition, -5f),
+    ///             },
+    ///         };
+    ///
+    ///         burnEffect.periodicEffects.Add(burnTick);
+    ///
+    ///         if (effectHandler == null)
+    ///         {
+    ///             effectHandler = target.GetComponent<EffectHandler>();
+    ///         }
+    ///
+    ///         EffectHandle? handle = effectHandler.ApplyEffect(burnEffect);
+    ///     }
+    /// }
+    /// </code>
+    /// <para>
+    /// In the example above the handler waits for <c>initialDelay</c>, applies the <see cref="modifications"/> every <c>interval</c> seconds,
+    /// and stops after <see cref="maxTicks"/> executions or as soon as the effect is removed.
+    /// </para>
+    /// </example>
+    [Serializable]
+    [ProtoContract]
+    public sealed class PeriodicEffectDefinition
+    {
+        /// <summary>
+        /// Optional label shown in tooling to help distinguish multiple periodic definitions.
+        /// </summary>
+        [ProtoMember(1)]
+        public string name;
+
+        /// <summary>
+        /// Time (seconds) before the first tick fires after the effect is applied.
+        /// </summary>
+        [Min(0f)]
+        [ProtoMember(2)]
+        public float initialDelay;
+
+        /// <summary>
+        /// Interval (seconds) between ticks once the first tick has executed.
+        /// </summary>
+        [Min(0.01f)]
+        [ProtoMember(3)]
+        public float interval = 1f;
+
+        /// <summary>
+        /// Maximum number of ticks to execute. Zero or negative means unlimited ticks.
+        /// </summary>
+        [Min(0)]
+        [ProtoMember(4)]
+        public int maxTicks;
+
+        /// <summary>
+        /// Attribute modifications applied each time the tick fires.
+        /// </summary>
+        [ProtoMember(5)]
+        public List<AttributeModification> modifications = new();
+    }
+}

package/Runtime/Tags/PeriodicEffectDefinition.cs.meta

@@ -0,0 +1,4 @@
+fileFormatVersion: 2
+guid: 8d763ed3f32f4fbf9bcaca8f24ef1a31
+timeCreated: 1759598400
+

package/Runtime/Tags/PeriodicEffectRuntimeState.cs

@@ -0,0 +1,40 @@
+namespace WallstopStudios.UnityHelpers.Tags
+{
+    using UnityEngine;
+
+    /// <summary>
+    /// Runtime tracking for a periodic effect definition.
+    /// </summary>
+    internal sealed class PeriodicEffectRuntimeState
+    {
+        internal bool IsComplete => definition.maxTicks > 0 && ExecutedTicks >= definition.maxTicks;
+
+        internal float NextTickTime { get; private set; }
+
+        internal int ExecutedTicks { get; private set; }
+
+        internal readonly PeriodicEffectDefinition definition;
+        internal readonly float interval;
+
+        internal PeriodicEffectRuntimeState(PeriodicEffectDefinition definition, float startTime)
+        {
+            this.definition = definition;
+            ExecutedTicks = 0;
+            float clampedInterval = Mathf.Max(0.01f, definition.interval);
+            interval = clampedInterval;
+            NextTickTime = startTime + Mathf.Max(0f, definition.initialDelay);
+        }
+
+        internal bool TryConsumeTick(float currentTime)
+        {
+            if (currentTime < NextTickTime || IsComplete)
+            {
+                return false;
+            }
+
+            ++ExecutedTicks;
+            NextTickTime = currentTime + interval;
+            return true;
+        }
+    }
+}

package/Runtime/Tags/PeriodicEffectRuntimeState.cs.meta

@@ -0,0 +1,4 @@
+fileFormatVersion: 2
+guid: 5af38ac9186645fabd9858dfead3c001
+timeCreated: 1759598400
+

package/Samples~/DI - Zenject/README.md

@@ -71,8 +71,6 @@ public class Enemy : MonoBehaviour
 2. Add the `RelationalComponentsInstaller` component to the same GameObject
 3. Enable **"Assign Scene On Initialize"** to automatically wire all scene components after the container builds (recommended)
 
-![SceneContext Setup](../../Docs/Images/zenject_setup.png)
-
 > 💡 **Beginner tip:** Enable both checkboxes in the inspector:
 >
 > - ✅ **Assign Scene On Initialize** → Auto-wires all scene objects (saves you from calling it manually)

package/Tests/Editor/Attributes/WShowIfPropertyDrawerTests.cs

@@ -0,0 +1,285 @@
+namespace WallstopStudios.UnityHelpers.Tests.Editor.Attributes
+{
+    using System.Reflection;
+    using NUnit.Framework;
+    using UnityEditor;
+    using UnityEngine;
+    using WallstopStudios.UnityHelpers.Core.Attributes;
+    using WallstopStudios.UnityHelpers.Editor.CustomDrawers;
+    using WallstopStudios.UnityHelpers.Tags;
+    using WallstopStudios.UnityHelpers.Tests.Editor.Utils;
+
+    [TestFixture]
+    public sealed class WShowIfPropertyDrawerTests : CommonTestBase
+    {
+        private static readonly FieldInfo AttributeField = typeof(PropertyDrawer).GetField(
+            "m_Attribute",
+            BindingFlags.Instance | BindingFlags.NonPublic
+        );
+
+        [Test]
+        public void BoolConditionHidesFieldWhenFalse()
+        {
+            TestContainer container = CreateScriptableObject<TestContainer>();
+            SerializedObject serializedObject = new(container);
+            serializedObject.Update();
+
+            SerializedProperty dependentProperty = serializedObject.FindProperty(
+                nameof(TestContainer.boolDependent)
+            );
+            Assert.NotNull(dependentProperty);
+
+            WShowIfPropertyDrawer drawer = CreateDrawer(
+                new WShowIfAttribute(nameof(TestContainer.boolCondition))
+            );
+
+            container.boolCondition = false;
+            serializedObject.Update();
+            float hiddenHeight = drawer.GetPropertyHeight(
+                dependentProperty,
+                new GUIContent("boolDependent")
+            );
+            Assert.That(hiddenHeight, Is.Zero);
+
+            container.boolCondition = true;
+            serializedObject.Update();
+            float shownHeight = drawer.GetPropertyHeight(
+                dependentProperty,
+                new GUIContent("boolDependent")
+            );
+            Assert.That(shownHeight, Is.GreaterThan(0f));
+        }
+
+        [Test]
+        public void EnumConditionMatchesExpectedValue()
+        {
+            TestContainer container = CreateScriptableObject<TestContainer>();
+            SerializedObject serializedObject = new(container);
+            serializedObject.Update();
+
+            SerializedProperty dependentProperty = serializedObject.FindProperty(
+                nameof(TestContainer.durationDependent)
+            );
+            Assert.NotNull(dependentProperty);
+
+            WShowIfPropertyDrawer drawer = CreateDrawer(
+                new WShowIfAttribute(
+                    nameof(TestContainer.durationType),
+                    expectedValues: new object[] { ModifierDurationType.Duration }
+                )
+            );
+
+            container.durationType = ModifierDurationType.Instant;
+            serializedObject.Update();
+            float hiddenHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(hiddenHeight, Is.Zero);
+
+            container.durationType = ModifierDurationType.Duration;
+            serializedObject.Update();
+            float shownHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(shownHeight, Is.GreaterThan(0f));
+        }
+
+        [Test]
+        public void EnumConditionHonorsInverseFlag()
+        {
+            TestContainer container = CreateScriptableObject<TestContainer>();
+            SerializedObject serializedObject = new(container);
+            serializedObject.Update();
+
+            SerializedProperty dependentProperty = serializedObject.FindProperty(
+                nameof(TestContainer.inverseDependent)
+            );
+            Assert.NotNull(dependentProperty);
+
+            WShowIfPropertyDrawer drawer = CreateDrawer(
+                new WShowIfAttribute(
+                    nameof(TestContainer.durationType),
+                    inverse: true,
+                    expectedValues: new object[] { ModifierDurationType.Instant }
+                )
+            );
+
+            container.durationType = ModifierDurationType.Instant;
+            serializedObject.Update();
+            float hiddenHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(hiddenHeight, Is.Zero);
+
+            container.durationType = ModifierDurationType.Infinite;
+            serializedObject.Update();
+            float shownHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(shownHeight, Is.GreaterThan(0f));
+        }
+
+        [Test]
+        public void FloatConditionMatchesExpectedValue()
+        {
+            TestContainer container = CreateScriptableObject<TestContainer>();
+            SerializedObject serializedObject = new(container);
+            serializedObject.Update();
+
+            SerializedProperty dependentProperty = serializedObject.FindProperty(
+                nameof(TestContainer.floatDependent)
+            );
+            Assert.NotNull(dependentProperty);
+
+            WShowIfPropertyDrawer drawer = CreateDrawer(
+                new WShowIfAttribute(
+                    nameof(TestContainer.floatCondition),
+                    expectedValues: new object[] { 3.5f }
+                )
+            );
+
+            container.floatCondition = 0f;
+            serializedObject.Update();
+            float hiddenHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(hiddenHeight, Is.Zero);
+
+            container.floatCondition = 3.5f;
+            serializedObject.Update();
+            float shownHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(shownHeight, Is.GreaterThan(0f));
+        }
+
+        [Test]
+        public void DoubleConditionMatchesEquivalentIntExpectedValue()
+        {
+            TestContainer container = CreateScriptableObject<TestContainer>();
+            SerializedObject serializedObject = new(container);
+            serializedObject.Update();
+
+            SerializedProperty dependentProperty = serializedObject.FindProperty(
+                nameof(TestContainer.doubleDependent)
+            );
+            Assert.NotNull(dependentProperty);
+
+            WShowIfPropertyDrawer drawer = CreateDrawer(
+                new WShowIfAttribute(
+                    nameof(TestContainer.doubleCondition),
+                    expectedValues: new object[] { 7 }
+                )
+            );
+
+            container.doubleCondition = 2.5d;
+            serializedObject.Update();
+            float hiddenHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(hiddenHeight, Is.Zero);
+
+            container.doubleCondition = 7d;
+            serializedObject.Update();
+            float shownHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(shownHeight, Is.GreaterThan(0f));
+        }
+
+        [Test]
+        public void IntConditionMatchesExpectedValue()
+        {
+            TestContainer container = CreateScriptableObject<TestContainer>();
+            SerializedObject serializedObject = new(container);
+            serializedObject.Update();
+
+            SerializedProperty dependentProperty = serializedObject.FindProperty(
+                nameof(TestContainer.intDependent)
+            );
+            Assert.NotNull(dependentProperty);
+
+            WShowIfPropertyDrawer drawer = CreateDrawer(
+                new WShowIfAttribute(
+                    nameof(TestContainer.intCondition),
+                    expectedValues: new object[] { 42 }
+                )
+            );
+
+            container.intCondition = 7;
+            serializedObject.Update();
+            float hiddenHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(hiddenHeight, Is.Zero);
+
+            container.intCondition = 42;
+            serializedObject.Update();
+            float shownHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(shownHeight, Is.GreaterThan(0f));
+        }
+
+        [Test]
+        public void StringConditionMatchesExpectedValues()
+        {
+            TestContainer container = CreateScriptableObject<TestContainer>();
+            SerializedObject serializedObject = new(container);
+            serializedObject.Update();
+
+            SerializedProperty dependentProperty = serializedObject.FindProperty(
+                nameof(TestContainer.stringDependent)
+            );
+            Assert.NotNull(dependentProperty);
+
+            WShowIfPropertyDrawer drawer = CreateDrawer(
+                new WShowIfAttribute(
+                    nameof(TestContainer.stringCondition),
+                    expectedValues: new object[] { "alpha", "beta" }
+                )
+            );
+
+            container.stringCondition = "gamma";
+            serializedObject.Update();
+            float hiddenHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(hiddenHeight, Is.Zero);
+
+            container.stringCondition = "alpha";
+            serializedObject.Update();
+            float shownHeight = drawer.GetPropertyHeight(dependentProperty, GUIContent.none);
+            Assert.That(shownHeight, Is.GreaterThan(0f));
+        }
+
+        private static WShowIfPropertyDrawer CreateDrawer(WShowIfAttribute attribute)
+        {
+            WShowIfPropertyDrawer drawer = new();
+            Assert.NotNull(AttributeField);
+            AttributeField.SetValue(drawer, attribute);
+            return drawer;
+        }
+
+        private sealed class TestContainer : ScriptableObject
+        {
+            public bool boolCondition;
+
+            [WShowIf(nameof(boolCondition))]
+            public int boolDependent;
+
+            public ModifierDurationType durationType = ModifierDurationType.Instant;
+
+            [WShowIf(
+                nameof(durationType),
+                expectedValues: new object[] { ModifierDurationType.Duration }
+            )]
+            public int durationDependent;
+
+            [WShowIf(
+                nameof(durationType),
+                inverse: true,
+                expectedValues: new object[] { ModifierDurationType.Instant }
+            )]
+            public int inverseDependent;
+
+            public float floatCondition;
+
+            [WShowIf(nameof(floatCondition), expectedValues: new object[] { 3.5f })]
+            public int floatDependent;
+
+            public double doubleCondition;
+
+            [WShowIf(nameof(doubleCondition), expectedValues: new object[] { 7 })]
+            public int doubleDependent;
+
+            public int intCondition;
+
+            [WShowIf(nameof(intCondition), expectedValues: new object[] { 42 })]
+            public int intDependent;
+
+            public string stringCondition;
+
+            [WShowIf(nameof(stringCondition), expectedValues: new object[] { "alpha", "beta" })]
+            public int stringDependent;
+        }
+    }
+}

package/Tests/Editor/Attributes/WShowIfPropertyDrawerTests.cs.meta

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

package/Tests/Editor/Core/Attributes/RelationalComponentAssignerTests.cs

@@ -24,7 +24,7 @@ namespace WallstopStudios.UnityHelpers.Tests.Core.Attributes
         }
 
         [Test]
-        public void HasRelationalAssignments_RespectsMetadata()
+        public void HasRelationalAssignmentsRespectsMetadata()
         {
             AttributeMetadataCache cache = CreateScriptableObject<AttributeMetadataCache>();
 
@@ -62,7 +62,7 @@ namespace WallstopStudios.UnityHelpers.Tests.Core.Attributes
         }
 
         [Test]
-        public void Assign_IEnumerable_AssignsOnlyRelationalTypes_AndSkipsNulls()
+        public void AssignIEnumerableAssignsOnlyRelationalTypesAndSkipsNulls()
         {
             AttributeMetadataCache cache = CreateScriptableObject<AttributeMetadataCache>();
 

package/Tests/Editor/Utils/ScriptableObjectSingletonTests.cs

@@ -34,6 +34,8 @@ namespace WallstopStudios.UnityHelpers.Tests.Editor.Utils
             yield return null;
             DeleteAssetIfExists("Assets/Resources/CustomPath/CustomPathSingleton.asset");
             yield return null;
+            DeleteFolderIfEmpty("Assets/Resources/CustomPath");
+            yield return null;
 
             // For nested test types, Unity cannot create valid .asset files (no script file).
             // Instead, create in-memory instances so the singleton loader can discover them via FindObjectsOfTypeAll.
@@ -81,6 +83,43 @@ namespace WallstopStudios.UnityHelpers.Tests.Editor.Utils
             }
         }
 
+        private static void DeleteFolderIfEmpty(string folderPath)
+        {
+            if (string.IsNullOrWhiteSpace(folderPath))
+            {
+                return;
+            }
+
+            if (!AssetDatabase.IsValidFolder(folderPath))
+            {
+                return;
+            }
+
+            string[] subFolders = AssetDatabase.GetSubFolders(folderPath);
+            if (subFolders != null && subFolders.Length > 0)
+            {
+                return;
+            }
+
+            string[] assetGuids = AssetDatabase.FindAssets(string.Empty, new[] { folderPath });
+            for (int i = 0; i < assetGuids.Length; i++)
+            {
+                string guid = assetGuids[i];
+                string assetPath = AssetDatabase.GUIDToAssetPath(guid);
+                if (
+                    !string.IsNullOrEmpty(assetPath)
+                    && !string.Equals(assetPath, folderPath, System.StringComparison.Ordinal)
+                )
+                {
+                    return;
+                }
+            }
+
+            AssetDatabase.DeleteAsset(folderPath);
+            AssetDatabase.SaveAssets();
+            AssetDatabase.Refresh();
+        }
+
         private static TType CreateInMemoryInstance<TType>()
             where TType : ScriptableObject
         {
@@ -144,6 +183,8 @@ namespace WallstopStudios.UnityHelpers.Tests.Editor.Utils
             AssetDatabase.SaveAssets();
             AssetDatabase.Refresh();
             yield return null;
+            DeleteFolderIfEmpty("Assets/Resources/CustomPath");
+            yield return null;
             // Prefer public API surface over reflection to clean up the cached instance
             if (TestSingleton.HasInstance)
             {

package/Tests/Runtime/Serialization/JsonSerializationTest.cs

@@ -4,6 +4,7 @@ namespace WallstopStudios.UnityHelpers.Tests.Serialization
     using System.Collections.Generic;
     using System.Linq;
     using System.Runtime.Serialization;
+    using System.Text.Json;
     using System.Text.Json.Serialization;
     using NUnit.Framework;
     using UnityEngine;
@@ -42,9 +43,9 @@ namespace WallstopStudios.UnityHelpers.Tests.Serialization
             using System.Text.Json.JsonDocument doc = System.Text.Json.JsonDocument.Parse(json);
             System.Text.Json.JsonElement root = doc.RootElement;
             Assert.AreEqual(System.Text.Json.JsonValueKind.Object, root.ValueKind);
-            Assert.True(root.TryGetProperty("name", out var name));
-            Assert.True(root.TryGetProperty("type", out var type));
-            Assert.True(root.TryGetProperty("instanceId", out var id));
+            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("Test GameObject", name.GetString());
             StringAssert.Contains("UnityEngine.GameObject", type.GetString());
             Assert.AreEqual(expectedId, id.GetInt32());