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¶

Related Documentation¶

• Health Abstractions
• Rules
• Health System