Only your worst debuff counts¶

// An explicit sink on the target wins. A project that implements IDamageTakenModifier has
// said where it wants incoming-damage scaling to live, and routing past it to Health would
// apply the debuff twice on any object that has both.
if (target.TryGetComponent<IDamageTakenModifier>(out var s))
{
    sink = s;
    sink.AddMultiplier(appliedMultiplier);
    return;
}

using System.Collections.Generic;

using RevGaming.RevFramework.Core.Abstractions.Combat;

using RevGaming.RevFramework.Health.Abstractions.Contracts;
using RevGaming.RevFramework.Health.Abstractions.Rules;
using RevGaming.RevFramework.Health.Rules.Builtins.Hubs;
using RevGaming.RevFramework.Health.Rules.Builtins.Ordering;

using UnityEngine;

namespace RevGaming.RevFramework.Cookbook.WorstDebuffWins
{
    /// <summary>
    /// Two curses that each make you take 50% more damage make you take 50% more damage, not 125%
    /// more — while a resistance still applies on top of whichever curse won.
    /// </summary>
    /// <remarks>
    /// <para><b>Recipe.</b> One class, dropped into a project that already exists. Systems required:
    /// <b>Health</b> only. Public API only. It goes on the actor being hit, on the same object as its
    /// health component and its <see cref="DamageRuleHub"/> — both halves are found from that one
    /// object, so a child will not do.</para>
    ///
    /// <para><b>It is the framework's first implementation of <see cref="IDamageTakenModifier"/>, and
    /// that interface is not decoration.</b> <c>VulnerabilityStatus.Apply</c> looks for one on its
    /// target <i>before</i> anything else and returns the moment it finds one, with the reason stated
    /// in its own source: a project that implements this has said where it wants incoming-damage
    /// scaling to live, and routing past it would apply the debuff twice. Nothing in Runtime,
    /// Integrations, Samples or Teaching implements it. So the seam is a standing invitation that has
    /// never been accepted.</para>
    ///
    /// <para><b>Two seams against one hit, and it needs both.</b> <see cref="IDamageTakenModifier"/>
    /// is where contributions <i>arrive</i>; it has no idea a hit is happening. <see cref="IDamageRule"/>
    /// is where a hit is <i>decided</i>; it is never told a debuff was applied. One class implements
    /// both, which is what lets it answer the only question that matters here — <i>how do these
    /// combine?</i> — instead of forwarding it.</para>
    ///
    /// <para><b>What it changes.</b> Health ships <c>DamageTakenMultiplierRule</c>, which multiplies
    /// every contribution together; three stacked 1.5x debuffs make a hit 3.375x. That is a defensible
    /// default and it is not the rule most games want. Here the amplifiers do not stack — only the
    /// largest counts — and everything at or below 1x still multiplies, so resistances, wards and
    /// difficulty scaling compose exactly as before. <b>The cap is the mechanic, so there is nothing
    /// left to clamp on the amplifier side.</b></para>
    ///
    /// <para><b>Status Effects is not required, and that is worth knowing before you wire it.</b>
    /// <see cref="AddMultiplier"/> and <see cref="RemoveMultiplier"/> are public, so a stance, a
    /// difficulty setting or a scripted encounter can push into this with no status system anywhere.
    /// Status Effects installed simply means <c>Vulnerability</c> finds it on its own.</para>
    ///
    /// <para><b>It does not clear itself when disabled, and the shipped rule does.</b>
    /// <see cref="DamageRuleHub.WillRun"/> already skips a rule whose component is unticked or whose
    /// object is inactive, so clearing buys no stand-down — it only throws away bookkeeping that
    /// something else still believes in. A status that pushed a contribution cannot know you unticked
    /// a box, so re-enabling with an emptied stack would silently drop live debuffs. Standing down and
    /// keeping the ledger is the honest behaviour; <see cref="Clear"/> is public for the one case that
    /// genuinely wants a wipe.</para>
    ///
    /// <para><b><see cref="Apply"/> writes nothing.</b> It is run by <c>PreviewDamage</c> as well as by
    /// the real hit, so a rule that advanced state here would make forecasting a hit change the hit.
    /// The combined factor is settled when a contribution arrives, which also means the hit path never
    /// walks the list.</para>
    /// </remarks>
    [DisallowMultipleComponent]
    [RequireComponent(typeof(DamageRuleHub))]
    public sealed class WorstDebuffWins : MonoBehaviour, IDamageTakenModifier, IDamageRule
    {
        [Tooltip("Damage is never scaled below this. Reducers multiply without limit, so this is the " +
                 "one direction the design leaves open. Matches the shipped rule's default.")]
        [SerializeField, Min(0.01f)] private float minFactor = 0.05f;

