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¶

It does not provide runtime behaviour on its own

This folder contains contracts only.

Root Health README
Rules
Shields
Authority