Last stand¶

using System;

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

using UnityEngine;

namespace RevGaming.RevFramework.Cookbook.LastStand
{
    /// <summary>
    /// Survive one otherwise-lethal hit, leaving a sliver of health, then go on cooldown — but only
    /// spend the save when the hit really would have killed you. A shield absorbs after this rule
    /// runs, so the owner can end above <c>survivingHealth</c> — never below it.
    /// </summary>
    /// <remarks>
    /// <para><b>Recipe.</b> One class, dropped into a project that already exists. Systems required:
    /// <b>Health</b> only. Public API only.</para>
    ///
    /// <para><b>The composition is the point: decide in PRE, commit in POST.</b> A rule that both
    /// changes a hit and spends a resource cannot do both in <see cref="IDamageRule.Apply"/>, because
    /// at that moment nothing has happened yet. Rules after this one may reduce the damage further,
    /// shields absorb after the PRE stage finishes, and the whole hit may still be cancelled — so a
    /// charge spent in PRE is a charge spent on a hit that might never land. This rule therefore
    /// adjusts the damage in PRE, remembers what it did, and decides in
    /// <see cref="IPostDamageRule.OnDamageApplied"/> — where <see cref="DamageContext.FinalApplied"/>
    /// says what actually happened — whether the save was needed at all. Worth knowing what that
    /// second stage is really for: when nothing sits between the rules and health, the POST test is
    /// the PRE test again and cannot decline. It earns its place on the cases where something did
    /// come between them — a cancel, a shield the estimate below could not see, or a rule of your
    /// own that cut the number further.</para>
    ///
    /// <para><b>Lethality has to be measured against what reaches health.</b> A shield in front of
    /// health absorbs after the PRE stage, so a test made on <see cref="IHealthReadonly.Current"/>
    /// alone spends the charge on hits the shield would have swallowed by itself. The estimate
    /// therefore asks the shield what would be left, through
    /// <see cref="IShieldPreview.PreviewRemainder"/> — but it can only find one that is a component
    /// on the victim: the framework resolves the real shield through an internal seam, so a shield
    /// handed to <c>HealthSystem.SetShield</c>, one on a child object, or one behind a disabled
    /// component stays invisible. What the estimate cannot see, POST still sees in the landed
    /// damage.</para>
    ///
    /// <para><b>Preview is the trap, and it is a documented one.</b>
    /// <c>PreviewDamage</c> runs the live rule components, which is exactly what makes a preview agree
    /// with the hit it predicts. So the arithmetic below must still run for a preview — otherwise the
    /// HUD would promise a killing blow this rule is about to survive — while every piece of
    /// <i>state</i> must be left alone, including the armed record: a HUD that previews inside a real
    /// hit would otherwise throw that hit's pending save away. The shipped <c>CritRule</c> had this
    /// bug with its random draw; <see cref="DamageContext.IsPreview"/> exists because of it.</para>
    ///
    /// <para><b>PRE and POST are not a guaranteed pair.</b> <see cref="IPostDamageRule"/> states that
    /// invocation for early-rejected attempts is implementation-defined, so a PRE that armed something
    /// may never see its POST. Anything held across the two stages therefore has to be safe when the
    /// second half never runs — here the armed record is cleared at the head of every real PRE and
    /// again the moment POST looks at it, so an abandoned arm cannot be picked up by a later hit. The
    /// hit that abandoned it keeps its reduction and never spends the charge: disable this component
    /// or deactivate the object between the two stages — a stagger handler reacting to
    /// <c>Damaged</c> will do it — and the owner gets that one save for free. That is the safe
    /// direction to be wrong in, and cheaper than the machinery that would close it.</para>
    ///
    /// <para><b>Ordering.</b> This runs at <see cref="DamageRulePriority.Clamp"/> + 1: after the
    /// general clamp, so the estimate already reflects any configured cap and nothing else reshapes
    /// the number afterwards. Priority orders PRE rules and nothing else — the shipped reflect and
    /// lifesteal components do their work in POST, where the hub runs observers in component order,
    /// so this value does not order this rule against them. It does not need to: they read
    /// <see cref="DamageContext.FinalApplied"/>, which is fixed before any POST observer runs, so
    /// they see the damage that was actually survived either way.</para>
    ///
    /// <para><b>Why a rule rather than the death seam.</b> The framework already ships a
    /// one-component version of this: <c>ExtraLifeTotemHandler</c> implements
    /// <c>IBeforeDeathHandler</c>, intercepts the death pipeline and revives the target — and it
    /// catches routes a damage rule cannot see, such as a direct health write, or <c>Kill()</c> once
    /// its <c>ignoreKillCommands</c> is turned off. Reach for that when what you want is "do not
    /// die". This recipe reshapes the hit instead, so the damage number the player reads, reflect,
    /// lifesteal and the death flow all agree that the blow was survived, and the death pipeline is
    /// never entered at all.</para>
    ///
    /// <para><b>The cooldown lives in memory only.</b> A save/load, a scene reload or a pooled
    /// respawn hands back a fresh component with the charge available; persist <c>_readyAt</c>
    /// yourself if that matters to your game.</para>
    /// </remarks>
    [DisallowMultipleComponent]
    [RequireComponent(typeof(DamageRuleHub))]
    public sealed class LastStandRule : MonoBehaviour, IDamageRule, IPostDamageRule
    {
        [Tooltip("Health left when a lethal hit is survived. 1 is the classic 'one hit point left'. " +
                 "A shield absorbing part of the reduced hit leaves the owner higher than this.")]
        [SerializeField, Min(1)] private int survivingHealth = 1;

