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; see Rounding)      │
└───────────────┬──────────────┘
                │
                ▼
┌──────────────────────────────┐
│           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

Rounding¶

Damage math is evaluated in floats and lands on HP as an integer:

incoming = max(0, round(RawAmount * Multiplier) + FlatDelta)

Two details are worth knowing before you tune multipliers.

Rounding is half-to-even, not half-up

A midpoint result rounds to the nearest even integer, so the behaviour is asymmetric across values:

`RawAmount * Multiplier`	Lands as
1.5	2
2.5	2
3.5	4
4.5	4

A 0.5x multiplier on odd base damage will not always round the way you expect. If you need half-up behaviour, do the rounding yourself in a PRE rule and pass a whole number through RawAmount.

FlatDelta is added after the multiply

Flat bonuses are never scaled by Multiplier, and they are applied to the already-rounded product. A rule that adds +1 adds exactly 1.

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

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

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