Skip to content

❤️ Health System --- Overview

The RevFramework Health System is a modular, interface-driven mutation pipeline for managing character health.

It is designed for:

  • Deterministic rule ordering
  • Composable shields
  • Authority-gated mutation (optional)
  • Explicit lifecycle control
  • Event-driven UI integration
  • Zero gameplay lock-in

Health owns exactly one responsibility:

Own and mutate HP (Current / Max) safely and predictably.

Everything else composes around that.

🧱 Architecture Summary

The Health system is built from layers:

Layer Responsibility

HealthSystem Owns HP state and runs pipelines

Rules Modify damage/heal math (PRE/POST)

Shields Intercept damage before HP changes

Handlers Lifecycle coordination (death, regen, invincibility, etc.)

Authority Optional mutation gating

Events Deterministic, ordered notifications

UI Binding Via IHealthReadonly + events (no core coupling)

Health does not depend on optional layers — they are purely additive.

🔄 True Damage Flow

When damage is applied:

DamageContext created
    ↓
Authority gate (optional)
    ↓
State guards (dead, invincible, damage-locked)
    ↓
PRE Damage Rules (ordered by Priority)
    ↓
Damage evaluation (RawAmount * Multiplier + FlatDelta)
    ↓
IShield (if present and not bypassed)
    ↓
HP mutation (Current -= applied)
    ↓
POST observers
    ↓
Death pipeline (if HP <= 0)

Key truths:

  • PRE rules modify context only.
  • Shields intercept integer damage after rules.
  • BypassShields skips shield interception.
  • Only HealthSystem mutates HP.
  • POST observers do not change the finalized outcome of the current attempt.
  • POST observers may trigger new mutations, which run through a separate pipeline.

💚 Heal Flow

Authority gate (optional)
    ↓
State guards (dead check)
    ↓
PRE Heal Rules
    ↓
Damage evaluation
    ↓
Healing Modifiers (IHealingModifier)
    ↓
HP mutation
    ↓
POST observers

Lifecycle APIs (Revive, SetCurrent, SetMax) intentionally bypass the rule pipeline.

🛡 Shields

If a shield component implementing IShield is present, HealthSystem resolves and invokes it.

Core implementations include:

  • Capacity shields
  • Rechargeable shields
  • Stateless reduction shields
  • Overheal (temporary HP)
  • Shield chains

Shields never mutate HP directly.

ShieldPool is not a shield --- it is a ticketed value accumulator for UI/FX.

🌐 Authority (Optional)

Authority gating is opt-in.

When enabled:

  • Mutation is blocked if authority denies it
  • PRE rules and shields do not execute
  • HP remains unchanged
  • AuthorityDenied is raised
  • The pipeline stops immediately

Authority does not:

  • Replicate state
  • Define ownership model
  • Provide networking transport
  • Guarantee rollback determinism

Sample authority binders for NGO, Mirror, and Fusion are provided in the Samples folder.

🔔 Events

Supported mutation paths emit deterministic, ordered C# events such as:

  • Damaged, Healed
  • HealthChanged
  • MaxChanged
  • Died, Revived
  • DamageAttempted
  • AuthorityDenied

Event listeners are isolated --- exceptions are caught and logged.

🧩 UI Integration

UI should depend on:

  • IHealthReadonly
  • HealthChanged
  • Damaged / Healed
  • MaxChanged

UI is not coupled to internal fields.

A HealthBarUIConnector component is available for plug-and-play binding.

🧠 Design Philosophy

Health is:

  • Deterministic in ordering
  • Composition-first
  • Interface-driven
  • Explicit about extension seams
  • Honest about boundaries

Health is not:

  • A netcode framework
  • A transaction engine
  • A prediction/rollback system
  • A persistence manager
  • A gameplay logic brain

Preview APIs provide estimates and may not match final results due to runtime state and rule behaviour.

If it's not part of the public API or guarantees matrix, it's not promised behaviour.

🔗 See Also

  • Mental Model
  • Public API
  • System Guarantees Matrix
  • Rules
  • Shields
  • Handlers