        [Tooltip("Seconds before this can save the owner again. 0 means every lethal hit is survived.")]
        [SerializeField, Min(0f)] private float cooldownSeconds = 60f;

        [Tooltip("Unscaled time ignores Time.timeScale, so a slow-motion death sequence does not " +
                 "stretch the cooldown with it. Choose it before play: switching while a cooldown " +
                 "is running compares a stamp taken from one clock against the other.")]
        [SerializeField] private bool useUnscaledTime = true;

        private bool _armed;
        private long _armedReduction;
        private int _armedHealthBefore;
        private float _readyAt;

        /// <summary>Raised when a lethal hit was survived, with the health left behind.</summary>
        public event Action<int> Survived;

        /// <summary>
        /// Whether the cooldown has elapsed. Not a promise of survival: a hit is only survived while
        /// current health is above <c>survivingHealth</c>.
        /// </summary>
        public bool IsReady => Now >= _readyAt;

        /// <summary>Seconds until this can save the owner again. Zero when it is ready.</summary>
        public float CooldownRemaining => Mathf.Max(0f, _readyAt - Now);

        /// <inheritdoc />
        public int Priority => DamageRulePriority.Clamp + 1;

        private float Now => useUnscaledTime ? Time.unscaledTime : Time.time;

        /// <summary>
        /// Reduces a lethal hit to a survivable one, without yet deciding that the save was spent.
        /// </summary>
        public bool Apply(ref DamageContext ctx)
        {
            // Cleared on every real evaluation, so an armed record left behind by a PRE whose POST
            // never ran cannot be picked up by a later hit. A preview must not clear it: previews run
            // the live rule components, so a HUD refreshing inside a real hit would otherwise discard
            // that hit's pending save.
            if (!ctx.IsPreview)
                _armed = false;

            if (ctx.Cancelled || !IsReady)
                return true;

            if (!ctx.Victim || !ctx.Victim.TryGetComponent<IHealthReadonly>(out var health))
                return true;

            int current = health.Current;
            if (current <= survivingHealth)
                return true;

            long estimate = Estimate(in ctx);
            if (RemainderAfterShields(in ctx, estimate) < current)
                return true;

            // Reduced to what health can survive, not to what the shield would pass through. A
            // shield's absorption is proportional in the general case, so crediting it twice --
            // once in the test above and again here -- would over-reduce the reduction itself and
            // could leave the hit lethal after all. Under-reducing is the safe direction: whatever
            // the shield takes off afterwards can only leave the owner higher.
            long reduction = estimate - (current - survivingHealth);

            // Expressed through FlatDelta rather than by overwriting Multiplier or RawAmount, so the
            // adjustment composes with whatever the earlier rules decided instead of erasing it. This
            // is the same convention the shipped clamp rule follows -- including computing in long
            // and bounding only on the write-back, because FlatDelta is the int that has to hold it.
            int flatBefore = ctx.FlatDelta;
            ctx.FlatDelta = (int)Math.Clamp(flatBefore - reduction, int.MinValue, int.MaxValue);

            // Preview must see the reduced number -- that is what makes a preview agree with the hit
            // it predicts -- but must arm nothing, because nothing is going to be committed.
            if (!ctx.IsPreview)
            {
                _armed = true;

                // What was actually taken off, which is what POST has to reason about: the clamp
                // above can hold back part of an extreme reduction, and a reduction POST believes in
                // but the hit never received would spend the charge on a save that did not happen.
                _armedReduction = flatBefore - (long)ctx.FlatDelta;
                _armedHealthBefore = current;
            }

            return true;
        }

