Skip to content

❤️ Using the Health System

The Health system is a modular, rule-driven, authority-aware health pipeline with optional invincibility, regeneration, shields, and pre/post rule stacks.
It is interface-driven, event-rich, and multiplayer-safe when paired with external authority gating.

This system focuses only on health state and mutation.
It does not implement combat logic, abilities, AI, UI frameworks, or networking transport.

📦 Overview

Attach HealthSystem to any GameObject and compose behaviour by adding optional components.

Required - HealthSystem — the sole owner of health state

Optional - Invincibility — HealthInvincibilityHandler - Regeneration — HealthRegenerationHandler - Shields — IShield implementations (capacity, rechargeable, reduction, overheal, chain) - Rules — damage and heal rules via DamageRuleHub / HealRuleHub - Death handling — IBeforeDeathHandler, IHealthDeathHandler - Authority — IHealthAuthority - UI / Debug — helper components only

Mutation may be gated via: - requireAuthority - a custom IHealthAuthority

🚀 Quick Start

  1. Add HealthSystem to your character
  2. (Optional) Add invincibility, regeneration, and shields
  3. (Optional) Add DamageRuleHub / HealRuleHub
  4. (Optional) Bind UI via HealthBarUIConnector
  5. Enable requireAuthority for multiplayer projects

Minimal Mutation Example

health.TryTakeDamage(20);
health.TryHeal(10);
health.ApplyPercentDamage(0.25f, bypassShields: true);

🧩 Composition Cheat Sheet

  • Core

  • HealthSystem

  • Rules

  • DamageRuleHub

  • HealRuleHub

  • Plug-ins

  • Invincibility
  • Regeneration

  • Shields

  • Lifecycle

  • IBeforeDeathHandler

  • IHealthDeathHandler

  • Authority

  • IHealthAuthority

🧮 Public API (Representative)

The exact overload set may vary by version.
Prefer interface-driven calls and context-based APIs for extensibility.

bool TryTakeDamage(int amount);
DamageResult ApplyDamage(in DamageContext ctx);

bool TryHeal(int amount);
void Kill();
void Revive(int health = -1);

int PreviewDamage(in DamageContext ctx, bool includeShields = true);
int PreviewHeal(int amount, bool includeRules = true, bool includeModifiers = true);

Preview APIs never mutate state and never fire events.

🔔 Events

Common events exposed by HealthSystem include: - Damaged / DamagedDetailed - Healed / HealedDetailed - HealthChanged - MaxChanged - Died / Revived - DamageAttempted - AuthorityDenied

Death Order (idempotent):
IBeforeDeathHandler → IHealthDeathHandler → UnityEvent → Died()

The death pipeline runs once per death unless the unit is explicitly revived.

🧠 Damage & Heal Rules

Damage Rules

  • PRE: crit, execute, armor, affinity, attacker/victim multipliers, clamps
  • POST: reflect, lifesteal, analytics, VFX

Heal Rules

  • PRE: anti-heal, low-HP boosts
  • POST: events, SFX, VFX

Rules mutate contexts, not health directly.

⚙️ Pipeline Order

Damage

PRE Rules → Shields → HealthSystem.ApplyDamage → POST Rules

Heal

PRE Rules → Healing modifiers → HealthSystem.TryHeal → POST Rules

🛡️ Shields

Available implementations include: - CapacityShield - RechargeableShield - ReductionShield - OverhealShield - ShieldChain

⚠️ ShieldPool does not implement IShield and is not used for damage absorption.

Shields that implement IShieldPreview participate correctly in damage previews.

🧭 UI & Debugging

  • HealthBarUIConnector — binds any IHealthReadonly to a UI Image
  • WorldSpaceHealthBar — optional world-space visual helper

These are optional helpers and are not required for runtime health logic.

🌐 Authority & Networking

Health authority enforcement is opt-in and only applies when requireAuthority is enabled.

Authority only gates mutation — it does not: - replicate state - synchronize health - determine network ownership

Resolution order: 1. Scene cache 2. Local binder 3. Parent binders 4. Scene roots 5. Global scan

Multiplayer projects should implement IHealthAuthority.

⚠️ Gotchas

  • SetMaxHealth(..., clampCurrent: true) may emit damage/death events
  • Preview APIs do not fire events
  • Previews ignore invincibility
  • Shields without IShieldPreview misrepresent previews
  • Crit determinism requires explicit seeding
  • Overheal spill requires spillOverhealToTempShield = true

❌ What You Should Not Modify

  • Do not modify HealthSystem
  • Do not set health values directly
  • Do not bypass ApplyDamage / TryHeal
  • Do not invoke death logic manually
  • Extend behaviour via rules, handlers, and interfaces instead

🧩 Extending the System

Implement your own: - IDamageRule, IPostDamageRule - IHealRule, IPostHealRule - IShield, IShieldPreview - IHealthAuthority - IBeforeDeathHandler, IHealthDeathHandler

🔗 See Also