Skip to content

🔌 Health System — Integration Surfaces

This page explains where new gameplay logic should integrate with the RevFramework Health system.

If you're adding a new mechanic, start here.

The Health architecture is intentionally modular. Each gameplay behaviour belongs to a specific extension surface. Choosing the correct surface keeps systems predictable, maintainable, and compatible with the rest of the framework.

🧠 Extension Surfaces Overview

Goal Extension Point Example
Modify damage calculation PRE Damage Rule (IDamageRule) armor, crit, execute
Modify healing calculation PRE Heal Rule (IHealRule) anti-heal, low HP boost
React to finalized damage POST Damage Rule (IPostDamageRule) lifesteal, reflect, VFX
React to finalized healing POST Heal Rule (IPostHealRule) SFX, UI
Intercept damage before HP Shield (IShield) barrier, temp HP
Timed mutation Effects (DotEffect, HotEffect) poison DOT, regen HOT
Block mutation entirely Authority (IHealthAuthority) server authority
Extend lifecycle behavior Handlers (IBeforeDeathHandler, IHealthDeathHandler) extra lives, revive logic, death effects
Direct HP mutation HealthSystem APIs (IHealthWriter, lifecycle APIs) setup, persistence, debugging
Read health state IHealthReadonly UI, AI checks

⚙ Example Decision Flow

Critical Hits

Use:

IDamageRule

Critical hits modify the damage calculation, so they belong in the PRE rule pipeline.

Fire Damage Over Time

Use:

DotEffect

DOT is time-based mutation, which is exactly what Effects are designed for.

Temporary Barrier / Temporary HP

Use:

CapacityShield
RechargeableShield
OverhealShield

These intercept damage before it reaches HP or provide temporary HP buffers.

Lifesteal

Use:

IPostDamageRule

Lifesteal reacts to final damage applied, not the math before it.

Regeneration

Use:

HealthRegenerationHandler

Regen is a companion system that coordinates healing over time.

Multiplayer Authority

Use:

IHealthAuthority

Authority determines whether mutation is allowed, not how damage is calculated.
It does not modify damage values or healing behaviour.

UI Health Bars

Depend on:

IHealthReadonly

UI should read health state but never mutate it.

🛡 Rules vs Shields

Rules modify damage calculation.

Shields modify damage interception.

Rules operate before shields.
Shields operate after rules but before health mutation.

Behaviour Implementation
Resistance Rule
Crit Rule
Execute Rule
Damage cap Rule
Reflect POST Rule
Capacity barrier Shield
Temporary HP Shield

💥 Effects vs Rules

Effects are time-based gameplay decorators.

Rules are instantaneous calculation modifiers.

Effects apply repeated mutation over time using the same public mutation surfaces (IHealthMutator, IHealthWriter).

Behaviour Correct Surface
Poison DOT DotEffect
Regeneration HOT HotEffect
Burn damage scaling IDamageRule
Anti-heal debuff IHealRule

⚠ Common Mistakes

Avoid the following:

  • Mutating Current or Max directly
  • Calling internal methods instead of public APIs
  • Embedding combat logic inside Authority
  • Using POST rules to change damage math (POST rules must not mutate core damage calculation)
  • Treating ShieldPool as an absorbing shield (it does not intercept damage)

🧩 Architecture Summary

Damage Attempt
     ↓
Authority Gate
     ↓
State Guards (Dead / Invincible / Damage Locked)
     ↓
PRE Rules
     ↓
Damage Evaluation (raw → multiplier → flat)
     ↓
Shield Absorption
     ↓
HP Mutation
     ↓
POST Observers
     ↓
Death Interception (IBeforeDeathHandler)
     ↓
Death Finalization (IHealthDeathHandler + events)

Every extension surface plugs into one of these stages.

⚠ Direct Mutation Warning

Direct mutation APIs (e.g. SetCurrent, SetMax, snapshot restore) bypass the standard damage and healing pipelines.

They should only be used for:

  • setup
  • persistence
  • controlled non-combat workflows

🔗 Related Docs

  • Mental Model
  • Public API
  • System Guarantees Matrix
  • FAQ