        /// <summary>
        /// Spends the save, but only if the hit that landed really would have been lethal without it.
        /// </summary>
        public void OnDamageApplied(in DamageContext ctx)
        {
            if (ctx.IsPreview || !_armed)
                return;

            // Cleared before the work, not after: whatever this decides, this armed record is spent.
            _armed = false;

            if (ctx.Cancelled)
                return;

            // Nothing reached health, so there is nothing to call a survival -- something stopped
            // the hit outright, either a shield this rule could not see or one whose remaining
            // capacity happened to swallow the reduced number. The first case would spend the charge
            // on an owner the shield had already saved; the second gives away a save that was real.
            // POST cannot tell them apart, so it keeps the charge: a free save is a better failure
            // than a "you survived" flash over an owner nothing touched.
            if (ctx.FinalApplied <= 0)
                return;

            // And nothing to celebrate over a corpse. This rule's reduction cannot itself be what
            // killed the owner, but something else in the same hit can, and the event says a lethal
            // hit was survived.
            if (!ctx.Victim || !ctx.Victim.TryGetComponent<IHealthReadonly>(out var health) ||
                health.Current <= 0)
                return;

            // The question is not "did we change the number" but "did that change matter". Shields
            // absorb after the PRE stage, and a later rule may have cut the damage on its own, so a
            // hit this rule adjusted can still turn out to have been survivable anyway. Only the
            // arithmetic on what actually landed can tell the difference.
            long withoutSave = (long)ctx.FinalApplied + _armedReduction;
            if (withoutSave < _armedHealthBefore)
                return;

            _readyAt = Now + cooldownSeconds;

            int healthLeft = _armedHealthBefore - ctx.FinalApplied;

            // A listener that throws inside the damage pipeline would otherwise take the rest of the
            // hit down with it -- including any rule that has not been notified yet.
            try
            {
                Survived?.Invoke(healthLeft);
            }
            catch (Exception e)
            {
                Debug.LogException(e, this);
            }
        }

        /// <summary>
        /// The damage this hit is currently worth, in the pipeline's own terms.
        /// </summary>
        /// <remarks>
        /// Reimplemented rather than called: the framework's own helper for this is internal, so any
        /// rule outside the assembly has to restate the formula. Keep <see cref="Mathf.RoundToInt"/> —
        /// it rounds halves to even, and swapping in a cast or <c>Math.Round</c>'s default would put
        /// this rule one point out from the pipeline on exactly the hits that decide life or death.
        /// The result is a <see cref="long"/> for the same reason the framework's helper returns one:
        /// the sum genuinely can leave <see cref="int"/> range, and bounding it here would shrink the
        /// reduction by exactly the excess that overflowed — enough to kill the owner this rule had
        /// already decided to save.
        /// </remarks>
        private static long Estimate(in DamageContext ctx)
        {
            float scaled = ctx.RawAmount * Mathf.Max(0f, ctx.Multiplier);

            if (float.IsNaN(scaled))
                return ctx.FlatDelta;

            long rounded = scaled >= int.MaxValue ? int.MaxValue
                : scaled <= int.MinValue ? int.MinValue
                : Mathf.RoundToInt(scaled);

            return rounded + ctx.FlatDelta;
        }

        /// <summary>
        /// What that estimate would leave for health once the victim's shield has taken its share.
        /// </summary>
        /// <remarks>
        /// Only a shield that is a component on the victim can be found, and only while it is active:
        /// the resolved shield itself is reachable only through an internal seam. When none is found
        /// the full estimate is returned, which is the safe way to be wrong — it can cost a charge
        /// that was not needed, never a life. The other way round is possible but takes an odd
        /// setup: point the health component's shield field at a shield somewhere else while
        /// leaving one on the victim, and the component found here is not the one that will absorb.
        /// Crediting it can then talk this rule out of a save — the owner is no worse off than with
        /// no rule attached, but the charge stays showing on the HUD. Keep the shield the health
        /// component actually uses on the victim.
        /// </remarks>
        private static long RemainderAfterShields(in DamageContext ctx, long estimate)
        {
            if (ctx.BypassShields || estimate <= 0)
                return estimate;

            if (!ctx.Victim.TryGetComponent<IShieldPreview>(out var shield))
                return estimate;

            if (shield is Behaviour b && !b.isActiveAndEnabled)
                return estimate;

            // PreviewRemainder deals in int, so an estimate above int range is offered the largest
            // value it can express. What comes back is still absorption this hit would suffer, and
            // clamping it keeps a third-party shield from reporting a remainder larger than the hit.
            int probe = (int)Math.Min(estimate, int.MaxValue);
            return estimate - (probe - Mathf.Clamp(shield.PreviewRemainder(probe), 0, probe));
        }
    }
}