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

package/Runtime/Tags/AttributeEffect.cs

@@ -9,10 +9,61 @@ namespace WallstopStudios.UnityHelpers.Tags
     using Core.Extension;
     using Core.Helper;
     using UnityEngine;
+    using WallstopStudios.UnityHelpers.Core.Attributes;
+    using WallstopStudios.UnityHelpers.Utils;
 #if ODIN_INSPECTOR
     using Sirenix.OdinInspector;
 #endif
 
+    /// <summary>
+    /// Determines which handles are considered the "same stack" when evaluating stacking policies.
+    /// </summary>
+    public enum EffectStackGroup
+    {
+        [Obsolete("Please use a valid EffectStackGroup instead.")]
+        None = 0,
+
+        /// <summary>
+        /// Uses the effect asset reference. Each ScriptableObject instance is its own group.
+        /// </summary>
+        Reference = 1,
+
+        /// <summary>
+        /// Uses a custom string key supplied via <see cref="AttributeEffect.stackGroupKey"/>.
+        /// Effects with matching keys share a stack regardless of asset reference.
+        /// </summary>
+        CustomKey = 2,
+    }
+
+    /// <summary>
+    /// Describes how additional applications of an effect interact with existing stacks.
+    /// </summary>
+    public enum EffectStackingMode
+    {
+        [Obsolete("Please use a valid EffectStackingMode instead.")]
+        None = 0,
+
+        /// <summary>
+        /// Always create a new stack (subject to optional stack limit).
+        /// </summary>
+        Stack = 1,
+
+        /// <summary>
+        /// Reuse the first existing stack and refresh duration if possible.
+        /// </summary>
+        Refresh = 2,
+
+        /// <summary>
+        /// Remove existing stacks sharing the same group before creating a new one.
+        /// </summary>
+        Replace = 3,
+
+        /// <summary>
+        /// Ignore new applications when a stack is already active.
+        /// </summary>
+        Ignore = 4,
+    }
+
     /// <summary>
     /// Reusable, data‑driven bundle of stat modifications, tags, and cosmetic feedback.
     /// Serves as the authoring unit for buffs, debuffs, and status effects.
@@ -52,6 +103,7 @@ namespace WallstopStudios.UnityHelpers.Tags
     /// </para>
     /// </remarks>
     [Serializable]
+    [CreateAssetMenu(menuName = "Wallstop Studios/Unity Helpers/Attribute Effect")]
     public sealed class AttributeEffect :
 #if ODIN_INSPECTOR
         SerializedScriptableObject
@@ -72,24 +124,31 @@ namespace WallstopStudios.UnityHelpers.Tags
         /// The list of attribute modifications to apply when this effect is activated.
         /// Each modification specifies an attribute name, action type, and value.
         /// </summary>
-        public readonly List<AttributeModification> modifications = new();
+        public List<AttributeModification> modifications = new();
+
+        /// <summary>
+        /// Periodic modifier sets executed on a cadence while the effect remains active.
+        /// </summary>
+        public List<PeriodicEffectDefinition> periodicEffects = new();
 
         /// <summary>
         /// Specifies how long this effect should persist (Instant, Duration, or Infinite).
         /// </summary>
         public ModifierDurationType durationType = ModifierDurationType.Duration;
 
-#if ODIN_INSPECTOR
-        [ShowIf("@durationType == ModifierDurationType.Duration")]
-#endif
         /// <summary>
         /// The duration in seconds for this effect. Only used when <see cref="durationType"/> is <see cref="ModifierDurationType.Duration"/>.
         /// </summary>
-        public float duration;
-
 #if ODIN_INSPECTOR
         [ShowIf("@durationType == ModifierDurationType.Duration")]
+#else
+        [WShowIf(
+            nameof(durationType),
+            expectedValues: new object[] { ModifierDurationType.Duration }
+        )]
 #endif
+        public float duration;
+
         /// <summary>
         /// If true, reapplying this effect while it's already active will reset the duration timer.
         /// Only used when <see cref="durationType"/> is <see cref="ModifierDurationType.Duration"/>.
@@ -98,6 +157,14 @@ namespace WallstopStudios.UnityHelpers.Tags
         /// A poison effect with resetDurationOnReapplication=true will restart its 5-second timer
         /// each time the poison is reapplied, preventing stacking but extending the effect.
         /// </example>
+#if ODIN_INSPECTOR
+        [ShowIf("@durationType == ModifierDurationType.Duration")]
+#else
+        [WShowIf(
+            nameof(durationType),
+            expectedValues: new object[] { ModifierDurationType.Duration }
+        )]
+#endif
         public bool resetDurationOnReapplication;
 
         /// <summary>
