Skip to content

❤️ Health — Documentation Guide

🧭 Where should I start?

🔹 New to Health?

Start with:

👉 System Overview (README + Mental Model)

This explains: - What the Health system is - How the damage and healing pipelines are structured - How Health integrates rules, shields, authority, lifecycle, and UI - Typical setup and usage patterns

🔹 Want to know what you can safely depend on?

Read:

👉 PublicAPI/

This document defines: - The supported runtime surface - Stable interfaces, value types, events, and host APIs - Guaranteed behaviours - Explicitly unsupported usage

If something is not listed there, it is not supported — even if it appears public in code.

This is the contract.

🔹 Adding gameplay or extending the system?

Start with:

👉 Integration Surfaces/

This shows exactly where logic belongs: - damage and heal rules - shields and interception - authority and lifecycle - effects and regeneration - UI and read-only consumers

Then use:

👉 FAQ/

The FAQ answers questions like: - Should this be a rule, shield, effect, or handler? - How do I apply damage or healing correctly? - How does authority work? - What do previews actually mean? - What should I avoid?

It focuses on decision-making, not API reference.

🔹 Need the full damage flow at a glance?

Read:

👉 Damage Pipeline Diagram/

This gives you the visual order of operations:

  • Authority / guards
  • PRE rules
  • damage evaluation
  • shields
  • HP mutation
  • POST observers
  • death handling

Use it when you want the shortest possible explanation of how Health actually executes.

🧠 How these documents work together

Document Purpose
Overview Explains the system
Public API Defines what is supported
FAQ Guides correct usage choices
Integration Surfaces Shows where new logic should plug in
Mental Model Explains how to think about the system
Damage Pipeline Diagram Shows exact execution order visually
Guarantees Matrix Defines behavioural contracts

Each document serves a specific purpose.
You do not need to read everything — start with what matches your task.

🛑 Important support note

RevFramework Health is:

  • Component-driven
  • Interface-first
  • Pipeline-based
  • Authority-aware
  • Event-driven
  • UI-agnostic
  • Netcode-agnostic

Support is provided for:

  • Behaviour defined in PublicAPI
  • Usage patterns described in Overview, FAQ, Integration Surfaces, and the Damage Pipeline Diagram
  • Guarantees listed in the Guarantees Matrix

Support is not provided for:

  • Mutating HP outside the supported public APIs
  • Depending on undocumented pipeline behaviour
  • Reflecting into runtime internals
  • Treating preview APIs as guaranteed final outcomes
  • Using subclassing to replace supported composition seams

  • Teaching Panels
    Add debug or teachable panels to inspect health, rules, shields, and lifecycle behaviour live

  • Samples
    See /Samples/Health/ for runnable examples

  • MkDocs site
    Mirrors this documentation for web browsing

🧠 System philosophy

Health is:

  • A host-owned HP pipeline (not free-form field mutation)
  • A composition-first system (rules, shields, handlers, effects)
  • A result-first mutation model (explicit damage/heal outcomes)
  • A read/write separation model (IHealthReadonly for consumers, mutation through supported seams)

Every public extension seam exists for a reason.
If something feels unclear, you're likely using the wrong layer.

✅ TL;DR

  • Want to understand Health → Overview
  • Want to see the true order → Damage Pipeline Diagram
  • Want to build safely → Public API
  • Want to choose correctly → FAQ
  • Want to extend cleanly → Integration Surfaces

If you stay within these boundaries, Health will behave predictably and remain supportable.