Skip to content

Health — Unity Integration / Core

Folder Overview

This folder contains the main Unity-facing runtime components for the Health system:

  • HealthSystem
  • HealthConfig
  • TeamProvider

They bridge abstract Health contracts into practical Unity behaviour.

Design Note — Unified Orchestrator (Intentional)

HealthSystem is deliberately large. It is the concrete, drop-in host most projects use directly, implementing the full set of health-facing interfaces in one discoverable place.

Distinct behaviours are already factored out into collaborators — shields, regeneration, death handling, invincibility, and the damage / heal rule hubs. What remains here is the cohesive damage / heal orchestration that wires them together, kept unified for a single integration point and readable end-to-end flow, not split for its own sake.

Consumers are encouraged to depend on the narrow interfaces (IHealthReadonly, IDamageable, IHealthWriter, IHealthMutator) rather than this concrete type.

Purpose

Provide the primary runtime implementation and authoring surfaces for Health in Unity.

What Lives Here

HealthSystem

Core runtime MonoBehaviour implementing:

  • IHealthReadonly
  • IHealthLifecycle
  • IHealthWriter
  • IDamageable
  • IHealthMutator

Responsibilities:

  • Damage and heal evaluation
  • Death and revive flows
  • Previews
  • Current/max mutation
  • Integration with rules, shields, authority, and handlers

HealthConfig

Optional ScriptableObject defaults for HealthSystem.

Used for:

  • Default max health
  • Initialisation behaviour
  • Revive defaults
  • Invincibility defaults

Notes:

  • Configuration only
  • Does not own runtime state

TeamProvider

Unity-facing implementation of ITeamProvider.

Provides:

  • Inspector-authored teamId

Notes:

  • Data only
  • No relationship or policy logic

Important Notes

Runtime Responsibilities

Damage

  • Guards (authority, dead, invincibility, locks)
  • PRE rules
  • Shields
  • HP mutation
  • POST observers
  • Death flow

Healing

  • Guards
  • PRE rules
  • Healing modifiers
  • HP mutation
  • POST observers

Lifecycle

  • Revive and kill
  • Direct mutation
  • Snapshot and restore
  • Preview APIs

Boundaries

Prefer depending on interfaces for gameplay code:

  • IHealthReadonly
  • IHealthWriter
  • IHealthMutator
  • IDamageable

Use HealthSystem directly only when implementation features are required.

Component Roles

  • HealthSystem → runtime implementation
  • HealthConfig → initial configuration
  • TeamProvider → identity data

Usage Guidance

  • Treat this folder as the primary authoring surface in Unity
  • Use abstractions to avoid unnecessary coupling
  • Keep gameplay logic in rules and handlers

Not for Production Use

This folder is part of the runtime implementation and should not be extended via internal details.

  • Health Abstractions
  • Rules
  • Shields
  • UI Connectors