Skip to content

❤️ Core — Health System

This folder contains the central orchestration class for the Health framework.

This layer intentionally contains only HealthSystem. All supporting data, helpers, and behaviours live in their own dedicated buckets (Shared, Components, Rules, Authority, Shields, etc.).

If this folder is deleted, the Health framework cannot function.

🧠 What Lives Here (and Why)

The Core layer is responsible for:

  • Owning health state
  • Orchestrating damage and healing pipelines
  • Coordinating lifecycle flow (death / revive)
  • Enforcing authority gating
  • Providing preview, snapshot, and safety APIs

It deliberately does not:

  • Encode gameplay rules
  • Contain combat logic
  • Own authoring data
  • Handle networking or replication
  • Provide UI or behaviour glue

This separation keeps the core system boring, stable, and correct.

🩺 HealthSystem

The primary entry point and sole owner of health state.

All health mutation flows through this component.

Responsibilities

  • Track current and maximum health
  • Apply damage and healing through rule pipelines
  • Manage death and revive (idempotent)
  • Emit both C# events and designer-facing UnityEvents
  • Coordinate optional subsystems via cached interfaces
  • Enforce mutation authority when enabled

Extension Seams (Cached Interfaces)

Discovered at runtime and cached for performance:

  • IInvincibilityHandler
  • IHealthDeathHandler
  • IHealthRegenerator
  • IShield / IShieldPreview (via ShieldSelector)
  • IBeforeDeathHandler
  • DamageRuleHub / HealRuleHub

Components can be added or removed freely — HealthSystem adapts automatically.

Death & Lifecycle Flow

Death handling is ordered and idempotent:

IBeforeDeathHandler
→ IHealthDeathHandler
→ UnityEvents
→ C# events (Died)
  • The pipeline runs once per death
  • Handlers may cancel death by restoring state
  • Revive resets internal death flags cleanly

Authority Integration

  • Optional via requireAuthority
  • Supports injected authority resolvers for multiplayer/server authority
  • Falls back to a scene-based local authority policy when no resolver is injected

All mutations are gated:

  • damage
  • heal
  • kill
  • revive
  • max/current setters

When denied:

  • Mutation is blocked
  • LastAuthorityError is populated (display-only)
  • AuthorityDenied event is raised

See Authority README for integration details.

Preview & Safety APIs

HealthSystem provides non-mutating previews for AI, UI, and tooling:

  • PreviewDamage
  • PreviewDamageDetailed
  • PreviewHeal
  • PreviewHealDetailed

Additional safety features:

  • Damage locks (LockDamage, UnlockDamage, scoped locks)
  • Overflow healing spill into OverhealShield
  • Clamp-safe max-health changes
  • Snapshot capture / restore for save/load

Public Interaction Surfaces

Read-only (IHealthReadonly) - Current, Max, Normalized01 - IsAlive, IsDead, IsFull, IsEmpty

Writer (IHealthWriter) - Heal(int) - SetCurrent(int) - SetMax(int, bool) - ResetToMax()

Ergonomic helpers - TryTakeDamage(...) - TryTakeTrueDamage(...) - ApplyPercentDamage(...) - TryHealPercent(...)

Gameplay code should prefer these interfaces over referencing HealthSystem directly.

⚠️ Core Rules & Boundaries

  • HealthSystem is the only class that owns health state
  • Do not mutate health fields directly
  • Do not bypass damage/heal APIs
  • Do not encode gameplay rules here
  • Extend behaviour via:
  • rules
  • shields
  • handlers
  • components
  • authority integration

This layer exists to stay boring, stable, and correct.

🔗 See Also