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

package/Runtime/Tags/EffectStackKey.cs

@@ -0,0 +1,79 @@
+namespace WallstopStudios.UnityHelpers.Tags
+{
+    using System;
+    using WallstopStudios.UnityHelpers.Core.Helper;
+
+    /// <summary>
+    /// Key used to group effect handles for stacking decisions.
+    /// </summary>
+    internal readonly struct EffectStackKey : IEquatable<EffectStackKey>
+    {
+        private readonly EffectStackGroup _group;
+        private readonly AttributeEffect _effect;
+        private readonly string _customKey;
+
+        private EffectStackKey(EffectStackGroup group, AttributeEffect effect, string customKey)
+        {
+            _group = group;
+            _effect = effect;
+            _customKey = customKey;
+        }
+
+        public static EffectStackKey CreateReference(AttributeEffect effect)
+        {
+            return new EffectStackKey(EffectStackGroup.Reference, effect, null);
+        }
+
+        public static EffectStackKey CreateCustom(string customKey)
+        {
+            return new EffectStackKey(EffectStackGroup.CustomKey, null, customKey);
+        }
+
+        public bool Equals(EffectStackKey other)
+        {
+            if (_group != other._group)
+            {
+                return false;
+            }
+
+            return _group switch
+            {
+                EffectStackGroup.Reference => ReferenceEquals(_effect, other._effect),
+                EffectStackGroup.CustomKey => string.Equals(
+                    _customKey,
+                    other._customKey,
+                    StringComparison.Ordinal
+                ),
+                _ => false,
+            };
+        }
+
+        public override bool Equals(object obj)
+        {
+            return obj is EffectStackKey other && Equals(other);
+        }
+
+        public override int GetHashCode()
+        {
+            return _group switch
+            {
+                EffectStackGroup.Reference => Objects.HashCode(_group, _effect),
+                EffectStackGroup.CustomKey => Objects.HashCode(
+                    _group,
+                    _customKey != null ? StringComparer.Ordinal.GetHashCode(_customKey) : 0
+                ),
+                _ => Objects.HashCode(_group),
+            };
+        }
+
+        public static bool operator ==(EffectStackKey left, EffectStackKey right)
+        {
+            return left.Equals(right);
+        }
+
+        public static bool operator !=(EffectStackKey left, EffectStackKey right)
+        {
+            return !(left == right);
+        }
+    }
+}

package/Runtime/Tags/EffectStackKey.cs.meta

@@ -0,0 +1,4 @@
+fileFormatVersion: 2
+guid: 6e83f3c3d7ef4ed28d8f9777084ffcf2
+timeCreated: 1759598400
+

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/Runtime/Tags/TagHandler.cs

@@ -250,6 +250,304 @@ namespace WallstopStudios.UnityHelpers.Tags
             return false;
         }
 