        [Tooltip("Damage is never scaled above this. Stacking cannot reach it on its own — only a " +
                 "single very large contribution can. Matches the shipped rule's default.")]
        [SerializeField, Min(0.01f)] private float maxFactor = 10f;

        // One entry per live contribution, in arrival order. A list rather than a running number
        // because RemoveMultiplier has to withdraw ONE matching entry: two effects pushing 1.5x are
        // separate contributions, and the first to expire must not take the second one with it.
        private readonly List<float> contributions = new(4);

        private float combined = 1f;

        /// <summary>
        /// Runs at the same point in the PRE chain as the rule it replaces.
        /// </summary>
        /// <remarks>
        /// After armour and affinity, before the safety clamp. Using the shipped constant rather than a
        /// number of its own means a project swapping one component for the other does not also move
        /// where victim-side scaling happens.
        /// </remarks>
        public int Priority => DamageRulePriority.DamageTakenMultiplier;

        /// <summary>
        /// How many live contributions this actor is carrying.
        /// </summary>
        /// <remarks>Read-only and side-effect free, so a debug overlay can show it every frame.</remarks>
        public int Count => contributions.Count;

        /// <summary>
        /// The multiplier the next hit will be scaled by, after combination and clamping.
        /// </summary>
        /// <remarks>
        /// <para>Zero means the next hit is cancelled outright rather than scaled to almost nothing —
        /// a contribution of zero is somebody saying <i>immune</i>, and clamping that up to
        /// <c>minFactor</c> would let five percent through.</para>
        /// <para>This is the readout the shipped rule has no equivalent of: a UI can say <i>you are
        /// taking 50% more damage</i> and name a number the pipeline will actually use.</para>
        /// </remarks>
        public float Factor
        {
            get
            {
                if (contributions.Count == 0) return 1f;
                if (combined == 0f) return 0f;

                float lower = Mathf.Max(0f, minFactor);
                float upper = Mathf.Max(lower, maxFactor);
                return Mathf.Clamp(combined, lower, upper);
            }
        }

        /// <summary>
        /// Records a contribution to how much damage this actor takes.
        /// </summary>
        /// <remarks>
        /// <para>Above 1 amplifies and competes with the other amplifiers; at or below 1 it reduces and
        /// multiplies with the other reducers. Negative values are treated as zero, which is what the
        /// shipped rule does and what a caller passing one almost certainly meant.</para>
        /// <para>Every call must be matched by exactly one <see cref="RemoveMultiplier"/> with the same
        /// value. An unmatched push leaves the actor permanently fragile — the framework's own source
        /// says so beside the code that pairs them.</para>
        /// </remarks>
        /// <param name="multiplier">The factor to contribute.</param>
        public void AddMultiplier(float multiplier)
        {
            contributions.Add(Mathf.Max(0f, multiplier));
            Recompute();
        }

