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

package/Runtime/Tags/EffectHandler.cs

@@ -67,6 +67,9 @@ namespace WallstopStudios.UnityHelpers.Tags
             List<CosmeticEffectData>
         > _instancedCosmeticEffects = new();
 
+        private readonly Dictionary<EffectStackKey, List<EffectHandle>> _handlesByStackKey = new();
+        private readonly Dictionary<long, EffectStackKey> _stackKeyByHandleId = new();
+
         // Stores expiration time of duration effects (We store by Id because it's much cheaper to iterate Guids than it is EffectHandles
         private readonly Dictionary<long, float> _effectExpirations = new();
         private readonly Dictionary<long, EffectHandle> _effectHandlesById = new();
@@ -74,6 +77,9 @@ namespace WallstopStudios.UnityHelpers.Tags
         // Used only to save allocations in Update()
         private readonly List<long> _expiredEffectIds = new();
         private readonly List<EffectHandle> _appliedEffects = new();
+        private readonly Dictionary<long, List<PeriodicEffectRuntimeState>> _periodicEffectStates =
+            new();
+        private readonly Dictionary<long, List<EffectBehavior>> _behaviorsByHandleId = new();
 
         private bool _initialized;
 
@@ -118,51 +124,109 @@ namespace WallstopStudios.UnityHelpers.Tags
         /// </remarks>
         public EffectHandle? ApplyEffect(AttributeEffect effect)
         {
-            EffectHandle? maybeHandle = null;
+            if (effect == null)
+            {
+                return null;
+            }
 
-            if (effect.durationType != ModifierDurationType.Instant)
+            if (effect.durationType == ModifierDurationType.Instant)
             {
-                if (effect.durationType == ModifierDurationType.Duration)
+                if (RequiresHandle(effect))
+                {
+                    this.LogWarn(
+                        $"Effect {effect:json} defines periodic or behaviour data but is Instant. These features require a Duration or Infinite effect."
+                    );
+                }
+
+                InternalApplyEffect(effect);
+                return null;
+            }
+
+            EffectStackKey stackKey = effect.GetStackKey();
+            List<EffectHandle> existingHandles = TryGetStackHandles(stackKey);
+
+            switch (effect.stackingMode)
+            {
+                case EffectStackingMode.Ignore:
+                {
+                    if (existingHandles is { Count: > 0 })
+                    {
+                        return existingHandles[0];
+                    }
+
+                    break;
+                }
+                case EffectStackingMode.Refresh:
+                {
+                    if (existingHandles is { Count: > 0 })
+                    {
+                        EffectHandle handle = existingHandles[0];
+                        InternalApplyEffect(handle);
+                        return handle;
+                    }
+
+                    break;
+                }
+                case EffectStackingMode.Replace:
                 {
-                    foreach (EffectHandle appliedEffect in _appliedEffects)
+                    if (existingHandles is { Count: > 0 })
                     {
-                        if (appliedEffect.effect == null)
+                        using PooledResource<List<EffectHandle>> handleBufferResource =
+                            Buffers<EffectHandle>.List.Get(out List<EffectHandle> handleBuffer);
+                        handleBuffer.AddRange(existingHandles);
+                        for (int i = 0; i < handleBuffer.Count; ++i)
                         {
-                            continue;
+                            RemoveEffect(handleBuffer[i]);
                         }
+                    }
 
-                        string serializableName = appliedEffect.effect.name;
-                        if (string.Equals(effect.name, serializableName, StringComparison.Ordinal))
+                    break;
+                }
+                case EffectStackingMode.Stack:
+                {
+                    if (existingHandles is { Count: > 0 } && effect.maximumStacks > 0)
+                    {
+                        while (existingHandles.Count >= effect.maximumStacks)
                         {
-                            maybeHandle = appliedEffect;
-                            break;
+                            EffectHandle oldestHandle = existingHandles[0];
+                            RemoveEffect(oldestHandle);
                         }
                     }
-                }
-
-                maybeHandle ??= EffectHandle.CreateInstance(effect);
-            }
 
-            if (maybeHandle.HasValue)
-            {
-                EffectHandle handle = maybeHandle.Value;
-                InternalApplyEffect(handle);
-                if (
-                    effect.durationType == ModifierDurationType.Duration
-                    && (effect.resetDurationOnReapplication || !_appliedEffects.Contains(handle))
-                )
-                {
-                    long handleId = handle.id;
-                    _effectExpirations[handleId] = Time.time + effect.duration;
-                    _effectHandlesById[handleId] = handle;
+                    break;
                 }
             }
-            else
+
+            EffectHandle newHandle = EffectHandle.CreateInstance(effect);
+            RegisterStackHandle(stackKey, newHandle);
+            InternalApplyEffect(newHandle);
+            return newHandle;
+        }
+
+        private static bool RequiresHandle(AttributeEffect effect)
+        {
+            return (effect.periodicEffects is { Count: > 0 })
+                || (effect.behaviors is { Count: > 0 });
+        }
+
+        private List<EffectHandle> TryGetStackHandles(EffectStackKey stackKey)
+        {
+            _ = _handlesByStackKey.TryGetValue(stackKey, out List<EffectHandle> handles);
+            return handles;
+        }
+
+        private void RegisterStackHandle(EffectStackKey stackKey, EffectHandle handle)
+        {
+            long handleId = handle.id;
+            _stackKeyByHandleId[handleId] = stackKey;
+
+            if (!_handlesByStackKey.TryGetValue(stackKey, out List<EffectHandle> handles))
             {
-                InternalApplyEffect(effect);
+                handles = new List<EffectHandle>();
+                _handlesByStackKey.Add(stackKey, handles);
             }
 
-            return maybeHandle;
+            handles.Add(handle);
         }
 
         /// <summary>
