❤️ Health System — Damage Pipeline Diagram

This page visually summarizes the RevFramework Health damage pipeline.

It complements the Mental Model by showing exact execution order and where extension points plug in.

---

⚔ Damage Pipeline (Visual)

┌──────────────────────────────┐
│        Damage Attempt        │
│   DamageContext constructed  │
└───────────────┬──────────────┘
                │
                ▼
┌──────────────────────────────────────────────┐
│            Mutation Guards                   │
│ Authority / Dead / Invincibility / Lock     │
│        (may block mutation early)           │
└───────────────┬──────────────────────────────┘
                │
                ▼
┌──────────────────────────────┐
│    Context Normalization     │
│ clamp values / set defaults  │
└───────────────┬──────────────┘
                │
                ▼
┌──────────────────────────────┐
│         PRE Rules            │
│          IDamageRule         │
│  - modify math               │
│  - cancel attempt            │
│  - scale damage              │
└───────────────┬──────────────┘
                │
                ▼
┌──────────────────────────────┐
│      Evaluate Damage Math    │
│ (RawAmount * Multiplier)     │
│        + FlatDelta           │
│ (clamped and rounded)        │
└───────────────┬──────────────┘
                │
                ▼
┌──────────────────────────────┐
│           Shields            │
│            IShield           │
│  - absorb damage             │
│  - reduce damage             │
│  - skipped if BypassShields  │
└───────────────┬──────────────┘
                │
                ▼
┌──────────────────────────────┐
│         HP Mutation          │
│    HealthSystem updates HP   │
│     Current -= FinalDamage   │
└───────────────┬──────────────┘
                │
                ▼
┌──────────────────────────────┐
│        POST Observers        │
│       IPostDamageRule        │
│  - lifesteal                 │
│  - reflect                   │
│  - VFX / SFX                 │
└───────────────┬──────────────┘
                │
                ▼
┌──────────────────────────────┐
│      Death Interception      │
│    IBeforeDeathHandler       │
│  (may cancel death)          │
└───────────────┬──────────────┘
                │
                ▼
┌──────────────────────────────┐
│       Death Finalization     │
│   IHealthDeathHandler        │
│   UnityEvents + C# events    │
└──────────────────────────────┘

---

⚠ Notes

• Some rejection paths exit early and skip later stages
• POST observers do not run for all guard-level rejections

---

🧩 Where Extensions Plug In

Stage	Extension Surface
Mutation Guards	IHealthAuthority
PRE rules	IDamageRule
Damage math	internal to HealthSystem
Shields	IShield
Mutation	HealthSystem
POST reactions	IPostDamageRule
Death control	IBeforeDeathHandler, IHealthDeathHandler

---

🛡 Rules vs Shields

Rules change damage math.

Shields change damage interception.

Feature	Surface
Crit	Rule
Armor	Rule
Execute	Rule
Reflect	POST Rule
Barrier	Shield
Temporary HP	Shield

---

⚠ Important Guarantees

The pipeline guarantees:

• Stable, implementation-defined execution order
• HP mutation occurs at most once per evaluated damage attempt
• POST observers receive the evaluated damage context after PRE processing
• Death handlers run after mutation
• Death may be intercepted and cancelled

The pipeline does not guarantee:

• Cross-system atomicity
• Multiplayer replication
• Rollback determinism

---

🧠 Mental Shortcut

If you remember nothing else, remember this:

Authority
 → Rules
 → Shields
 → HP
 → Post
 → Death

Every feature in the Health system fits into one of these stages.

---

🧭 Pipeline Legend (Quick Teaching Reference)

Use this legend when explaining the pipeline:

Stage	Question it answers
Authority / Guards	Is mutation allowed?
Rules	How much damage should happen?
Shields	Does the damage reach HP?
HP	Apply the final mutation
Post	React to the result
Death	Handle the consequences

---

🔗 Related Docs

• Mental Model
• Integration Surfaces
• Public API
• System Guarantees Matrix
• FAQ