+        /// <summary>
+        /// Checks whether all of the specified tags are currently active.
+        /// Optimized for different collection types with specialized implementations.
+        /// </summary>
+        /// <param name="effectTags">The collection of tags to check.</param>
+        /// <returns><c>true</c> if all tags are active; otherwise, <c>false</c>. Returns <c>false</c> when <paramref name="effectTags"/> is <c>null</c>.</returns>
+        public bool HasAllTags(IEnumerable<string> effectTags)
+        {
+            if (effectTags == null)
+            {
+                return false;
+            }
+
+            switch (effectTags)
+            {
+                case IReadOnlyList<string> list:
+                {
+                    return HasAllTags(list);
+                }
+                case HashSet<string> hashSet:
+                {
+                    foreach (string effectTag in hashSet)
+                    {
+                        if (string.IsNullOrEmpty(effectTag))
+                        {
+                            continue;
+                        }
+                        if (!_tagCount.ContainsKey(effectTag))
+                        {
+                            return false;
+                        }
+                    }
+
+                    return true;
+                }
+                case SortedSet<string> sortedSet:
+                {
+                    foreach (string effectTag in sortedSet)
+                    {
+                        if (string.IsNullOrEmpty(effectTag))
+                        {
+                            continue;
+                        }
+                        if (!_tagCount.ContainsKey(effectTag))
+                        {
+                            return false;
+                        }
+                    }
+
+                    return true;
+                }
+                case Queue<string> queue:
+                {
+                    foreach (string effectTag in queue)
+                    {
+                        if (string.IsNullOrEmpty(effectTag))
+                        {
+                            continue;
+                        }
+                        if (!_tagCount.ContainsKey(effectTag))
+                        {
+                            return false;
+                        }
+                    }
+
+                    return true;
+                }
+                case Stack<string> stack:
+                {
+                    foreach (string effectTag in stack)
+                    {
+                        if (string.IsNullOrEmpty(effectTag))
+                        {
+                            continue;
+                        }
+                        if (!_tagCount.ContainsKey(effectTag))
+                        {
+                            return false;
+                        }
+                    }
+
+                    return true;
+                }
+                case LinkedList<string> linkedList:
+                {
+                    foreach (string effectTag in linkedList)
+                    {
+                        if (string.IsNullOrEmpty(effectTag))
+                        {
+                            continue;
+                        }
+                        if (!_tagCount.ContainsKey(effectTag))
+                        {
+                            return false;
+                        }
+                    }
+
+                    return true;
+                }
+            }
+
+            foreach (string effectTag in effectTags)
+            {
+                if (string.IsNullOrEmpty(effectTag))
+                {
+                    continue;
+                }
+                if (!_tagCount.ContainsKey(effectTag))
+                {
+                    return false;
+                }
+            }
+
+            return true;
+        }
+
+        /// <summary>
+        /// Checks whether all of the specified tags are active.
+        /// Optimized for IReadOnlyList with index-based iteration.
+        /// </summary>
+        /// <param name="effectTags">The list of tags to check.</param>
+        /// <returns><c>true</c> if all of the tags are active, or if the list is empty; otherwise, <c>false</c>.</returns>
+        public bool HasAllTags(IReadOnlyList<string> effectTags)
+        {
+            if (effectTags == null)
+            {
+                return false;
+            }
+
+            for (int i = 0; i < effectTags.Count; ++i)
+            {
+                string effectTag = effectTags[i];
+                if (string.IsNullOrEmpty(effectTag))
+                {
+                    continue;
+                }
+
+                if (!_tagCount.ContainsKey(effectTag))
+                {
+                    return false;
+                }
+            }
+
+            return true;
+        }
+
+        /// <summary>
+        /// Determines whether none of the specified tags are active.
+        /// </summary>
+        /// <param name="effectTags">The collection of tags to inspect.</param>
+        /// <returns>
+        /// <c>true</c> when the collection is <c>null</c>, empty, or every tag is currently inactive; otherwise, <c>false</c>.
+        /// </returns>
+        /// <example>
+        /// <code>
+        /// if (tagHandler.HasNoneOfTags(new[] { "Stunned", "Frozen" }))
+        /// {
+        ///     EnablePlayerInput();
+        /// }
+        /// </code>
+        /// </example>
+        public bool HasNoneOfTags(IEnumerable<string> effectTags)
+        {
+            if (effectTags == null)
+            {
+                return true;
+            }
+
+            return !HasAnyTag(effectTags);
+        }
+
+        /// <summary>
+        /// Determines whether none of the specified tags are active.
+        /// </summary>
+        /// <param name="effectTags">The list of tags to inspect.</param>
+        /// <returns>
+        /// <c>true</c> when the list is <c>null</c>, empty, or every tag is currently inactive; otherwise, <c>false</c>.
+        /// </returns>
+        public bool HasNoneOfTags(IReadOnlyList<string> effectTags)
+        {
+            if (effectTags == null)
+            {
+                return true;
+            }
+
+            return !HasAnyTag(effectTags);
+        }
+
+        /// <summary>
+        /// Attempts to retrieve the active instance count for the specified tag.
+        /// </summary>
+        /// <param name="effectTag">The tag whose count should be retrieved.</param>
+        /// <param name="count">
+        /// When this method returns, contains the active count for the tag (cast to <see cref="int"/>) if found; otherwise, zero.
+        /// </param>
+        /// <returns><c>true</c> if the tag is currently tracked; otherwise, <c>false</c>.</returns>
+        /// <example>
+        /// <code>
+        /// if (tagHandler.TryGetTagCount("Poisoned", out int stacks) && stacks >= 3)
+        /// {
+        ///     TriggerCriticalWarning();
+        /// }
+        /// </code>
+        /// </example>
+        public bool TryGetTagCount(string effectTag, out int count)
+        {
+            if (string.IsNullOrEmpty(effectTag))
+            {
+                count = default;
+                return false;
+            }
+
+            if (_tagCount.TryGetValue(effectTag, out uint uintCount))
+            {
+                count = unchecked((int)uintCount);
+                return true;
+            }
+
+            count = default;
+            return false;
+        }
+
+        /// <summary>
+        /// Retrieves the set of currently active tags into an optional buffer.
+        /// </summary>
+        /// <param name="buffer">
+        /// Optional list to populate. When <c>null</c>, a new list is created. The buffer is cleared before population.
+        /// </param>
+        /// <returns>The populated buffer containing all active tags.</returns>
+        /// <example>
+        /// <code>
+        /// List&lt;string&gt; activeTags = tagHandler.GetActiveTags(_reusableTagBuffer);
+        /// if (activeTags.Contains("Rooted"))
+        /// {
+        ///     DisableMovement();
+        /// }
+        /// </code>
+        /// </example>
+        public List<string> GetActiveTags(List<string> buffer = null)
+        {
+            buffer ??= new List<string>();
+            buffer.Clear();
+            foreach (KeyValuePair<string, uint> entry in _tagCount)
+            {
+                if (entry.Value == 0)
+                {
+                    continue;
+                }
+
+                buffer.Add(entry.Key);
+            }
+
+            return buffer;
+        }
+
+        /// <summary>
+        /// Collects all active effect handles that currently contribute the specified tag.
+        /// </summary>
+        /// <param name="effectTag">The tag to query.</param>
+        /// <param name="buffer">
+        /// Optional list to populate. When <c>null</c>, a new list is created. The buffer is cleared before population.
+        /// </param>
+        /// <returns>The populated buffer containing matching effect handles.</returns>
+        /// <example>
+        /// <code>
+        /// List&lt;EffectHandle&gt; handles = tagHandler.GetHandlesWithTag("Burning", _handleBuffer);
+        /// foreach (EffectHandle handle in handles)
+        /// {
+        ///     effectHandler.RemoveEffect(handle);
+        /// }
+        /// </code>
+        /// </example>
+        public List<EffectHandle> GetHandlesWithTag(
+            string effectTag,
+            List<EffectHandle> buffer = null
+        )
+        {
+            buffer ??= new List<EffectHandle>();
+            buffer.Clear();
+            if (string.IsNullOrEmpty(effectTag))
+            {
+                return buffer;
+            }
+
+            foreach (EffectHandle handle in _effectHandles.Values)
+            {
+                if (
+                    handle.effect.effectTags != null
+                    && handle.effect.effectTags.Contains(effectTag)
+                )
+                {
+                    buffer.Add(handle);
+                }
+            }
+
+            return buffer;
+        }
+
         /// <summary>
         /// Applies a tag, incrementing its count. If the tag is new, raises <see cref="OnTagAdded"/>.
         /// Otherwise, raises <see cref="OnTagCountChanged"/>.
