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

package/Runtime/Tags/AttributeEffect.cs

@@ -9,11 +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.
@@ -76,22 +126,29 @@ namespace WallstopStudios.UnityHelpers.Tags
         /// </summary>
         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"/>.
@@ -100,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>
@@ -112,6 +177,41 @@ namespace WallstopStudios.UnityHelpers.Tags
         /// </example>
         public List<string> effectTags = new();
 
+        /// <summary>
+        /// A list of cosmetic effect data that defines visual and audio feedback for this effect.
+        /// These are applied when the effect becomes active and removed when it expires.
+        /// </summary>
+        [JsonIgnore]
+        public List<CosmeticEffectData> cosmeticEffects = new();
+
+        /// <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>
@@ -272,17 +372,6 @@ namespace WallstopStudios.UnityHelpers.Tags
             return buffer;
         }
 
-        /// <summary>
-        /// A list of cosmetic effect data that defines visual and audio feedback for this effect.
-        /// These are applied when the effect becomes active and removed when it expires.
-        /// </summary>
-        [JsonIgnore]
-        public List<CosmeticEffectData> cosmeticEffects = new();
-
-        private List<string> CosmeticEffectsForJson =>
-            cosmeticEffects?.Select(cosmeticEffectData => cosmeticEffectData.name).ToList()
-            ?? new List<string>(0);
-
         /// <summary>
         /// Converts this effect to a JSON string representation including all modifications, tags, and cosmetic effects.
         /// </summary>
@@ -300,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)
@@ -382,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/AttributeMetadataCache.cs

@@ -484,9 +484,15 @@ namespace WallstopStudios.UnityHelpers.Tags
             RelationalTypeMetadata[] relationalTypeMetadata
         )
         {
-            _allAttributeNames = allAttributeNames;
-            _typeMetadata = typeMetadata;
-            _relationalTypeMetadata = relationalTypeMetadata;
+            string[] normalizedAttributeNames = SortAttributeNames(allAttributeNames);
+            TypeFieldMetadata[] normalizedTypeMetadata = SortTypeMetadata(typeMetadata);
+            RelationalTypeMetadata[] normalizedRelationalMetadata = SortRelationalTypeMetadata(
+                relationalTypeMetadata
+            );
+
+            _allAttributeNames = normalizedAttributeNames;
+            _typeMetadata = normalizedTypeMetadata;
+            _relationalTypeMetadata = normalizedRelationalMetadata;
             _computedAllAttributeNames = null;
             _computedAllAttributeNamesIncludesTests = false;
             _typeFieldsLookup = null;
@@ -495,6 +501,309 @@ namespace WallstopStudios.UnityHelpers.Tags
             _elementTypeLookup = null;
             UnityEditor.EditorUtility.SetDirty(this);
         }
