04 — Regen, IFrames, and Combat State

Goal:
Demonstrate how Health Regeneration, Invincibility Frames (IFrames), and CombatState interact dynamically to create reactive combat behaviour.

---

🎓 What This Scene Teaches

• How to configure automatic regeneration that pauses under damage or invulnerability.
• How IFrames prevent damage temporarily after a hit or during dodges.
• How CombatState changes based on player health (active, wounded, dead).
• How these systems communicate via shared events and handlers.

---

🧩 What’s in This Scene

Object	Description
Player Capsule	Contains HealthSystem with regen and IFrame logic.
Enemy Capsule	Has HealthSystem + DebugUI and can apply test hits.
CombatState	Tracks player state transitions (healthy, injured, dead) and interacts with combat ability logic.

---

⚙️ Components & Features

Component	Role
HealthSystem	Core component managing HP, regeneration, and damage handling.
HealthRegenerationHandler	Gradually restores health over time if not recently damaged.
HealthInvincibilityHandler	Applies temporary invulnerability (“IFrames”) after taking damage.
CombatState	Manages player states (Active, Injured, Dead) and gates ability access.
DebugUI	Provides test controls to apply damage and observe transitions.

---

⚠️ Authority Note
This scene runs with Require Authority disabled by default.
Health mutations are allowed locally for demonstration purposes.

Enabling an authority binder alone will not block mutations unless
Require Authority is enabled on the HealthSystem — this is intentional.

Why Health works this way:
https://revandrab.github.io/RevFramework/authority/#health-opt-in-authority-gameplay-state

---

🕹️ How to Use

1. Press Play.
2. Observe the Player Capsule:
3. Health automatically regenerates while not damaged or invulnerable.
4. Applying damage pauses regen and triggers IFrames.
5. Open the DebugUI (F9) for more control:
6. Use Apply Hit to test different damage values.
7. Adjust regen rates and IFrame durations live to see their effects.
8. Watch CombatState transitions:
9. Full HP → Active (can attack)
10. Damaged → Wounded / In IFrames (restricted)
11. 0 HP → Dead (combat disabled)

---

💡 Key Concepts

• Health Regeneration:
  Controlled by HealthRegenerationHandler.
  Automatically resumes when the player is safe (no recent damage, no IFrames).

• Invincibility Frames (IFrames):
  Trigger after taking damage or dodging.
  The player becomes immune to further damage until the timer expires.

• Combat State:
  Reacts dynamically to health changes:
  disables combat actions when injured or dead, then re-enables on recovery.

---

⚙️ Key Interactions

Interaction	Behaviour
Damage → IFrames	Triggers temporary invulnerability. Further hits are ignored until IFrames expire.
Regen → Interrupted	Regeneration halts during IFrames or while taking damage.
CombatState → Gating	Abilities are gated or disabled based on current state.
Adjustables	Tweak regen rate, delay, or IFrame duration in the overlay to test balance.

---

🧩 Demo Notes

• The demo panel may auto-add missing handlers (e.g., HealthRegenerationHandler, HealthInvincibilityHandler) to keep the scene functional.
  In production, add and configure these components manually.

• No HUD or UI is required — only the DebugUI is used for this scene.
  The system is fully UI-agnostic and can integrate with any health bar or combat framework.

---

🧱 Debug vs Production

• The IMGUI panel and DebugUI are development tools only.
• For shipping games, implement your own UI and trigger regen/IFrames contextually through gameplay logic.

---

✅ Key Takeaway

This scene demonstrates how regeneration, IFrames, and CombatState work together to form a living, reactive health loop.
Damage interrupts regen, IFrames prevent spam hits, and CombatState ensures abilities respond intelligently to the player’s condition.