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