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

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/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))

package/Runtime/Tags/EffectBehavior.cs

@@ -0,0 +1,171 @@
+namespace WallstopStudios.UnityHelpers.Tags
+{
+    using UnityEngine;
+
+    /// <summary>
+    /// Base class for authoring custom effect behaviours that respond to the lifecycle of an active <see cref="AttributeEffect"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Each behaviour asset is cloned per <see cref="EffectHandle"/>, which means derived classes can safely store mutable state
+    /// between calls to <see cref="OnApply(EffectBehaviorContext)"/>, <see cref="OnTick(EffectBehaviorContext)"/>,
+    /// <see cref="OnPeriodicTick(EffectBehaviorContext, PeriodicEffectTickContext)"/>, and <see cref="OnRemove(EffectBehaviorContext)"/>.
+    /// </para>
+    /// <para>
+    /// Attach behaviour assets to <see cref="AttributeEffect.behaviors"/> to augment the data-driven attribute pipeline with bespoke
+    /// gameplay logic, visual or audio feedback, or integration hooks into other game systems.
+    /// </para>
+    /// <para>
+    /// All callbacks are synchronously invoked by <see cref="EffectHandler"/> on the main thread, ensuring safe interaction with Unity APIs.
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// <code language="csharp">
+    /// using UnityEngine;
+    /// using WallstopStudios.UnityHelpers.Tags;
+    ///
+    /// [CreateAssetMenu(menuName = "Game/Effects/Burning Behaviour")]
+    /// public sealed class BurningBehavior : EffectBehavior
+    /// {
+    ///     [SerializeField]
+    ///     private GameObject flamePrefab;
+    ///
+    ///     private GameObject spawnedInstance;
+    ///
+    ///     public override void OnApply(EffectBehaviorContext context)
+    ///     {
+    ///         if (flamePrefab == null)
+    ///         {
+    ///             return;
+    ///         }
+    ///
+    ///         Transform parent = context.Target.transform;
+    ///         spawnedInstance = Object.Instantiate(flamePrefab, parent.position, parent.rotation, parent);
+    ///     }
+    ///
+    ///     public override void OnPeriodicTick(EffectBehaviorContext context, PeriodicEffectTickContext tickContext)
+    ///     {
+    ///         // Cancel the effect early once the periodic bundle has executed three times.
+    ///         if (tickContext.executedTicks >= 3)
+    ///         {
+    ///             context.handler.RemoveEffect(context.handle);
+    ///         }
+    ///     }
+    ///
+    ///     public override void OnRemove(EffectBehaviorContext context)
+    ///     {
+    ///         if (spawnedInstance != null)
+    ///         {
+    ///             Object.Destroy(spawnedInstance);
+    ///             spawnedInstance = null;
+    ///         }
+    ///     }
+    /// }
+    ///
+    /// // Assign the behaviour asset to an AttributeEffect so it is cloned per application.
+    /// AttributeEffect burnEffect = ScriptableObject.CreateInstance&lt;AttributeEffect&gt;();
+    /// burnEffect.behaviors.Add(burningBehaviorAsset);
+    /// </code>
+    /// </example>
+    public abstract class EffectBehavior : ScriptableObject
+    {
+        /// <summary>
+        /// Invoked once when the effect handle becomes active.
+        /// </summary>
+        /// <param name="context">Runtime context for the effect instance.</param>
+        public virtual void OnApply(EffectBehaviorContext context) { }
+
+        /// <summary>
+        /// Invoked every frame while the effect remains active.
+        /// </summary>
+        /// <param name="context">Runtime context for the effect instance.</param>
+        public virtual void OnTick(EffectBehaviorContext context) { }
+
+        /// <summary>
+        /// Invoked after a periodic tick has been processed for the owning effect.
+        /// </summary>
+        /// <param name="context">Runtime context for the effect instance.</param>
+        /// <param name="tickContext">Information about the specific periodic tick.</param>
+        public virtual void OnPeriodicTick(
+            EffectBehaviorContext context,
+            PeriodicEffectTickContext tickContext
+        ) { }
+
+        /// <summary>
+        /// Invoked when the effect handle is removed or expires.
+        /// </summary>
+        /// <param name="context">Runtime context for the effect instance.</param>
+        public virtual void OnRemove(EffectBehaviorContext context) { }
+    }
+
+    /// <summary>
+    /// Immutable runtime data passed to behaviour callbacks.
+    /// </summary>
+    public readonly struct EffectBehaviorContext
+    {
+        /// <summary>
+        /// Gets the effect asset backing the handle.
+        /// </summary>
+        public AttributeEffect Effect => handle.effect;
+
+        /// <summary>
+        /// Gets the GameObject targeted by the effect handler.
+        /// </summary>
+        public GameObject Target => handler.gameObject;
+
+        /// <summary>
+        /// Gets the deltaTime used for the current invocation. For <see cref="EffectBehavior.OnApply"/>,
+        /// this value is zero.
+        /// </summary>
+        public readonly float deltaTime;
+
+        /// <summary>
+        /// Gets the handler managing the effect.
+        /// </summary>
+        public readonly EffectHandler handler;
+
+        /// <summary>
+        /// Gets the handle associated with this behaviour invocation.
+        /// </summary>
+        public readonly EffectHandle handle;
+
+        public EffectBehaviorContext(EffectHandler handler, EffectHandle handle, float deltaTime)
+        {
+            this.handler = handler;
+            this.handle = handle;
+            this.deltaTime = deltaTime;
+        }
+    }
+
+    /// <summary>
+    /// Details about a specific periodic tick that just executed.
+    /// </summary>
+    public readonly struct PeriodicEffectTickContext
+    {
+        /// <summary>
+        /// Gets the periodic definition that produced this tick.
+        /// </summary>
+        public readonly PeriodicEffectDefinition definition;
+
+        /// <summary>
+        /// Gets the number of ticks executed so far, including this one.
+        /// </summary>
+        public readonly int executedTicks;
+
+        /// <summary>
+        /// Gets the timestamp when the tick occurred.
+        /// </summary>
+        public readonly float currentTime;
+
+        public PeriodicEffectTickContext(
+            PeriodicEffectDefinition definition,
+            int executedTicks,
+            float currentTime
+        )
+        {
+            this.definition = definition;
+            this.executedTicks = executedTicks;
+            this.currentTime = currentTime;
+        }
+    }
+}

package/Runtime/Tags/EffectBehavior.cs.meta

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

package/Runtime/Tags/EffectHandle.cs

@@ -72,6 +72,11 @@ namespace WallstopStudios.UnityHelpers.Tags
             return new EffectHandle(Interlocked.Increment(ref Id), effect);
         }
 
+        internal static EffectHandle CreateInstanceInternal()
+        {
+            return new EffectHandle(Interlocked.Increment(ref Id), null);
+        }
+
         private EffectHandle(long id, AttributeEffect effect)
         {
             this.id = id;