Health System — Overview¶

The RevFramework Health System is a modular, interface-driven mutation pipeline for managing character health.

It is designed for:

• Deterministic rule ordering
• Composable shields
• Authority-gated mutation (optional)
• Explicit lifecycle control
• Event-driven UI integration
• Zero gameplay lock-in

Health owns exactly one responsibility:

Architecture Summary¶

The Health system is built from layers:

Health does not depend on optional layers — they are purely additive.

True Damage Flow¶

When damage is applied:

DamageContext created
    ↓
Authority gate (optional)
    ↓
State guards (dead, invincible, damage-locked)
    ↓
PRE Damage Rules (ordered by Priority)
    ↓
Damage evaluation (RawAmount * Multiplier + FlatDelta)
    ↓
IShield (if present and not bypassed)
    ↓
HP mutation (Current -= applied)
    ↓
POST observers
    ↓
Death pipeline (if HP <= 0)

Heal Flow¶

Authority gate (optional)
    ↓
State guards (dead check)
    ↓
PRE Heal Rules
    ↓
Damage evaluation
    ↓
Healing Modifiers (IHealingModifier)
    ↓
HP mutation
    ↓
POST observers

Lifecycle APIs (Revive, SetCurrent, SetMax) intentionally bypass the rule pipeline.

Shields¶

If a shield component implementing IShield is present, HealthSystem resolves and invokes it.

Core implementations include:

• Capacity shields
• Rechargeable shields
• Stateless reduction shields
• Overheal (temporary HP)
• Shield chains

Shields never mutate HP directly.

ShieldPool is not a shield — it is a ticketed value accumulator for UI/FX.

Authority (Optional)¶

Authority gating is opt-in.

When enabled:

• Mutation is blocked if authority denies it
• PRE rules and shields do not execute
• HP remains unchanged
• AuthorityDenied is raised
• The pipeline stops immediately

Authority does not:

• Replicate state
• Define ownership model
• Provide networking transport
• Guarantee rollback determinism

Supplying your own authority¶

Automatic resolution searches for IHealthAuthority, nearest first: the object being gated, then its parents, then the scene. The two hierarchy steps run ahead of the scene cache and are never cached, so an actor carrying its own authority is governed by that one whether or not another component resolved first. A custom implementation left in the scene is discovered the same way the shipped HealthAuthorityBinder is, and the same active-and-enabled test applies to both — one that has been switched off falls through to a working one rather than becoming the scene's authority, and it falls through on the very next mutation, including for a component that had already resolved it.

You can still install one explicitly, which takes precedence over anything resolved from the scene:

health.SetAuthorityResolver(() => myNetworkAuthority.HasAuthority(health));

An injected resolver takes precedence over any binder, so you do not need to remove or disable the binder to replace it. ClearAuthorityResolver() returns the component to automatic resolution.

Events¶

Supported mutation paths emit deterministic, ordered C# events such as:

• Damaged, Healed
• HealthChanged
• MaxChanged
• Died, Revived
• DamageAttempted
• AuthorityDenied

Event listeners are isolated — exceptions are caught and logged.

UI Integration¶

UI should depend on:

• IHealthReadonly
• HealthChanged
• Damaged / Healed
• MaxChanged

UI is not coupled to internal fields.

A HealthBarUIConnector component is available for plug-and-play binding.

Design Philosophy¶

Health is:

• Deterministic in ordering
• Composition-first
• Interface-driven
• Explicit about extension seams
• Honest about boundaries

Health is not:

• A netcode framework
• A transaction engine
• A prediction/rollback system
• A persistence manager
• A gameplay logic brain

See Also¶

• Mental Model
• Public API
• System Guarantees Matrix
• Rules
• Shields
• Handlers