⚙️ Health — Rules

📦 Folder Overview

This folder is the entry point for the Health rule system.

Rules define how damage and healing behave between incoming data (DamageContext / HealContext) and the core HealthSystem.

They are the primary extension surface for combat math, modifiers, and reactive behaviour.

---

🎯 Purpose

Rules provide:

• A composable pipeline for damage and healing
• External behaviour injection without modifying core systems
• Separation between data (contracts) and behaviour (rules)

---

🧩 What Lives Here

Priority Definitions

• DamageRulePriority.cs
• HealRulePriority.cs

Defines canonical ordering constants used by all rule families.

Use these to keep ordering consistent and debuggable.

---

🧩 Components

Pipeline Overview (Damage)

1. Guards

2. authority (optional)

3. dead target
4. invincibility

5. damage locks

6. PRE rules (DamageRuleHub) [ascending Priority]

7. mutate DamageContext (RawAmount, Multiplier, FlatDelta, Cancelled, BypassRules)

8. Fold damage

9. RawAmount * Multiplier + FlatDelta

10. Shields (optional)

11. IShield.TryAbsorb(ref damage) unless bypassed

12. Apply to HP

13. Current -= applied

14. POST observers (DamageRuleHub.NotifyPost)

15. IPostDamageRule observe finalized context (FinalApplied)

16. Execution for rejected attempts is implementation-defined

17. Death pipeline (if HP ≤ 0)

18. IBeforeDeathHandler[]

19. IHealthDeathHandler
20. Events

POST observers run after evaluation completes and should be treated as observer hooks.

---

Pipeline Overview (Heal)

1. Guards

2. authority (optional)

3. dead target

4. invalid amount

5. PRE heal rules (HealRuleHub) [ascending Priority]

6. mutate HealContext (RawAmount, Multiplier, FlatDelta, Cancelled)

7. Fold heal

8. RawAmount * Multiplier + FlatDelta

9. Healing modifiers (IHealingModifier)

10. Apply to HP

11. Current += applied (clamped)

12. POST observers (HealRuleHub.NotifyPost)

13. IPostHealRule observe finalized context (FinalApplied)

14. Execution for rejected attempts is implementation-defined

---

⚠️ Important Notes

Priority System

• Lower values run first
• Higher values run later
• POST observers run after evaluation

Use constants from:

• DamageRulePriority
• HealRulePriority

Avoid hardcoding numbers.

---

Boundaries

Rules should not:

• Mutate HP directly
• Rely on implicit ordering
• Encode networking or authority logic
• Treat helpers as guaranteed behaviour

Rules operate on context and act as extensions, not owners.

---

🧠 Usage Guidance

Quick Start

1. Add DamageRuleHub and/or HealRuleHub to the same GameObject as HealthSystem
2. Add rule components (PRE and/or POST)
3. Use ordering constants
4. Add shields if needed (run after PRE rules)

No rules are required by default.

---

Authoring Examples

Damage PRE rule

public sealed class MyRule : MonoBehaviour, IDamageRule
{
    public int Priority => DamageRulePriority.Armor + 10;

    public bool Apply(ref DamageContext ctx)
    {
        return true;
    }
}

Damage POST observer

public sealed class MyObserver : MonoBehaviour, IPostDamageRule
{
    public void OnDamageApplied(in DamageContext ctx)
    {
        if (ctx.FinalApplied <= 0) return;
    }
}

Heal PRE rule

public sealed class MyHealGate : MonoBehaviour, IHealRule
{
    public int Priority => HealRulePriority.AntiHeal + 10;

    public bool Apply(ref HealContext ctx)
    {
        return true;
    }
}

---

🔗 Related Documentation

• Rules Abstractions
• Damage Rules
• Heal Rules
• Rule Hubs
• Modifiers
• Authority