+
+        private static string[] SortAttributeNames(string[] attributeNames)
+        {
+            if (attributeNames == null || attributeNames.Length == 0)
+            {
+                return Array.Empty<string>();
+            }
+
+            string[] result = new string[attributeNames.Length];
+            Array.Copy(attributeNames, result, attributeNames.Length);
+            Array.Sort(result, StringComparer.Ordinal);
+            return result;
+        }
+
+        private static TypeFieldMetadata[] SortTypeMetadata(TypeFieldMetadata[] typeMetadata)
+        {
+            if (typeMetadata == null || typeMetadata.Length == 0)
+            {
+                return Array.Empty<TypeFieldMetadata>();
+            }
+
+            int nonNullCount = 0;
+            for (int i = 0; i < typeMetadata.Length; i++)
+            {
+                if (typeMetadata[i] != null)
+                {
+                    nonNullCount++;
+                }
+            }
+
+            if (nonNullCount == 0)
+            {
+                return Array.Empty<TypeFieldMetadata>();
+            }
+
+            TypeFieldMetadata[] result = new TypeFieldMetadata[nonNullCount];
+            int resultIndex = 0;
+            for (int i = 0; i < typeMetadata.Length; i++)
+            {
+                TypeFieldMetadata metadata = typeMetadata[i];
+                if (metadata == null)
+                {
+                    continue;
+                }
+
+                string typeName = metadata.typeName ?? string.Empty;
+                string[] fieldNames = metadata.fieldNames ?? Array.Empty<string>();
+                string[] sortedFieldNames =
+                    fieldNames.Length == 0 ? Array.Empty<string>() : CopyAndSort(fieldNames);
+
+                result[resultIndex] = new TypeFieldMetadata(typeName, sortedFieldNames);
+                resultIndex++;
+            }
+
+            Array.Sort(result, CompareTypeFieldMetadata);
+            return result;
+        }
+
+        private static RelationalTypeMetadata[] SortRelationalTypeMetadata(
+            RelationalTypeMetadata[] relationalTypeMetadata
+        )
+        {
+            if (relationalTypeMetadata == null || relationalTypeMetadata.Length == 0)
+            {
+                return Array.Empty<RelationalTypeMetadata>();
+            }
+
+            int nonNullCount = 0;
+            for (int i = 0; i < relationalTypeMetadata.Length; i++)
+            {
+                if (relationalTypeMetadata[i] != null)
+                {
+                    nonNullCount++;
+                }
+            }
+
+            if (nonNullCount == 0)
+            {
+                return Array.Empty<RelationalTypeMetadata>();
+            }
+
+            RelationalTypeMetadata[] result = new RelationalTypeMetadata[nonNullCount];
+            int resultIndex = 0;
+            for (int i = 0; i < relationalTypeMetadata.Length; i++)
+            {
+                RelationalTypeMetadata metadata = relationalTypeMetadata[i];
+                if (metadata == null)
+                {
+                    continue;
+                }
+
+                string typeName = metadata.typeName ?? string.Empty;
+                RelationalFieldMetadata[] sortedFields = SortRelationalFields(metadata.fields);
+                result[resultIndex] = new RelationalTypeMetadata(typeName, sortedFields);
+                resultIndex++;
+            }
+
+            Array.Sort(result, CompareRelationalTypeMetadata);
+            return result;
+        }
+
+        private static RelationalFieldMetadata[] SortRelationalFields(
+            RelationalFieldMetadata[] relationalFields
+        )
+        {
+            if (relationalFields == null || relationalFields.Length == 0)
+            {
+                return Array.Empty<RelationalFieldMetadata>();
+            }
+
+            int nonNullCount = 0;
+            for (int i = 0; i < relationalFields.Length; i++)
+            {
+                if (relationalFields[i] != null)
+                {
+                    nonNullCount++;
+                }
+            }
+
+            if (nonNullCount == 0)
+            {
+                return Array.Empty<RelationalFieldMetadata>();
+            }
+
+            RelationalFieldMetadata[] result = new RelationalFieldMetadata[nonNullCount];
+            int resultIndex = 0;
+            for (int i = 0; i < relationalFields.Length; i++)
+            {
+                RelationalFieldMetadata field = relationalFields[i];
+                if (field == null)
+                {
+                    continue;
+                }
+
+                result[resultIndex] = new RelationalFieldMetadata(
+                    field.fieldName,
+                    field.attributeKind,
+                    field.fieldKind,
+                    field.elementTypeName,
+                    field.isInterface
+                );
+                resultIndex++;
+            }
+
+            Array.Sort(result, CompareRelationalFieldMetadata);
+            return result;
+        }
+
+        private static string[] CopyAndSort(string[] values)
+        {
+            string[] result = new string[values.Length];
+            Array.Copy(values, result, values.Length);
+            Array.Sort(result, StringComparer.Ordinal);
+            return result;
+        }
+
+        private static int CompareTypeFieldMetadata(TypeFieldMetadata left, TypeFieldMetadata right)
+        {
+            if (ReferenceEquals(left, right))
+            {
+                return 0;
+            }
+
+            if (left == null)
+            {
+                return -1;
+            }
+
+            if (right == null)
+            {
+                return 1;
+            }
+
+            int typeNameComparison = string.CompareOrdinal(left.typeName, right.typeName);
+            if (typeNameComparison != 0)
+            {
+                return typeNameComparison;
+            }
+
+            string[] leftFields = left.fieldNames ?? Array.Empty<string>();
+            string[] rightFields = right.fieldNames ?? Array.Empty<string>();
+
+            int lengthComparison = leftFields.Length.CompareTo(rightFields.Length);
+            if (lengthComparison != 0)
+            {
+                return lengthComparison;
+            }
+
+            for (int i = 0; i < leftFields.Length; i++)
+            {
+                int fieldComparison = string.CompareOrdinal(leftFields[i], rightFields[i]);
+                if (fieldComparison != 0)
+                {
+                    return fieldComparison;
+                }
+            }
+
+            return 0;
+        }
+
+        private static int CompareRelationalTypeMetadata(
+            RelationalTypeMetadata left,
+            RelationalTypeMetadata right
+        )
+        {
+            if (ReferenceEquals(left, right))
+            {
+                return 0;
+            }
+
+            if (left == null)
+            {
+                return -1;
+            }
+
+            if (right == null)
+            {
+                return 1;
+            }
+
+            int typeNameComparison = string.CompareOrdinal(left.typeName, right.typeName);
+            if (typeNameComparison != 0)
+            {
+                return typeNameComparison;
+            }
+
+            RelationalFieldMetadata[] leftFields =
+                left.fields ?? Array.Empty<RelationalFieldMetadata>();
+            RelationalFieldMetadata[] rightFields =
+                right.fields ?? Array.Empty<RelationalFieldMetadata>();
+
+            int lengthComparison = leftFields.Length.CompareTo(rightFields.Length);
+            if (lengthComparison != 0)
+            {
+                return lengthComparison;
+            }
+
+            for (int i = 0; i < leftFields.Length; i++)
+            {
+                int fieldComparison = CompareRelationalFieldMetadata(leftFields[i], rightFields[i]);
+                if (fieldComparison != 0)
+                {
+                    return fieldComparison;
+                }
+            }
+
+            return 0;
+        }
+
+        private static int CompareRelationalFieldMetadata(
+            RelationalFieldMetadata left,
+            RelationalFieldMetadata right
+        )
+        {
+            if (ReferenceEquals(left, right))
+            {
+                return 0;
+            }
+
+            if (left == null)
+            {
+                return -1;
+            }
+
+            if (right == null)
+            {
+                return 1;
+            }
+
+            int fieldNameComparison = string.CompareOrdinal(left.fieldName, right.fieldName);
+            if (fieldNameComparison != 0)
+            {
+                return fieldNameComparison;
+            }
+
+            int attributeComparison = left.attributeKind.CompareTo(right.attributeKind);
+            if (attributeComparison != 0)
+            {
+                return attributeComparison;
+            }
+
+            int fieldKindComparison = left.fieldKind.CompareTo(right.fieldKind);
+            if (fieldKindComparison != 0)
+            {
+                return fieldKindComparison;
+            }
+
+            int elementTypeComparison = string.CompareOrdinal(
+                left.elementTypeName,
+                right.elementTypeName
+            );
+            if (elementTypeComparison != 0)
+            {
+                return elementTypeComparison;
+            }
+
+            if (left.isInterface == right.isInterface)
+            {
+                return 0;
+            }
+
+            return left.isInterface ? -1 : 1;
+        }
 #endif
     }
 }

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>

package/Runtime/Tags/AttributesComponent.cs

@@ -121,6 +121,26 @@ namespace WallstopStudios.UnityHelpers.Tags
             IEnumerable<AttributeModification> attributeModifications
         )
         {
+            if (attributeModifications is IReadOnlyList<AttributeModification> readonlyList)
+            {
+                for (int i = 0; i < readonlyList.Count; ++i)
+                {
+                    AttributeModification modification = readonlyList[i];
+                    if (!TryGetAttribute(modification.attribute, out Attribute attribute))
+                    {
+                        continue;
+                    }
+
+                    float oldValue = attribute;
+                    attribute.ApplyAttributeModification(modification);
+                    float currentValue = attribute;
+
+                    OnAttributeModified?.Invoke(modification.attribute, oldValue, currentValue);
+                }
+
+                return;
+            }
+
             foreach (AttributeModification modification in attributeModifications)
             {
                 if (!TryGetAttribute(modification.attribute, out Attribute attribute))