Skip to content

🧱 Health — Internal Systems

This folder contains internal infrastructure code used by the Health system. These types exist to support resolution, coordination, and safe orchestration between gameplay-facing components — they are not intended as primary extension points.

⚠️ Important Everything in this folder should be treated as implementation detail. Public types may exist for technical reasons, but nothing here is a supported gameplay API.

📌 What This Folder Is For

The .Internal namespace contains: - Resolution helpers - Selection logic - Scene-level caches - Cross-cutting utilities used by HealthSystem

These classes typically: - Have no inspector presence - Are auto-invoked by core systems - Are designed to be hard to misuse accidentally - May change without notice between versions

If you are building gameplay logic, you should almost never reference these directly.

🧩 Internal Components

CombatUtility

Small helper methods for interacting with HealthCombatState if present.

  • Safe no-ops when the target has no combat state
  • Used internally to coordinate combat entry/exit from damage events
  • Explicit methods prevent accidental misuse

Typical internal uses: - Entering combat on outgoing damage attempts - Forcing combat state during scripted sequences - Exiting combat for stealth or test scenarios

HealthAuthority

Scene-scoped resolver for IHealthAuthority.

Responsibilities: - Resolves the active authority policy for a given context - Caches usable authorities per scene for performance - Detects inactive or disabled authority binders for diagnostics

Resolution order (simplified): 1. Scene cache (active, enabled only) 2. Local component 3. Parent hierarchy 4. Scene roots 5. Global scan (diagnostic fallback)

ℹ️ Inactive or disabled authority binders may be detected for warnings, but are never cached or used for mutation checks.

ShieldSelector

Internal selection logic for determining which shield implementation a HealthSystem should use.

  • Applies a fixed, deterministic precedence order
  • Supports explicit overrides, chains, and child shields
  • Never mutates shield state

Shield precedence: 1. Explicit shield provider (if enabled) 2. ShieldChain on the same GameObject 3. First enabled IShield on the same GameObject 4. ShieldChain in children 5. First enabled IShield in children

This logic is intentionally centralized to avoid: - inconsistent shield application - order-dependent bugs - duplicated selection logic across systems

TeamUtility

Lightweight helper for resolving team / faction information.

  • Attempts to read ITeamProvider from a target
  • Falls back to team 0 when none is present

This helper exists to keep team resolution consistent across: - damage rules - combat utilities - internal health logic

Projects with custom team or faction systems are free to replace or bypass this logic.

❌ What You Should Not Do

Do not: - Depend on .Internal types for gameplay logic - Call these helpers directly from game code - Assume behaviour here is stable API - Mirror this logic instead of using public extension points

If you find yourself wanting to use something from .Internal, it is usually a sign that: - a public abstraction is missing, or - your logic belongs inside a handler, rule, or authority implementation

🧠 Design Philosophy

The .Internal layer exists to: - Keep HealthSystem lean and readable - Centralise complex coordination logic - Prevent API surface bloat - Protect gameplay code from fragile implementation details

This separation allows the Health system to evolve safely without breaking supported user-facing APIs.

🔗 See Also