Skip to content

💚 Health — Heal Rules

📦 Folder Overview

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

Heal rules define how healing is modified and observed as it flows through HealthSystem.

All heal rules are:

  • Modular
  • Priority-driven
  • Designed to avoid allocations in hot paths
  • Composable per prefab

🎯 Purpose

Provide a composable, priority-driven pipeline for healing behaviour without modifying core systems.

🧩 What Lives Here

PRE Rules

  • Implement IHealRule
  • Mutate HealContext before healing is applied

POST Observers

  • Implement IPostHealRule
  • Observe finalized results after evaluation

🧠 Usage Guidance

Basic Usage

  1. Add HealRuleHub to a GameObject with HealthSystem
  2. Add rule components from this folder
  3. PRE rules run in ascending Priority
  4. POST observers run after evaluation completes (execution for rejected heals is implementation-defined)

No heal rules are required by default.

Common Priority Bands

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

See HealRulePriority.cs for canonical constants.

⚠️ Important Notes

PRE Rule Behaviour

PRE rules may:

  • Modify Multiplier or FlatDelta
  • Set ctx.Cancelled = true
  • Return false to stop further rule execution

POST Rule Behaviour

POST rules:

  • Do not mutate health state
  • React to finalized results only
  • Use ctx.FinalApplied when healing is applied

Boundaries

Heal rules should not:

  • Apply healing directly
  • Assume ordering beyond Priority
  • Implement regeneration systems
  • Encode networking or authority logic
  • Include UI logic in PRE rules

Rules operate on context and act as extensions, not owners.

🧩 Components

AntiHealRule (priority 100)

  • Reduces or blocks healing
  • Uses healMultiplier and optional blockChance
  • May scale or cancel healing

LowHPHealBoostRule (priority 200)

  • Boosts healing when health is below a threshold
  • Multiplies ctx.Multiplier
  • Stacks with other modifiers

HealEventPostRule

  • Emits a UnityEvent<int> with applied heal amount
  • Includes rate limiting

HealSFXPostRule

  • Plays an AudioClip when healing applies
  • Ensures an AudioSource exists

HealVFXPostRule

  • Spawns VFX on heal
  • Optional scaling based on FinalApplied
  • Includes rate limiting
  • Rules Overview
  • Damage Rules
  • Rules Abstractions
  • Handlers