Skip to content

💥 Health — Effects (Runtime)

This folder contains optional, gameplay-focused effect components that extend HealthSystem with over-time mechanics built on top of the core Health pipelines.

Health works perfectly without anything in this folder.

📦 What Runtime Effects Are (and Aren’t)

Runtime Effects are: - Gameplay-facing decorators on top of HealthSystem - Tick-driven or event-driven mechanics - Fully integrated with: - damage & heal rules (PRE / POST) - affinities - shields - invincibility - authority (requireAuthority) - Safe to add or remove at runtime

Runtime Effects are NOT: - Required dependencies - A full buff / status framework - Visual-only feedback scripts - A networking or replication system

If you need custom behaviour, you are expected to build on the public Health APIs (events, rules, contexts) rather than modifying these components.

⚔️ Over-Time Effects (Supported)

DotEffect (Damage Over Time)

Applies periodic damage through the full Health damage pipeline.

Features

  • Damage applied via HealthSystem.ApplyDamage
  • Fully respects:
  • damage rules (PRE / POST)
  • affinities
  • shields
  • invincibility
  • authority (requireAuthority)
  • Multiple stacking modes:
  • Refresh — one stack, duration resets on reapply
  • Additive — damage per tick = base × stacks
  • Independent — each stack has its own timer

Determinism (Optional)

  • seed = 0 → non-deterministic tick timing (UnityEngine.Random)
  • seed != 0 → deterministic tick timing (System.Random)

Note: determinism applies to tick scheduling only (jitter and initial offsets). Damage/healing outcomes still depend on rules, shields, authority, and current state.

Useful for: - multiplayer authority consistency - replays (timing stability) - lockstep simulations (tick alignment)

Jitter Options

  • tickJitterPercent — ±% variance per tick
  • initialOffsetJitterPercent — desynchronises initial tick timing

Lifecycle

  • Apply(attacker, teamId) — apply or stack the effect
  • ClearAll() — remove all stacks
  • Optional auto-clear on:
  • death
  • revive

Rejected ticks (authority, invincibility, shields) apply no damage and do not break the effect.

HotEffect (Heal Over Time)

Healing counterpart to DotEffect.

Features

  • Identical stacking modes and timing behaviour to DotEffect
  • Healing routed through:
  • TryHeal
  • heal PRE / POST rules
  • healing modifiers
  • Fully authority-aware when requireAuthority = true

Typical uses: - regen buffs - healing auras - rest zones - support abilities

☠️ Death Handling (See Handlers)

Death-related behaviour is handled by dedicated handler components and no longer lives here.

See: - Health/Handlers/AnimatorDeathHandler - Health/Handlers/*Death*

These are executed as part of the guaranteed, idempotent death pipeline (after all IBeforeDeathHandler checks).

🎨 Visual & Feedback Effects (Samples / Teachables)

Purely visual or presentation-focused scripts are not part of the supported runtime API. They live under:

Samples/Health/

or

Health/Teaching/Support/

(depending on whether they are used by Teachables).

Examples include: - DamageFlashOnHit - DeathFadeToBlack - DeathReviveBasicFX - ReviveBurst

These are provided as examples only: - Copy them if useful - Modify freely - No compatibility guarantees

🧠 Design Guidelines

Best Practices

  • Effects should observe, not control, health
  • Never mutate health directly outside HealthSystem APIs
  • Prefer C# events over UnityEvents for performance
  • DOT / HOT effects automatically obey: rules, affinities, shields, invincibility, and authority
  • Deterministic modes are recommended for multiplayer-authoritative games

📊 Effect → Use Case Mapping (Runtime)

Effect Typical Use Case
DotEffect Poison, burn, bleed, corruption
HotEffect Regen buffs, healing zones

❌ What Runtime Effects Should Not Do

  • Do not replace gameplay systems
  • Do not bypass HealthSystem APIs
  • Do not assume networking or replication
  • Do not encode permanent character state

Runtime Effects are decorators, not foundations.

🔗 See Also