Skip to content

⚰️ Health Lifecycle

📦 Folder Overview

This folder defines lifecycle control surfaces for Health.

These APIs handle state transitions (death, revive, direct value setting) that are separate from the damage/heal pipelines.

🎯 Purpose

Lifecycle exists to:

  • Control death and revive flows
  • Allow last-chance interception before death
  • Support direct state changes for setup, restore, or scripted events

Lifecycle operations are not part of the damage/heal pipelines.

🧩 What Lives Here

IHealthLifecycle

Direct lifecycle control:

  • Revive() / Revive(int)
  • SetCurrent(int)

Includes IHealthReadonly.

Notes:

  • Provides a surface for lifecycle transitions
  • Does not guarantee rule execution, event ordering, or side effects

IBeforeDeathHandler

Last-chance interception before death is finalized.

  • Return true → cancel death
  • Return false → allow death to continue

Responsibilities when cancelling:

  • Restore a valid alive state (for example, health > 0)
  • Ensure the object is not left in an invalid state

Receives:

  • IHealthLifecycle — lifecycle surface
  • LastDamageReport? — may be null
  • bool isKillCommand — explicit kill marker

IHealthDeathHandler

Death side-effects hook.

Used for:

  • animations
  • ragdoll
  • input disable
  • drops / cleanup

Notes:

  • Health state is already finalized when this runs

IHealthRegenerator

Optional seam for regeneration systems.

  • Allows external systems to trigger regen cooldown

IInvincibilityHandler

Invincibility (i-frame) control:

  • activation
  • ticking
  • state query

IInvincibilityTimeMode

Optional extension:

  • Signals preference for scaled vs unscaled time

IInvincibilityResettable

Optional extension for invincibility implementations that support explicit clearing.

  • ClearInvincibility()

Purpose:

Allows systems (for example, revive flows) to clear active invincibility state.

Important:

  • Not all implementations support this
  • Consumers should check for this capability before calling
  • Behaviour depends on implementation

Usage pattern:

if (invincibility is IInvincibilityResettable resettable)
    resettable.ClearInvincibility();

⚠️ Important Notes

Behaviour

Lifecycle operations:

  • Bypass damage rules
  • Bypass heal rules
  • Do not run pipeline evaluation

This is intentional.

Use lifecycle when you need direct state control rather than gameplay simulation.

Boundaries

Do not:

  • Assume lifecycle calls behave like damage/heal
  • Inject gameplay rules into lifecycle handlers
  • Depend on internal pipeline behaviour
  • Use lifecycle as a substitute for the damage system

🧠 Usage Guidance

  • Use lifecycle for setup, restore, and explicit state transitions
  • Use damage/heal pipelines for gameplay simulation
  • Keep lifecycle and simulation responsibilities separate
  • Health Abstractions
  • Contracts
  • Rules
  • Health System