Health — Rules¶

Folder Overview¶

This folder is the entry point for the Health rule system.

Rules define how damage and healing behave between incoming data (DamageContext / HealContext) and the core HealthSystem.

They are the primary extension surface for combat math, modifiers, and reactive behaviour.

Purpose¶

Rules provide:

• A composable pipeline for damage and healing
• External behaviour injection without modifying core systems
• Separation between data (contracts) and behaviour (rules)

What Lives Here¶

Priority Definitions¶

• DamageRulePriority.cs
• HealRulePriority.cs

Defines canonical ordering constants used by all rule families.

Use these to keep ordering consistent and debuggable.

Components¶

Pipeline Overview (Damage)¶

1. Guards

2. authority (optional)

3. dead target
4. invincibility

5. damage locks

6. PRE rules (DamageRuleHub) [ascending Priority]

7. mutate DamageContext (RawAmount, Multiplier, FlatDelta, Cancelled, BypassRules)

8. Fold damage

9. RawAmount * Multiplier + FlatDelta

10. Shields (optional)

11. IShield.TryAbsorb(ref damage) unless bypassed

12. Apply to HP

13. Current -= applied

14. POST observers (DamageRuleHub.NotifyPost)

15. IPostDamageRule observe finalized context (FinalApplied)

16. Execution for rejected attempts is implementation-defined

17. Death pipeline (if HP ≤ 0)

18. IBeforeDeathHandler[]

19. IHealthDeathHandler
20. Events

POST observers run after evaluation completes and should be treated as observer hooks.

Pipeline Overview (Heal)¶

1. Guards

2. authority (optional)

3. dead target

4. invalid amount

5. PRE heal rules (HealRuleHub) [ascending Priority]

6. mutate HealContext (RawAmount, Multiplier, FlatDelta, Cancelled)

7. Fold heal

8. RawAmount * Multiplier + FlatDelta

9. Healing modifiers (IHealingModifier)

10. Apply to HP

11. Current += applied (clamped)

12. POST observers (HealRuleHub.NotifyPost)

13. IPostHealRule observe finalized context (FinalApplied)

14. Execution for rejected attempts is implementation-defined

Important Notes¶

Priority System¶

• Lower values run first
• Higher values run later
• POST observers run after evaluation

Use constants from:

• DamageRulePriority
• HealRulePriority

Avoid hardcoding numbers.

Boundaries¶

Rules should not:

• Mutate HP directly
• Rely on implicit ordering
• Encode networking or authority logic
• Treat helpers as guaranteed behaviour

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

Usage Guidance¶

Quick Start¶

1. Add DamageRuleHub and/or HealRuleHub to the same GameObject as HealthSystem
2. Add rule components (PRE and/or POST)
3. Use ordering constants
4. Add shields if needed (run after PRE rules)

No rules are required by default.

Authoring Examples¶

Damage PRE rule

public sealed class MyRule : MonoBehaviour, IDamageRule
{
    public int Priority => DamageRulePriority.Armor + 10;

    public bool Apply(ref DamageContext ctx)
    {
        return true;
    }
}

Damage POST observer

public sealed class MyObserver : MonoBehaviour, IPostDamageRule
{
    public void OnDamageApplied(in DamageContext ctx)
    {
        if (ctx.FinalApplied <= 0) return;
    }
}

Heal PRE rule

public sealed class MyHealGate : MonoBehaviour, IHealRule
{
    public int Priority => HealRulePriority.AntiHeal + 10;

    public bool Apply(ref HealContext ctx)
    {
        return true;
    }
}

Related Documentation¶

• Rules Abstractions
• Damage Rules
• Heal Rules
• Rule Hubs
• Modifiers
• Authority