@@ -115,11 +182,195 @@ namespace WallstopStudios.UnityHelpers.Tags
         /// These are applied when the effect becomes active and removed when it expires.
         /// </summary>
         [JsonIgnore]
-        public readonly List<CosmeticEffectData> cosmeticEffects = new();
+        public List<CosmeticEffectData> cosmeticEffects = new();
 
-        private List<string> CosmeticEffectsForJson =>
-            cosmeticEffects?.Select(cosmeticEffectData => cosmeticEffectData.name).ToList()
-            ?? new List<string>(0);
+        /// <summary>
+        /// Custom behaviours instantiated per active handle.
+        /// </summary>
+        [JsonIgnore]
+        public List<EffectBehavior> behaviors = new();
+
+        /// <summary>
+        /// Determines how this effect groups stacks for stacking decisions.
+        /// </summary>
+        public EffectStackGroup stackGroup = EffectStackGroup.Reference;
+
+        /// <summary>
+        /// Optional stack key used when <see cref="stackGroup"/> is set to <see cref="EffectStackGroup.CustomKey"/>.
+        /// </summary>
+        public string stackGroupKey;
+
+        /// <summary>
+        /// Determines how successive applications interact with existing stacks for the same group.
+        /// </summary>
+        public EffectStackingMode stackingMode = EffectStackingMode.Refresh;
+
+        /// <summary>
+        /// Optional cap on simultaneous stacks when <see cref="stackingMode"/> is <see cref="EffectStackingMode.Stack"/>.
+        /// A value of 0 means unlimited stacks.
+        /// </summary>
+        [Min(0)]
+        public int maximumStacks;
+
+        /// <summary>
+        /// Determines whether this effect applies the specified tag.
+        /// </summary>
+        /// <param name="effectTag">The tag to check.</param>
+        /// <returns><c>true</c> if the tag is present; otherwise, <c>false</c>.</returns>
+        public bool HasTag(string effectTag)
+        {
+            if (effectTags == null || string.IsNullOrEmpty(effectTag))
+            {
+                return false;
+            }
+
+            for (int i = 0; i < effectTags.Count; ++i)
+            {
+                if (string.Equals(effectTags[i], effectTag, StringComparison.Ordinal))
+                {
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        /// <summary>
+        /// Determines whether this effect applies any of the specified tags.
+        /// </summary>
+        /// <param name="effectTagsToCheck">The tags to inspect.</param>
+        /// <returns><c>true</c> if at least one tag is applied; otherwise, <c>false</c>.</returns>
+        public bool HasAnyTag(IEnumerable<string> effectTagsToCheck)
+        {
+            if (effectTags == null || effectTagsToCheck == null)
+            {
+                return false;
+            }
+
+            switch (effectTagsToCheck)
+            {
+                case IReadOnlyList<string> list:
+                {
+                    return HasAnyTag(list);
+                }
+                case HashSet<string> hashSet:
+                {
+                    foreach (string candidate in hashSet)
+                    {
+                        if (string.IsNullOrEmpty(candidate))
+                        {
+                            continue;
+                        }
+
+                        if (HasTag(candidate))
+                        {
+                            return true;
+                        }
+                    }
+
+                    return false;
+                }
+            }
+
+            foreach (string candidate in effectTagsToCheck)
+            {
+                if (string.IsNullOrEmpty(candidate))
+                {
+                    continue;
+                }
+
+                if (HasTag(candidate))
+                {
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        /// <summary>
+        /// Determines whether this effect applies any of the specified tags.
+        /// Optimized for indexed collections.
+        /// </summary>
+        /// <param name="effectTagsToCheck">The tags to inspect.</param>
+        /// <returns><c>true</c> if at least one tag is applied; otherwise, <c>false</c>.</returns>
+        public bool HasAnyTag(IReadOnlyList<string> effectTagsToCheck)
+        {
+            if (effectTags == null || effectTagsToCheck == null)
+            {
+                return false;
+            }
+
+            for (int i = 0; i < effectTagsToCheck.Count; ++i)
+            {
+                string candidate = effectTagsToCheck[i];
+                if (string.IsNullOrEmpty(candidate))
+                {
+                    continue;
+                }
+
+                if (HasTag(candidate))
+                {
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        /// <summary>
+        /// Determines whether this effect contains modifications for the specified attribute.
+        /// </summary>
+        /// <param name="attributeName">The attribute name to inspect.</param>
+        /// <returns><c>true</c> if the effect modifies <paramref name="attributeName"/>; otherwise, <c>false</c>.</returns>
+        public bool ModifiesAttribute(string attributeName)
+        {
+            if (modifications == null || string.IsNullOrEmpty(attributeName))
+            {
+                return false;
+            }
+
+            for (int i = 0; i < modifications.Count; ++i)
+            {
+                AttributeModification modification = modifications[i];
+                if (string.Equals(modification.attribute, attributeName, StringComparison.Ordinal))
+                {
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        /// <summary>
+        /// Copies all modifications that affect the specified attribute into the provided buffer.
+        /// </summary>
+        /// <param name="attributeName">The attribute to filter by.</param>
+        /// <param name="buffer">The destination buffer. Existing entries are preserved.</param>
+        /// <returns>The number of modifications added to <paramref name="buffer"/>.</returns>
+        public List<AttributeModification> GetModifications(
+            string attributeName,
+            List<AttributeModification> buffer = null
+        )
+        {
+            buffer ??= new List<AttributeModification>();
+            buffer.Clear();
+            if (modifications == null || string.IsNullOrEmpty(attributeName))
+            {
+                return buffer;
+            }
+
+            for (int i = 0; i < modifications.Count; ++i)
+            {
+                AttributeModification modification = modifications[i];
+                if (string.Equals(modification.attribute, attributeName, StringComparison.Ordinal))
+                {
+                    buffer.Add(modification);
+                }
+            }
+
+            return buffer;
+        }
 
         /// <summary>
         /// Converts this effect to a JSON string representation including all modifications, tags, and cosmetic effects.
@@ -138,6 +389,10 @@ namespace WallstopStudios.UnityHelpers.Tags
             }.ToJson();
         }
 
+        private List<string> CosmeticEffectsForJson =>
+            cosmeticEffects?.Select(cosmeticEffectData => cosmeticEffectData.name).ToList()
+            ?? new List<string>(0);
+
         private string BuildDescription()
         {
             if (modifications == null)
@@ -145,7 +400,9 @@ namespace WallstopStudios.UnityHelpers.Tags
                 return nameof(AttributeEffect);
             }
 
-            StringBuilder descriptionBuilder = new();
+            using PooledResource<StringBuilder> stringBuilderBuffer = Buffers.StringBuilder.Get(
+                out StringBuilder descriptionBuilder
+            );
             for (int i = 0; i < modifications.Count; ++i)
             {
                 AttributeModification modification = modifications[i];
@@ -218,6 +475,16 @@ namespace WallstopStudios.UnityHelpers.Tags
             return descriptionBuilder.ToString();
         }
 
+        internal EffectStackKey GetStackKey()
+        {
+            if (stackGroup == EffectStackGroup.CustomKey && !string.IsNullOrEmpty(stackGroupKey))
+            {
+                return EffectStackKey.CreateCustom(stackGroupKey);
+            }
+
+            return EffectStackKey.CreateReference(this);
+        }
+
         /// <summary>
         /// Determines whether this effect is equal to another effect by comparing all fields.
         /// This is needed because deserialization creates new instances, so reference equality is insufficient.

package/Runtime/Tags/AttributeModification.cs

@@ -1,62 +1,68 @@
 namespace WallstopStudios.UnityHelpers.Tags
 {
     using System;
+    using System.Text.Json.Serialization;
     using Core.Extension;
     using Core.Helper;
+    using ProtoBuf;
 
     /// <summary>
-    /// Declarative change to an <see cref="Attribute"/> value (add, multiply, or override).
-    /// Forms the stat‑modification payload inside an <see cref="AttributeEffect"/>.
+    /// Declarative change applied to an <see cref="Attribute"/>.
+    /// Each instance represents a single operation (add, multiply, or override) referenced by an <see cref="AttributeEffect"/>.
     /// </summary>
     /// <remarks>
+    /// <para>Key properties:</para>
+    /// <list type="bullet">
+    /// <item><description>Non-destructive: temporary handles can add/remove modifications without mutating base values.</description></item>
+    /// <item><description>Deterministic ordering: <see cref="Attribute"/> always processes Addition, then Multiplication, then Override.</description></item>
+    /// <item><description>Flexible authoring: supports both instant (permanent) and duration-based effects.</description></item>
+    /// </list>
+    /// <para>Stack processing order:</para>
+    /// <list type="number">
+    /// <item><description>Addition (value += x)</description></item>
+    /// <item><description>Multiplication (value *= x)</description></item>
+    /// <item><description>Override (value = x)</description></item>
+    /// </list>
     /// <para>
-    /// Problems solved:
-    /// - Non‑destructive stat changes that can be added/removed per effect instance
-    /// - Clear stacking rules via action ordering
-    /// - Works with both permanent (Instant) and temporary (Duration/Infinite) effects
+    /// The <see cref="attribute"/> field must match an <see cref="Attribute"/> field on the target <see cref="AttributesComponent"/>.
+    /// The Attribute Metadata Cache generator can provide editor dropdowns to avoid typos. Unknown names are ignored at runtime.
     /// </para>
-    /// <para>
-    /// Stacking and order: Modifications are applied in this order across a target attribute:
-    /// 1) Addition (value += x) → 2) Multiplication (value *= x) → 3) Override (value = x).
-    /// This means Overrides always win last; use with care.
-    /// </para>
-    /// <para>
-    /// Addressing: The <see cref="attribute"/> field names an <see cref="AttributesComponent"/> field of type
-    /// <see cref="Attribute"/>. Misspelled or missing names are ignored at runtime to keep effects robust.
-    /// Use the Attribute Metadata Cache generator to populate editor dropdowns and avoid typos.
-    /// </para>
-    /// <para>
-    /// Examples:
+    /// <para>Sample definitions:</para>
     /// <code>
-    /// // +50 flat Health
+    /// // +50 flat health
     /// new AttributeModification { attribute = "Health", action = ModificationAction.Addition, value = 50f };
     ///
-    /// // +50% Speed (i.e., multiply by 1.5)
+    /// // +50% speed
     /// new AttributeModification { attribute = "Speed", action = ModificationAction.Multiplication, value = 1.5f };
     ///
-    /// // Set Defense to 0 (hard override)
+    /// // Hard-set defense to 0
     /// new AttributeModification { attribute = "Defense", action = ModificationAction.Override, value = 0f };
     /// </code>
-    /// </para>
-    /// <para>
-    /// Tips:
-    /// - Prefer Addition for small buffs/debuffs; prefer Multiplication for % changes.
-    /// - Avoid frequent Overrides unless you intend to fully clamp a value.
-    /// - Use negative Addition values to subtract; use Multiplication < 1.0 for % reductions.
-    /// </para>
+    /// <para>Authoring tips:</para>
+    /// <list type="bullet">
+    /// <item><description>Use Addition for flat buffs/debuffs; Multiplication for percentage-style adjustments.</description></item>
+    /// <item><description>Reserve Override for hard clamps (it always executes last).</description></item>
+    /// <item><description>Negative Addition subtracts; Multiplication values below 1.0 reduce the attribute.</description></item>
+    /// </list>
     /// </remarks>
     [Serializable]
-    public struct AttributeModification : IEquatable<AttributeModification>
+    [ProtoContract]
+    public struct AttributeModification
+        : IEquatable<AttributeModification>,
+            IComparable<AttributeModification>,
+            IComparable
     {
         /// <summary>
         /// The name of the attribute to modify. This should match a field name in an <see cref="AttributesComponent"/> subclass.
         /// </summary>
         [StringInList(typeof(AttributeUtilities), nameof(AttributeUtilities.GetAllAttributeNames))]
+        [ProtoMember(1)]
         public string attribute;
 
         /// <summary>
         /// The type of modification action to perform (Addition, Multiplication, or Override).
         /// </summary>
+        [ProtoMember(2)]
         public ModificationAction action;
 
         /// <summary>
@@ -65,8 +71,17 @@ namespace WallstopStudios.UnityHelpers.Tags
         /// <para>- Multiplication: The multiplier to apply (e.g., 1.5 for +50%, 0.5 for -50%)</para>
         /// <para>- Override: The new absolute value to set</para>
         /// </summary>
+        [ProtoMember(3)]
         public float value;
 
+        [JsonConstructor]
+        public AttributeModification(string attribute, ModificationAction action, float value)
+        {
+            this.attribute = attribute;
+            this.action = action;
+            this.value = value;
+        }
+
         /// <summary>
         /// Converts this modification to a JSON string representation.
         /// </summary>
@@ -76,6 +91,21 @@ namespace WallstopStudios.UnityHelpers.Tags
             return this.ToJson();
         }
 
+        public int CompareTo(object obj)
+        {
+            if (obj is AttributeModification other)
+            {
+                return CompareTo(other);
+            }
+
+            return -1;
+        }
+
+        public int CompareTo(AttributeModification other)
+        {
+            return ((int)action).CompareTo((int)other.action);
+        }
+
         /// <summary>
         /// Determines whether two attribute modifications are not equal.
         /// </summary>