        /// <summary>
        /// Withdraws one contribution matching <paramref name="multiplier"/>.
        /// </summary>
        /// <remarks>
        /// <para><b>One, not all.</b> Matching is by value because that is the only handle the interface
        /// gives — there is no ticket — so two effects contributing the same factor are
        /// interchangeable. Removing every match would hand back somebody else's debuff, which is the
        /// documented hazard on Health's own push/pop pair.</para>
        /// <para>The scan runs from the end so the most recent matching contribution goes first, which
        /// keeps the common apply-then-expire case in step and matches the shipped rule.</para>
        /// <para>An unmatched withdrawal changes nothing and says so in the Editor. It is not a
        /// recoverable condition — it means some caller's accounting is already wrong — and the
        /// diagnostic is editor-only because the <i>behaviour</i> is identical in a player. That is the
        /// distinction worth holding on to: gating a warning is fine, gating a decision is not.</para>
        /// </remarks>
        /// <param name="multiplier">The factor to withdraw. Matched approximately.</param>
        public void RemoveMultiplier(float multiplier)
        {
            float m = Mathf.Max(0f, multiplier);

            for (int i = contributions.Count - 1; i >= 0; i--)
            {
                if (!Mathf.Approximately(contributions[i], m)) continue;

                contributions.RemoveAt(i);
                Recompute();
                return;
            }

#if UNITY_EDITOR
            Debug.LogWarning(
                $"[WorstDebuffWins] Nothing to withdraw for {m}. Something removed a contribution it " +
                "never added, or added one and changed the value before removing it.", this);
#endif
        }

        /// <summary>
        /// Drops every contribution.
        /// </summary>
        /// <remarks>
        /// Public because the framework cannot know when your game considers the slate clean. Spawning
        /// a pooled actor is the case that needs it most: the component keeps its ledger across a
        /// disable, deliberately, so an actor put back in the pool while cursed comes out of it cursed.
        /// A revive is the other obvious caller.
        /// </remarks>
        public void Clear()
        {
            contributions.Clear();
            combined = 1f;
        }

        /// <summary>
        /// Scales the incoming hit by the combined factor.
        /// </summary>
        /// <remarks>
        /// <para>Reads only. The list is not walked here — the combination is settled when a
        /// contribution arrives — so a hit costs one comparison and one multiply however many debuffs
        /// are running.</para>
        /// <para>Carrying nothing returns without touching the context at all, rather than multiplying
        /// by a clamped 1. A component holding no contributions has no opinion about the hit, and a
        /// mis-set <see cref="minFactor"/> above 1 would otherwise let it amplify one.</para>
        /// </remarks>
        /// <param name="ctx">The mutable damage context.</param>
        /// <returns><see langword="false"/> only when a zero contribution cancels the hit.</returns>
        public bool Apply(ref DamageContext ctx)
        {
            if (ctx.Cancelled) return true;
            if (contributions.Count == 0) return true;

            if (combined == 0f)
            {
                ctx.Cancelled = true;
                return false;
            }

            float lower = Mathf.Max(0f, minFactor);
            float upper = Mathf.Max(lower, maxFactor);

            ctx.Multiplier *= Mathf.Clamp(combined, lower, upper);
            return true;
        }

        /// <summary>
        /// Settles the combined factor from the live contributions.
        /// </summary>
        /// <remarks>
        /// The whole recipe is these eight lines. Amplifiers compete and the largest wins; reducers
        /// multiply. An actor carrying nothing combines to 1, which is why a lone reducer of 1x and an
        /// empty ledger are the same answer.
        /// </remarks>
        private void Recompute()
        {
            float amplifier = 1f;
            float reducers = 1f;

            for (int i = 0; i < contributions.Count; i++)
            {
                float m = contributions[i];

                if (m > 1f)
                {
                    if (m > amplifier) amplifier = m;
                }
                else
                {
                    reducers *= m;
                }
            }

            combined = amplifier * reducers;
        }

#if UNITY_EDITOR
        private void OnValidate()
        {
            minFactor = Mathf.Max(0.01f, minFactor);
            maxFactor = Mathf.Max(minFactor, maxFactor);
        }
#endif
    }
}