Skip to content

⚙️ Health — Handlers

Handlers are behavioural, state‑affecting components that extend HealthSystem with gameplay‑level logic.

Where Effects provide visual or feedback decoration,
Handlers actively modify health state, lifecycle flow, or mutation rules.

All handlers are: - Optional - Modular - Auto‑discovered by HealthSystem when present - Safe to enable/disable at runtime

Health works without any handlers — add only what your game needs.

📦 What Handlers Are (and Aren’t)

Handlers are - Gameplay‑facing logic components - Mutation‑aware and authority‑gated - Participants in death, revive, regen, and invulnerability flows

Handlers are not - Core health ownership (that’s HealthSystem) - Visual‑only feedback (that’s Effects) - Networking or replication logic

🧩 Handler Components

AnimatorDeathHandler

Animation‑driven hook into the death and revive pipeline.

  • Implements IHealthDeathHandler
  • Triggers Animator triggers on:
  • death
  • revive (optional)
  • Executes inside the guaranteed pipeline order:
IBeforeDeathHandler
→ IHealthDeathHandler
→ UnityEvents
→ C# events (Died)

Best used for: - Character rigs - Animation FSMs - Animator‑controlled models

ExtraLifeTotemHandler

Death interception / “extra life” mechanic.

  • Implements IBeforeDeathHandler
  • Cancels death by restoring state via the provided IHealthLifecycle
  • By default, consumed on first use
  • Optional consumeOnUse = false allows repeated death interception
  • Runs before any death logic, ensuring guaranteed interception

Typical uses: - Extra‑life totems - Amulets - Pickups - Last‑stand mechanics

HealthDeathEffectHandler

Canonical death‑moment effect runner.

  • Executes exactly once per real death
  • Subscribed to the idempotent Died event
  • Supports:
  • Death VFX
  • Camera shake
  • Time slow
  • Optional destroy‑on‑death

#### Runtime Configuration

HealthDeathEffectHandler supports safe runtime configuration via public APIs. Inspector values define defaults; tools, buffs, or debug panels may override them at runtime.

Supported seams include: - ConfigureDeathVfx(GameObject prefab, Vector3 offset, float lifetime) - ConfigureCameraShake(bool enabled, float intensity, float duration) - ConfigureSlowTime(bool enabled, float scale, float duration) - SetDestroyOnDeath(bool enabled)

Preview Mode

Calling PreviewDeathEffects(): - Spawns death VFX only - Skips camera shake, time slow, and destruction - Safe to call from editor tools or debug panels

Designed to remain independent from: - animation handlers - visual Effects - gameplay systems

HealthInvincibilityHandler

Provides temporary invulnerability windows (i‑frames).

  • Configurable duration
  • Optional useUnscaledTime
  • Exposes C# events:
  • InvincibilityStarted
  • InvincibilityEnded
  • Fully compatible with:
  • damage
  • healing
  • DOT / HOT
  • rule pipelines
  • authority checks

Behaviour notes: - Ticked each frame by HealthSystem - If disabled mid‑flight, invincibility ends cleanly and emits an end edge once - Never leaves health in an invalid state

HealthRegenerationHandler

Flexible automatic health regeneration system.

Regeneration Modes

  • Discrete ticks
    Heal regenAmount every regenInterval
  • Smooth regeneration
    Accumulator‑based trickle that applies integer healing per frame, capped by a safety limit

Key Features

  • regenDelay — cooldown after applied damage
  • Optional regen ceiling:
  • Percent of Max
  • Percent above activation health
  • Absolute HP value
  • Fully routed through:
  • Heal()
  • heal PRE / POST rules
  • authority checks

Events

  • RegenStarted
  • RegenStopped
  • RegenTicked

Designed to be: - inspector‑friendly - predictable - multiplayer‑safe

🧮 Max Health Modifiers

MaxModifierStack

(also known as MaxHealthModifierStack)

Component that supports stackable max‑health modification.

Note
This component no longer lives under a .Modifiers namespace.
It is treated as a first‑class gameplay handler that coordinates max‑health changes safely with HealthSystem.

Supported Modifiers

  • Flat adjustments
  • Percent multipliers
  • Combined flat + percent entries

Clamp Modes

Mode Behaviour
Silent Applies without firing events
WithEvents Downward clamps emit damage / death events
ClampNoDeathEvents Clamps safely without triggering death

Core API

int id = PushFlat(int amount);
int id = PushPercent(float multiplier);
int id = Push(int flat, float percent);

Remove(id);
ClearAll();
Reapply();
RebaseToCurrent();
SetBaseline(int value);

Designed for: - Equipment systems - Temporary buffs / debuffs - RPG stat recalculation - Difficulty scaling

This component centralises max‑health math to avoid desync and event bugs.

🧠 Design & Usage Notes

Best Practices

  • Handlers = gameplay logic
  • Effects = visual feedback
  • Never mutate health directly inside handlers
  • All handler‑driven mutation respects: rules, shields, invincibility, and authority
  • Handlers may be freely combined to build: RPG, ARPG, roguelike, or action‑style behaviours

❌ What Handlers Should Not Do

  • Do not own health state
  • Do not bypass HealthSystem APIs
  • Do not assume networking or replication
  • Do not embed UI or presentation logic
  • Do not replace rule pipelines

Handlers exist to extend, not replace, the core system.

🔗 See Also