🛠️ Health System — Public API

This page defines the supported, stable public API for the RevFramework Health System.

If something is not listed here, it is not supported as a public integration point — even if it appears accessible in code.

Audience: Developers integrating Health into gameplay or UI
Scope: Runtime public API only (Editor/Teaching helpers excluded)
Stability: Breaking changes to items listed here are avoided or clearly versioned

API Stability Policy

Items listed on this page are considered stable.
New public APIs may be added over time.
Internals may change without notice.

RevFramework guarantees stability only for documented public APIs.
Usage of internal or undocumented code is unsupported and may break without notice.

---

📌 Core Concepts

• HealthSystem is the orchestration root for:
• damage, healing, death, revive, max/current control
• optional i-frames, regen, shields, and rules
• Health is component-driven:
• add rules/handlers/shields as components
• subscribe to events for gameplay/UI
• Authority gating is optional:
• enable requireAuthority for multiplayer/server-authority setups
• inject your own resolver or supply an IHealthAuthority binder
• Teaching panels act as hostile consumers:
• if Teachables compile and run, the public contract is valid

---

🧱 Core Component

HealthSystem

The central runtime MonoBehaviour.

Supported Responsibilities

• Apply damage through rules + shields pipeline
• Apply healing through heal rules + healing modifiers
• Idempotent death pipeline + revive
• Max/current mutation APIs (with explicit behaviour)
• Non-mutating previews for UI/AI (damage/heal)
• Authority gating + denial feedback

---

🧩 Public Data Types

DamageContext

struct DamageContext

A snapshot for a single damage attempt.

Supported stable fields (safe to rely on): - Amount - FinalApplied - BypassShields - Cancelled - Attacker - Victim - SourceId - Tags

Other fields may exist for diagnostics/metadata. They may change without notice.

---

DamageResult

readonly struct DamageResult
{
    bool Applied
    int FinalApplied
    DamageRejectionReason Reason
    bool BypassedShields
}

---

LastDamageReport

readonly struct LastDamageReport
{
    int Requested
    int Applied
    bool Cancelled
    bool BypassShields
    bool FromKillCommand
    GameObject Attacker
    string SourceId
}

---

HealContext

struct HealContext
{
    GameObject Target
    int RawAmount
    float Multiplier
    int FlatDelta
    bool Cancelled
    int FinalApplied
}

---

Enums

enum DamageRejectionReason
[Flags] enum DamageTag
[Flags] enum RuleBypass

---

📈 Read-only State

int Current { get; }
int Max { get; }
float Normalized01 { get; }
bool IsAlive { get; }
bool IsDead { get; }
bool IsFull { get; }
bool IsEmpty { get; }

---

▶️ Damage API

Canonical entry

DamageResult ApplyDamage(in DamageContext input)

---

Ergonomic wrappers

bool TryTakeDamage(in DamageContext input)
bool TryTakeDamage(int amount)
bool TryTakeDamage(GameObject attacker, int amount, DamageTag tags = ..., bool bypassShields = ..., float multiplier = ..., int flatDelta = ..., Vector3? hitPoint = ..., Vector3? hitNormal = ..., Vector3? direction = ..., Vector3? impulse = ..., string sourceId = ..., int teamId = ...)
bool TryTakeTrueDamage(int amount, GameObject attacker = null, DamageTag tags = ...)
bool ApplyPercentDamage(float percent01, GameObject attacker = null, DamageTag tags = ..., bool bypassShields = false)

---

🛡️ Damage Lock

bool DamageLocked { get; }
void LockDamage()
void UnlockDamage()
IDisposable LockDamageScoped()

---

❤️ Healing API

Canonical entry

bool TryHeal(int amount)

Convenience helpers

bool TryHealPercent(float percent01)
int ComputeOverflow(int healAmount)

Interface-friendly wrapper

bool Heal(int amount)

---

🧪 Previews (Non-Mutating)

Damage previews

int PreviewDamage(in DamageContext input, bool includeShields = true)
void PreviewDamageDetailed(in DamageContext input, bool includeShields, out int afterRules, out int afterShields)

Heal previews

int PreviewHeal(int amount, bool includeRules = true, bool includeModifiers = true)
void PreviewHealDetailed(int amount, out int wouldApply, out int overflow, bool includeRules = true, bool includeModifiers = true)

---

☠️ Lifecycle (Kill / Revive / Max / Current)

void Kill()
void Revive(int health = -1)

void SetCurrent(int value)
void SetCurrentHealth(int value)

void SetMax(int value, bool clampCurrent = true)
void SetMaxHealth(int value, bool clampCurrent = true)
void SetMaxHealthSilent(int value, bool clampCurrent = true)
void SetMaxHealthClampNoDeathEvents(int value)

void ResetToMax()

---

💾 Save / Load Snapshot

struct HealthSnapshot
{
    int Max;
    int Current;
    bool Dead;
}

HealthSnapshot CaptureSnapshot()
void RestoreSnapshot(in HealthSnapshot s)

---

📣 Events

event Action Died
event Action Revived

event Action<int> Damaged
event Action<int, int> DamagedDetailed

event Action<int> Healed
event Action<int, int> HealedDetailed

event Action<int, int> HealthChanged
event Action<int, int> MaxChanged

event Action<DamageResult, DamageContext> DamageAttempted
event Action<string> AuthorityDenied

---

🔐 Authority

Public authority seam

interface IHealthAuthority
{
    bool HasAuthority(IHealthReadonly health);
}

HealthSystem authority surface

void SetAuthorityResolver(Func<bool> resolver)
void ClearAuthorityResolver()

bool HasAuthorityResolver { get; }
string LastAuthorityError { get; }

---

🛡️ Shields

Shield seams

interface IShield { bool TryAbsorb(ref int damage); }
interface IShieldPreview { int PreviewRemainder(int incoming); }

HealthSystem shield assignment

void SetShield(IShield shield)
void SetShieldProvider(MonoBehaviour provider)

---

🧩 Rules

Damage rules

interface IDamageRule { int Priority; bool Apply(ref DamageContext ctx); }
interface IPostDamageRule { void OnDamageApplied(in DamageContext ctx); }

Heal rules

interface IHealRule { int Priority; bool Apply(ref HealContext ctx); }
interface IPostHealRule { void OnHealedApplied(in HealContext ctx); }

---

❌ Not Supported

• Accessing internal helpers, selectors, or caches (anything in *.Internal or undocumented internals)
• Reflecting into private HealthSystem state
• Relying on undocumented DamageContext fields
• Relying on undocumented behaviour ordering outside DamageRulePriority / HealRulePriority
• Mutating rules/shields via raw field writes (use supported setters when provided)

---

🧠 Design Guarantee

If Teachables compile and run, the Health public API is valid.