@@ -261,22 +559,52 @@ namespace WallstopStudios.UnityHelpers.Tags
         }
 
         /// <summary>
-        /// Removes one or all instances of a tag.
+        /// Removes all instances of the specified tag and returns the contributing effect handles.
         /// </summary>
         /// <param name="effectTag">The tag to remove.</param>
-        /// <param name="allInstances">
-        /// If true, completely removes the tag regardless of count.
-        /// If false, decrements the count by 1, removing it only when count reaches 0.
+        /// <param name="buffer">
+        /// Optional list that receives the handles whose effects applied <paramref name="effectTag"/>.
+        /// When <c>null</c>, a new list is created. The buffer is cleared before population.
         /// </param>
-        public void RemoveTag(string effectTag, bool allInstances)
+        /// <returns>
+        /// The populated buffer of handles whose tags were removed. The buffer is empty when the tag was not active.
+        /// </returns>
+        /// <example>
+        /// <code>
+        /// List&lt;EffectHandle&gt; dispelled = tagHandler.RemoveTag("Stunned", _handles);
+        /// foreach (EffectHandle handle in dispelled)
+        /// {
+        ///     NotifyDispel(handle);
+        /// }
+        /// </code>
+        /// </example>
+        public List<EffectHandle> RemoveTag(string effectTag, List<EffectHandle> buffer = null)
         {
-            if (allInstances)
+            buffer ??= new List<EffectHandle>();
+            buffer.Clear();
+            if (string.IsNullOrEmpty(effectTag))
             {
-                _tagCount.Remove(effectTag);
-                return;
+                return buffer;
+            }
+
+            foreach (EffectHandle handle in _effectHandles.Values)
+            {
+                if (
+                    handle.effect.effectTags != null
+                    && handle.effect.effectTags.Contains(effectTag)
+                )
+                {
+                    buffer.Add(handle);
+                }
             }
 
-            InternalRemoveTag(effectTag);
+            foreach (EffectHandle handle in buffer)
+            {
+                ForceRemoveTags(handle);
+            }
+
+            InternalRemoveTag(effectTag, allInstances: true);
+            return buffer;
         }
 
         /// <summary>
