Skip to content

💚 Health — Heal Rules

This folder contains all healing-side rule components that plug into HealRuleHub.

Heal rules define how healing is gated, modified, or reacted to as it flows through HealthSystem.

All heal rules are: - Modular - Priority-driven - Low-allocation at runtime - Safe to compose per prefab

📦 What Heal Rules Are (and Aren’t)

Heal rules are - Deterministic pipeline steps - PRE mutators or POST observers - The primary extension surface for healing logic

Heal rules are not - Health state owners - Regeneration systems (those are Handlers) - Networking or replication logic - UI systems

Heal rules shape how much healing applies — never when or why healing happens.

🧩 Basic Usage

  1. Add a HealRuleHub to a GameObject with HealthSystem
  2. Add any rule components from this folder
  3. Rules implementing:
  4. IHealRule run in PRE
  5. IPostHealRule run in POST
  6. Lower Priority runs first
  7. POST rules always run after healing has been applied

No heal rules are required by default.

🧮 Common Priority Bands

Priority Purpose Example Rules
0–99 (reserved / custom gates) —
100 Anti-heal AntiHealRule
200 Heal boosts LowHPHealBoostRule
999 Post-heal reactions HealEventPostRule, HealSFXPostRule, HealVFXPostRule

See HealRulePriority.cs for canonical constants.

⚙️ PRE Heal Rules

PRE rules mutate HealContext before healing is applied.

They may: - modify Multiplier or FlatDelta - set ctx.Cancelled = true - return false to stop the chain

AntiHealRule (priority 100)

Reduces or blocks healing entirely.

Fields

  • healMultiplier
  • 0 → full block
  • 0.5 → half healing
  • 1 → no change
  • blockChance
  • Random chance to cancel the heal outright

Behaviour

  • Mutates ctx.Multiplier or
  • Cancels the heal via ctx.Cancelled

Typical uses: - curses - poison effects - boss mechanics - debuffs

LowHPHealBoostRule (priority 200)

Boosts healing when the target is at low health.

Fields

  • threshold01 — health percentage threshold
  • boostMultiplier — multiplier applied below threshold

Behaviour

  • Multiplies ctx.Multiplier when Current / Max ≤ threshold
  • Enables clutch or “last-stand” mechanics
  • Stacks multiplicatively with other heal rules and modifiers

💥 POST Heal Rules

POST rules observe results only. They never mutate health or context.

ctx.FinalApplied is guaranteed to be valid.

HealEventPostRule

  • Emits a UnityEvent<int> with the final applied heal amount
  • Includes minInterval spam guard
  • Ideal for:
  • UI hooks
  • designer-driven logic
  • telemetry

HealSFXPostRule

  • Plays a one-shot AudioClip when healing applies
  • Fields:
  • clip
  • volume
  • minInterval
  • Ensures an AudioSource exists (creates one if needed)

HealVFXPostRule

  • Spawns a healing VFX prefab on heal
  • Configurable:
  • world offset
  • lifetime
  • scale-by-heal amount
  • spam guard

Typical uses: - healing spells - potions - MMO-style heal feedback

🧠 Design Guarantees

  • PRE rules mutate context; POST rules observe only
  • Heal rules never apply health directly
  • Execution order is explicit and deterministic
  • Rules can be added or removed at runtime
  • Different prefabs can have entirely different heal rule stacks

❌ What Heal Rules Should Not Do

  • Do not apply healing directly
  • Do not assume rule execution order beyond Priority
  • Do not embed regeneration logic here
  • Do not encode networking or authority
  • Do not mix UI or presentation logic into PRE rules

Heal rules exist to stay small, predictable, and composable.

🔗 See Also