@@ -173,17 +237,236 @@ namespace WallstopStudios.UnityHelpers.Tags
         {
             InternalRemoveEffect(handle);
             _ = _appliedEffects.Remove(handle);
+            DeregisterHandle(handle);
         }
 
         public void RemoveAllEffects()
         {
-            foreach (EffectHandle handle in _appliedEffects.ToArray())
+            using PooledResource<List<EffectHandle>> handleBufferResource =
+                Buffers<EffectHandle>.List.Get(out List<EffectHandle> handleBuffer);
+            handleBuffer.AddRange(_appliedEffects);
+            foreach (EffectHandle handle in handleBuffer)
             {
-                InternalRemoveEffect(handle);
+                RemoveEffect(handle);
             }
             _appliedEffects.Clear();
         }
 
+        private void DeregisterHandle(EffectHandle handle)
+        {
+            long handleId = handle.id;
+            if (_stackKeyByHandleId.TryGetValue(handleId, out EffectStackKey stackKey))
+            {
+                if (_handlesByStackKey.TryGetValue(stackKey, out List<EffectHandle> handles))
+                {
+                    handles.Remove(handle);
+                    if (handles.Count == 0)
+                    {
+                        _handlesByStackKey.Remove(stackKey);
+                    }
+                }
+
+                _stackKeyByHandleId.Remove(handleId);
+            }
+
+            _periodicEffectStates.Remove(handleId);
+
+            if (_behaviorsByHandleId.Remove(handleId, out List<EffectBehavior> behaviorInstances))
+            {
+                EffectBehaviorContext context = new(this, handle, 0f);
+                for (int i = 0; i < behaviorInstances.Count; ++i)
+                {
+                    EffectBehavior behavior = behaviorInstances[i];
+                    if (behavior == null)
+                    {
+                        continue;
+                    }
+
+                    behavior.OnRemove(context);
+                    Destroy(behavior);
+                }
+            }
+        }
+
+        /// <summary>
+        /// Determines whether the specified effect is currently active on this handler.
+        /// </summary>
+        /// <param name="effect">The effect to check.</param>
+        /// <returns><c>true</c> if at least one handle for the effect is active; otherwise, <c>false</c>.</returns>
+        public bool IsEffectActive(AttributeEffect effect)
+        {
+            if (effect == null)
+            {
+                return false;
+            }
+
+            for (int i = 0; i < _appliedEffects.Count; ++i)
+            {
+                EffectHandle handle = _appliedEffects[i];
+                if (handle.effect == effect)
+                {
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        /// <summary>
+        /// Gets the number of active handles for the specified effect.
+        /// </summary>
+        /// <param name="effect">The effect to count.</param>
+        /// <returns>The number of active handles associated with <paramref name="effect"/>.</returns>
+        public int GetEffectStackCount(AttributeEffect effect)
+        {
+            if (effect == null)
+            {
+                return 0;
+            }
+
+            int count = 0;
+            for (int i = 0; i < _appliedEffects.Count; ++i)
+            {
+                EffectHandle handle = _appliedEffects[i];
+                if (handle.effect == effect)
+                {
+                    ++count;
+                }
+            }
+
+            return count;
+        }
+
+        /// <summary>
+        /// Copies all active effect handles into the provided 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 currently active effect handles.</returns>
+        public List<EffectHandle> GetActiveEffects(List<EffectHandle> buffer = null)
+        {
+            buffer ??= new List<EffectHandle>();
+            buffer.Clear();
+            buffer.AddRange(_appliedEffects);
+            return buffer;
+        }
+
+        /// <summary>
+        /// Attempts to retrieve the remaining duration for the specified effect handle.
+        /// </summary>
+        /// <param name="handle">The handle to inspect.</param>
+        /// <param name="remainingDuration">When this method returns, contains the remaining time in seconds, or zero if unavailable.</param>
+        /// <returns><c>true</c> if the handle has a tracked duration; otherwise, <c>false</c>.</returns>
+        public bool TryGetRemainingDuration(EffectHandle handle, out float remainingDuration)
+        {
+            long handleId = handle.id;
+            if (!_effectExpirations.TryGetValue(handleId, out float expiration))
+            {
+                remainingDuration = 0f;
+                return false;
+            }
+
+            float timeRemaining = expiration - Time.time;
+            if (timeRemaining < 0f)
+            {
+                timeRemaining = 0f;
+            }
+
+            remainingDuration = timeRemaining;
+            return true;
+        }
+
+        /// <summary>
+        /// Ensures an effect handle exists for the specified effect, optionally refreshing its duration if already active.
+        /// </summary>
+        /// <param name="effect">The effect to apply or refresh.</param>
+        /// <returns>An active handle for the effect, or <c>null</c> for instant effects.</returns>
+        public EffectHandle? EnsureHandle(AttributeEffect effect)
+        {
+            return EnsureHandle(effect, refreshDuration: true);
+        }
+
+        /// <summary>
+        /// Ensures an effect handle exists for the specified effect, optionally refreshing its duration if already active.
+        /// </summary>
+        /// <param name="effect">The effect to apply or refresh.</param>
+        /// <param name="refreshDuration">
+        /// When <c>true</c>, attempts to refresh the effect's duration when it is already active and supports reapplication.
+        /// </param>
+        /// <returns>An active handle for the effect, or <c>null</c> for instant effects.</returns>
+        public EffectHandle? EnsureHandle(AttributeEffect effect, bool refreshDuration)
+        {
+            if (effect == null)
+            {
+                return null;
+            }
+
+            for (int i = 0; i < _appliedEffects.Count; ++i)
+            {
+                EffectHandle handle = _appliedEffects[i];
+                if (handle.effect == effect)
+                {
+                    if (refreshDuration)
+                    {
+                        _ = RefreshEffect(handle);
+                    }
+
+                    return handle;
+                }
+            }
+
+            return ApplyEffect(effect);
+        }
+
+        /// <summary>
+        /// Attempts to refresh the duration of the specified effect handle.
+        /// </summary>
+        /// <param name="handle">The handle to refresh.</param>
+        /// <returns><c>true</c> if the duration was refreshed; otherwise, <c>false</c>.</returns>
+        public bool RefreshEffect(EffectHandle handle)
+        {
+            return RefreshEffect(handle, ignoreReapplicationPolicy: false);
+        }
+
+        /// <summary>
+        /// Attempts to refresh the duration of the specified effect handle.
+        /// </summary>
+        /// <param name="handle">The handle to refresh.</param>
+        /// <param name="ignoreReapplicationPolicy">
+        /// When <c>true</c>, refreshes the duration even if <see cref="AttributeEffect.resetDurationOnReapplication"/> is <c>false</c>.
+        /// </param>
+        /// <returns><c>true</c> if the duration was refreshed; otherwise, <c>false</c>.</returns>
+        public bool RefreshEffect(EffectHandle handle, bool ignoreReapplicationPolicy)
+        {
+            AttributeEffect effect = handle.effect;
+            if (effect == null)
+            {
+                return false;
+            }
+
+            if (effect.durationType != ModifierDurationType.Duration)
+            {
+                return false;
+            }
+
+            if (!ignoreReapplicationPolicy && !effect.resetDurationOnReapplication)
+            {
+                return false;
+            }
+
+            long handleId = handle.id;
+            if (!_effectExpirations.ContainsKey(handleId))
+            {
+                return false;
+            }
+
+            float newExpiration = Time.time + effect.duration;
+            _effectExpirations[handleId] = newExpiration;
+            _effectHandlesById[handleId] = handle;
+            return true;
+        }
+
         private void InternalRemoveEffect(EffectHandle handle)
         {
             foreach (AttributesComponent attributesComponent in _attributes)
@@ -217,17 +500,24 @@ namespace WallstopStudios.UnityHelpers.Tags
                 _appliedEffects.Add(handle);
             }
 
+            long handleId = handle.id;
+            _effectHandlesById[handleId] = handle;
+
             AttributeEffect effect = handle.effect;
             if (effect.durationType == ModifierDurationType.Duration)
             {
-                if (effect.resetDurationOnReapplication || !exists)
+                if (!exists || effect.resetDurationOnReapplication)
                 {
-                    long handleId = handle.id;
                     _effectExpirations[handleId] = Time.time + effect.duration;
-                    _effectHandlesById[handleId] = handle;
                 }
             }
 
+            if (!exists)
+            {
+                RegisterPeriodicRuntime(handle);
+                RegisterBehaviors(handle);
+            }
+
             if (!_initialized && _tagHandler == null)
             {
                 this.AssignRelationalComponents();
@@ -256,6 +546,13 @@ namespace WallstopStudios.UnityHelpers.Tags
 
         private void InternalApplyEffect(AttributeEffect effect)
         {
+            if (effect.durationType == ModifierDurationType.Instant && RequiresHandle(effect))
+            {
+                this.LogWarn(
+                    $"Effect {effect:json} defines periodic or behaviour data but is Instant. These features require a Duration or Infinite effect."
+                );
+            }
+
             if (!_initialized && _tagHandler == null)
             {
                 this.AssignRelationalComponents();
@@ -280,6 +577,116 @@ namespace WallstopStudios.UnityHelpers.Tags
             }
         }
 
+        private void RegisterPeriodicRuntime(EffectHandle handle)
+        {
+            AttributeEffect effect = handle.effect;
+            if (effect.periodicEffects is not { Count: > 0 })
+            {
+                return;
+            }
+
+            List<PeriodicEffectRuntimeState> runtimeStates = null;
+            float startTime = Time.time;
+
+            foreach (PeriodicEffectDefinition definition in effect.periodicEffects)
+            {
+                if (definition == null)
+                {
+                    continue;
+                }
+
+                (runtimeStates ??= new List<PeriodicEffectRuntimeState>()).Add(
+                    new PeriodicEffectRuntimeState(definition, startTime)
+                );
+            }
+
+            if (runtimeStates is { Count: > 0 })
+            {
+                _periodicEffectStates[handle.id] = runtimeStates;
+            }
+        }
+
+        private void RegisterBehaviors(EffectHandle handle)
+        {
+            AttributeEffect effect = handle.effect;
+            if (effect.behaviors is not { Count: > 0 })
+            {
+                return;
+            }
+
+            List<EffectBehavior> instances = null;
+            foreach (EffectBehavior behavior in effect.behaviors)
+            {
+                if (behavior == null)
+                {
+                    continue;
+                }
+
+                EffectBehavior clone = Instantiate(behavior);
+                (instances ??= new List<EffectBehavior>()).Add(clone);
+            }
+
+            if (instances is not { Count: > 0 })
+            {
+                return;
+            }
+
+            EffectBehaviorContext context = new(this, handle, 0f);
+            for (int i = 0; i < instances.Count; ++i)
+            {
+                EffectBehavior instance = instances[i];
+                if (instance == null)
+                {
+                    continue;
+                }
+
+                instance.OnApply(context);
+            }
+
+            _behaviorsByHandleId[handle.id] = instances;
+        }
+
+        private void ApplyPeriodicTick(
+            EffectHandle handle,
+            PeriodicEffectRuntimeState runtimeState,
+            float currentTime,
+            float deltaTime
+        )
+        {
+            PeriodicEffectDefinition definition = runtimeState.definition;
+            if (_attributes is { Count: > 0 } && definition.modifications is { Count: > 0 })
+            {
+                foreach (AttributesComponent attributesComponent in _attributes)
+                {
+                    attributesComponent.ApplyAttributeModifications(definition.modifications, null);
+                }
+            }
+
+            if (
+                _behaviorsByHandleId.TryGetValue(handle.id, out List<EffectBehavior> behaviors)
+                && behaviors.Count > 0
+            )
+            {
+                EffectBehaviorContext context = new(this, handle, deltaTime);
+                PeriodicEffectTickContext tickContext = new(
+                    definition,
+                    runtimeState.ExecutedTicks,
+                    currentTime
+                );
+
+                for (int i = 0; i < behaviors.Count; ++i)
+                {
+                    EffectBehavior behavior = behaviors[i];
+                    if (behavior == null)
+                    {
+                        continue;
+                    }
+
+                    behavior.OnPeriodicTick(context, tickContext);
+                }
+            }
+        }
+
         private void InternalApplyCosmeticEffects(EffectHandle handle)
         {
             if (_instancedCosmeticEffects.ContainsKey(handle))
@@ -332,8 +739,7 @@ namespace WallstopStudios.UnityHelpers.Tags
         {
             foreach (CosmeticEffectData cosmeticEffectData in attributeEffect.cosmeticEffects)
             {
-                CosmeticEffectData cosmeticEffect = cosmeticEffectData;
-                if (cosmeticEffect == null)
+                if (cosmeticEffectData == null)
                 {
                     this.LogError(
                         $"CosmeticEffectData is null for effect {attributeEffect:json}, cannot determine instancing scheme."
@@ -353,7 +759,7 @@ namespace WallstopStudios.UnityHelpers.Tags
                     Buffers<CosmeticEffectComponent>.List.Get();
                 List<CosmeticEffectComponent> cosmeticEffectsBuffer =
                     cosmeticEffectsResource.resource;
-                cosmeticEffect.GetComponents(cosmeticEffectsBuffer);
+                cosmeticEffectData.GetComponents(cosmeticEffectsBuffer);
                 foreach (CosmeticEffectComponent cosmeticComponent in cosmeticEffectsBuffer)
                 {
                     cosmeticComponent.OnApplyEffect(gameObject);
@@ -442,6 +848,13 @@ namespace WallstopStudios.UnityHelpers.Tags
         }
 
         private void Update()
+        {
+            ProcessEffectExpirations();
+            ProcessBehaviorTicks();
+            ProcessPeriodicEffects();
+        }
+
+        private void ProcessEffectExpirations()
         {
             if (_effectExpirations.Count <= 0)
             {
@@ -452,19 +865,131 @@ namespace WallstopStudios.UnityHelpers.Tags
             float currentTime = Time.time;
             foreach (KeyValuePair<long, float> entry in _effectExpirations)
             {
-                if (entry.Value < currentTime)
+                if (entry.Value <= currentTime)
                 {
                     _expiredEffectIds.Add(entry.Key);
                 }
             }
 
-            foreach (long expiredHandleId in _expiredEffectIds)
+            for (int i = 0; i < _expiredEffectIds.Count; ++i)
             {
+                long expiredHandleId = _expiredEffectIds[i];
                 if (_effectHandlesById.TryGetValue(expiredHandleId, out EffectHandle expiredHandle))
                 {
                     RemoveEffect(expiredHandle);
                 }
             }
+
+            _expiredEffectIds.Clear();
+        }
+
+        private void ProcessBehaviorTicks()
+        {
+            if (_behaviorsByHandleId.Count <= 0)
+            {
+                return;
+            }
+
+            using PooledResource<List<long>> behaviorHandleIdsResource = Buffers<long>.List.Get(
+                out List<long> behaviorHandleIdsBuffer
+            );
+            behaviorHandleIdsBuffer.AddRange(_behaviorsByHandleId.Keys);
+            float deltaTime = Time.deltaTime;
+
+            for (int i = 0; i < behaviorHandleIdsBuffer.Count; ++i)
+            {
+                long handleId = behaviorHandleIdsBuffer[i];
+                if (!_effectHandlesById.TryGetValue(handleId, out EffectHandle handle))
+                {
+                    continue;
+                }
+
+                if (!_behaviorsByHandleId.TryGetValue(handleId, out List<EffectBehavior> behaviors))
+                {
+                    continue;
+                }
+
+                EffectBehaviorContext context = new(this, handle, deltaTime);
+                for (int j = 0; j < behaviors.Count; ++j)
+                {
+                    EffectBehavior behavior = behaviors[j];
+                    if (behavior == null)
+                    {
+                        continue;
+                    }
+
+                    behavior.OnTick(context);
+                }
+            }
+        }
+
+        private void ProcessPeriodicEffects()
+        {
+            if (_periodicEffectStates.Count <= 0)
+            {
+                return;
+            }
+
+            float currentTime = Time.time;
+            float deltaTime = Time.deltaTime;
+            using PooledResource<List<long>> periodicRemovalResource = Buffers<long>.List.Get(
+                out List<long> periodicRemovalBuffer
+            );
+            using PooledResource<List<long>> periodHandleIdsResource = Buffers<long>.List.Get(
+                out List<long> periodicHandleIdsBuffer
+            );
+            periodicHandleIdsBuffer.AddRange(_periodicEffectStates.Keys);
+
+            for (int handleIndex = 0; handleIndex < periodicHandleIdsBuffer.Count; ++handleIndex)
+            {
+                long handleId = periodicHandleIdsBuffer[handleIndex];
+                if (!_effectHandlesById.TryGetValue(handleId, out EffectHandle handle))
+                {
+                    periodicRemovalBuffer.Add(handleId);
+                    continue;
+                }
+
+                if (
+                    !_periodicEffectStates.TryGetValue(
+                        handleId,
+                        out List<PeriodicEffectRuntimeState> runtimes
+                    )
+                )
+                {
+                    continue;
+                }
+
+                bool hasActive = false;
+
+                for (int i = 0; i < runtimes.Count; ++i)
+                {
+                    PeriodicEffectRuntimeState runtimeState = runtimes[i];
+                    if (runtimeState == null)
+                    {
+                        continue;
+                    }
+
+                    while (runtimeState.TryConsumeTick(currentTime))
+                    {
+                        ApplyPeriodicTick(handle, runtimeState, currentTime, deltaTime);
+                    }
+
+                    if (!runtimeState.IsComplete)
+                    {
+                        hasActive = true;
+                    }
+                }
+
+                if (!hasActive)
+                {
+                    periodicRemovalBuffer.Add(handleId);
+                }
+            }
+
+            for (int i = 0; i < periodicRemovalBuffer.Count; ++i)
+            {
+                _periodicEffectStates.Remove(periodicRemovalBuffer[i]);
+            }
         }
     }
 }