@@ -292,7 +620,7 @@ namespace WallstopStudios.UnityHelpers.Tags
                 return;
             }
 
-            ForceApplyEffect(handle.effect);
+            ApplyEffectTags(handle.effect);
         }
 
         /// <summary>
@@ -302,10 +630,7 @@ namespace WallstopStudios.UnityHelpers.Tags
         /// <param name="effect">The effect containing tags to apply.</param>
         public void ForceApplyEffect(AttributeEffect effect)
         {
-            foreach (string effectTag in effect.effectTags)
-            {
-                InternalApplyTag(effectTag);
-            }
+            ApplyEffectTags(effect);
         }
 
         /// <summary>
@@ -321,11 +646,7 @@ namespace WallstopStudios.UnityHelpers.Tags
                 return false;
             }
 
-            foreach (string effectTag in appliedHandle.effect.effectTags)
-            {
-                InternalRemoveTag(effectTag);
-            }
-
+            RemoveEffectTags(appliedHandle.effect);
             return true;
         }
 
@@ -346,7 +667,7 @@ namespace WallstopStudios.UnityHelpers.Tags
             }
         }
 
-        private void InternalRemoveTag(string effectTag)
+        private void InternalRemoveTag(string effectTag, bool allInstances)
         {
             if (!_tagCount.TryGetValue(effectTag, out uint count))
             {
@@ -355,7 +676,14 @@ namespace WallstopStudios.UnityHelpers.Tags
 
             if (count != 0)
             {
-                --count;
+                if (!allInstances)
+                {
+                    --count;
+                }
+                else
+                {
+                    count = 0;
+                }
             }
 
             if (count == 0)
@@ -369,5 +697,31 @@ namespace WallstopStudios.UnityHelpers.Tags
                 OnTagCountChanged?.Invoke(effectTag, count);
             }
         }
+
+        private void ApplyEffectTags(AttributeEffect effect)
+        {
+            if (effect.effectTags == null)
+            {
+                return;
+            }
+
+            foreach (string effectTag in effect.effectTags)
+            {
+                InternalApplyTag(effectTag);
+            }
+        }
+
+        private void RemoveEffectTags(AttributeEffect effect)
+        {
+            if (effect.effectTags == null)
+            {
+                return;
+            }
+
+            foreach (string effectTag in effect.effectTags)
+            {
+                InternalRemoveTag(effectTag, allInstances: false);
+            }
+        }
     }
 }