🩺 Health Abstractions¶

📦 Folder Overview¶

This folder defines the stable runtime contracts for the Health system.

These abstractions are:

Pure contracts (no implementation)
Safe to depend on from gameplay, UI, AI, networking, and tooling
Designed to remain stable even if the underlying implementation changes

🎯 Purpose¶

Provide stable integration surfaces for reading, mutating, and reacting to health without depending on concrete implementations.

🧩 What Lives Here¶

Core Surfaces¶

Health is designed so most systems do not depend on HealthSystem directly.

Core interfaces

IHealthReadonly — read-only state (Current, Max, Normalized01, IsAlive, etc.)
IHealthWriter — controlled mutation (Heal, SetCurrent, SetMax, ResetToMax)
IDamageable — minimal “can take damage” surface

These are the primary integration surfaces. Prefer these over concrete implementations.

🧩 Components¶

Lifecycle — `IHealthLifecycle`¶

Explicit lifecycle control:

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

Includes IHealthReadonly.

Notes:

Safe surface for lifecycle transitions
Does not guarantee rule execution, event ordering, or side effects

Authority — `IHealthAuthority`¶

Determines whether mutation is allowed.

Pure permission check
No side effects

Important:

Does not handle networking, replication, or ownership

Damage Pipeline¶

Flow:

PRE rules → shields → apply → POST observers

Core types

DamageContext
DamageResult
DamageRejectionReason
DamageTag
RuleBypass
LastDamageReport

PRE rules — IDamageRule

Ordered by Priority
May mutate context
ctx.Cancelled = true rejects
return false stops further rule execution

POST — IPostDamageRule

Observer only
Must not mutate health directly
Not guaranteed for rejected hits

Affinity — IDamageAffinity

Optional multiplier provider
null = no opinion

Healing Pipeline¶

Flow:

PRE rules → apply → POST observers

Types

HealContext

PRE — IHealRule

Same semantics as damage rules

POST — IPostHealRule

Observer after application
Not guaranteed for rejected heals

Death & Lifecycle Hooks¶

IBeforeDeathHandler
May cancel death
Must restore valid state if cancelling
IHealthDeathHandler
Side effects only
Health state already finalized

Shields¶

IShield — runtime absorption
IShieldPreview — optional preview
IShieldTicketPool — ticket-based aggregation (not part of damage pipeline)

Preview systems ignore shields without IShieldPreview.

Optional Seams¶

IHealthRegenerator
IInvincibilityHandler
IInvincibilityTimeMode
IInvincibilityResettable

These are capability interfaces, not guarantees.

Mutation Surface — `IHealthMutator`¶

Minimal damage surface:

ApplyDamage(in DamageContext)
Died
Revived

⚠️ Important Notes¶

These abstractions do not define networking
Event ordering is not guaranteed
Internal pipelines are not exposed
Gameplay rules are not included

🧠 Usage Guidance¶

Depend on interfaces, not HealthSystem
Treat contracts as stable surfaces for integration
Extend behaviour through rules, shields, and handlers

🚫 Not for Production Use¶

This folder contains contracts only. It does not provide runtime behaviour on its own.

Root Health README
Rules
Shields
Authority