Skip to content

❤️ Health System

The Health system is a modular, rule-driven, shield-aware, authority-gated mutation pipeline.

It owns exactly one thing:

Health state (Current / Max) and how it changes.

Everything else — combat logic, abilities, UI frameworks, networking transport — is external.

📦 Folder Overview

HealthSystem

  • Owns Current and Max
  • Runs the damage and heal mutation pipelines (when those APIs are used)
  • Coordinates rules, shields, lifecycle handlers, and authority
  • Emits ordered runtime events for mutation outcomes

Health does NOT

  • Replicate state
  • Implement combat mechanics
  • Own AI / abilities
  • Provide networking transport
  • Guarantee prediction / rollback

Authority gating is opt-in and only blocks mutation.

🎯 Purpose

Provide a single, consistent surface for managing health state and applying mutations through a controlled pipeline.

⚠️ Important Notes

Not every health change goes through the damage/heal pipelines.

Some APIs intentionally mutate state directly:

  • Setup / initialization
  • Save / load restore
  • Revive flows
  • Max-health recalculation
  • Debug / tooling

This is by design.

🧩 What Lives Here

Attach HealthSystem and compose behaviour via optional components.

Required

  • HealthSystem

Optional (Plug-in)

Rules

  • DamageRuleHub
  • HealRuleHub

Shields

  • IShield implementations (Capacity, Rechargeable, Reduction, Overheal, Chain)

Lifecycle

  • IBeforeDeathHandler
  • IHealthDeathHandler

Invincibility

  • IInvincibilityHandler

Regeneration

  • IHealthRegenerator

Authority

  • IHealthAuthority
  • SetAuthorityResolver(...)

HealthSystem can operate on its own. All other pieces are optional.

🧠 Usage Guidance

Minimal usage:

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

Extensible usage:

var ctx = DamageContext.CreateBasic(attacker, victim, 30, DamageTag.Fire);
health.ApplyDamage(in ctx);

🧪 Diagnostics

Pipeline Overview (Damage)

1) Guards
   - Authority (optional)
   - Dead target
   - Invincibility
   - Damage locks

2) Context normalization

3) PRE rules (DamageRuleHub)

4) Fold math

5) Shields (if not bypassed)

6) Apply to HP

7) Emit damage events

8) POST observers (for evaluated contexts)

9) Death pipeline (if HP <= 0)
   - IBeforeDeathHandler
   - IHealthDeathHandler
   - Events

Notes:

  • Some rejected paths still run POST observers
  • Early guard rejections do not

Pipeline Overview (Heal)

1) Guards
2) PRE heal rules (HealRuleHub)
3) Fold math
4) Healing modifiers (IHealingModifier)
5) Apply to HP
6) POST observers (when present)

🧩 Components

Events

Representative events:

  • Damaged / DamagedDetailed
  • Healed / HealedDetailed
  • HealthChanged
  • MaxChanged
  • Died / Revived
  • DamageAttempted
  • AuthorityDenied

Death handling is idempotent.

Rules

Rules mutate contexts, not HP directly.

  • PRE rules modify damage/heal input
  • POST rules react to final outcomes

Do not mutate internal state directly. Use public APIs.

Shields

Shields run after PRE rules and before HP mutation.

They:

  • Intercept damage
  • May fully absorb hits
  • May preview results

ShieldPool is not a shield.

🌐 Authority (Opt-In)

Enabled via:

requireAuthority = true;

Authority:

  • Blocks mutation
  • Raises AuthorityDenied
  • Does not replicate state
  • Does not define ownership

🧠 Usage Guidance

Preview APIs

PreviewDamage(...)
PreviewHeal(...)

Behaviour:

  • No mutation
  • No events
  • No death triggers

Limitations:

  • Ignores invincibility
  • May overestimate damage if shields lack preview support

⚠️ Important Notes

  • SetMaxHealth(..., clampCurrent: true) may emit damage/death events
  • Damage may be cancelled before shields
  • Healing may be reduced or blocked
  • Execute rules may bypass defenses
  • Reflect/lifesteal run POST
  • Determinism depends on RNG configuration

🚫 Not for Production Use

This folder contains runtime systems intended for gameplay use.

Debug and tooling APIs exist but should not be relied on as gameplay integration surfaces.

  • Core → Health/UnityIntegration/Core/
  • Rules → Health/Rules/
  • Shields → Health/Shields/
  • Lifecycle → `Health/UnityIntegration