Skip to content

🛡️ Health Shields

📦 Folder Overview

This folder defines the shield abstraction layer used by the Health system.

Shields intercept incoming damage before it reaches health.

🎯 Purpose

Shields provide:

  • A pre-health absorption layer
  • A way to extend survivability mechanics without modifying core logic
  • Separation between damage calculation and damage mitigation

🧩 What Lives Here

IShield

Runtime absorption contract.

bool TryAbsorb(ref int damage);

IShieldPreview

Optional preview contract for UI and AI.

int PreviewRemainder(int incoming);

IShieldTicketPool

Ticket-based aggregation of shield values.

int AddReturnTicket(int amount);
void RemoveByTicket(int ticket);
int Total { get; }

Purpose:

  • Tracks shield contributions using opaque ticket IDs
  • Allows systems to add and remove shield values safely
  • Supports stacked or temporary shielding
  • Does not absorb damage directly

⚠️ Important Notes

IShield Semantics

Implementations:

  • Mutate damage in place to represent remaining damage
  • Clamp damage to ≥ 0

  • Return:

  • true → damage fully absorbed

  • false → remaining damage continues

Behaviour

  • Shields run after PRE rules and before health application
  • Ordering is defined by the runtime system, not this layer
  • Shields may fully absorb, partially absorb, or pass through damage

Preview Behaviour

IShieldPreview implementations:

  • Do not mutate state
  • Return an estimate of remaining damage
  • Are expected to be safe for frequent calls

If a shield does not implement preview:

  • It is ignored by preview systems
  • Damage previews may be overestimated

Ticket Pool Behaviour

IShieldTicketPool:

  • Is not part of the damage pipeline
  • Does not absorb damage
  • Acts as a data aggregation tool for UI, FX, and external systems

Boundaries

This folder does not define:

  • Shield ordering
  • Shield selection
  • Shield composition (chains, stacking logic)
  • How ticket pools interact with runtime damage

These concerns belong to the Health system implementation.

🧠 Usage Guidance

  • Use shields to absorb or reduce incoming damage before it reaches health
  • Use preview interfaces for UI and AI estimation only
  • Use ticket pools for tracking and managing shield values externally
  • Contracts
  • Rules
  • Health System