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

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;