Skip to content

📦 Health Contracts

📦 Folder Overview

This folder defines the stable data contracts used by the Health system.

These types represent the public data shapes that flow through damage, healing, and persistence.

🎯 Purpose

Contracts exist to:

  • Provide stable, engine-level data structures
  • Enable safe cross-system communication
  • Decouple gameplay code from concrete implementations

They are safe to reference from:

  • Gameplay
  • AI
  • UI
  • Telemetry
  • Networking

🧩 What Lives Here

Damage

  • DamageContext — mutable evaluation context
  • DamageResult — final outcome
  • DamageRejectionReason — canonical rejection reasons
  • DamageTag — semantic flags
  • RuleBypass — selective rule skipping
  • LastDamageReport — minimal public snapshot

Healing

  • HealContext — mutable heal evaluation context

Persistence

  • HealthSnapshot — serializable state for save/load and restore

⚠️ Important Notes

Design Constraints

These contracts are:

  • Stable — changes affect public API
  • Minimal — no unnecessary fields or helpers
  • Engine-facing — describe data, not behaviour

Boundaries

Do not:

  • Leak internal pipeline mechanics into these types
  • Add gameplay logic or rule behaviour
  • Introduce convenience helpers that encode decisions
  • Depend on concrete systems or Core implementation details

These are data carriers only.

Change Policy

Changing anything in this folder is a public API change.

This means:

  • It affects all consumers (UI, gameplay, integrations)
  • It should be deliberate and justified
  • It should be treated as a versioned change

🧠 Usage Guidance

  • Treat contracts as stable integration surfaces
  • Do not embed behaviour into contract types
  • Keep data, rules, and execution separated

🚫 Not for Production Use

This folder does not provide runtime behaviour. It defines data structures used by runtime systems.

  • Health Abstractions
  • Rules
  • Health System