❓ FAQ — Health System¶
This FAQ answers integration and decision questions for the Health System.
It does not repeat the README — it clarifies what to use, what not to touch, and where to extend.
If you’re asking “should I do X or Y?”, this is the file you want.
1️⃣ How do I integrate the Health system?¶
Minimal setup (correct path):
1. Add HealthSystem to your GameObject.
2. (Optional) Add:
- Rules (DamageRuleHub, HealRuleHub)
- Shields (CapacityShield, OverhealShield, etc.)
- Handlers (regen, invincibility, death logic)
3. Call damage or healing via the public API:
- ApplyDamage
- TryHeal
- Kill / Revive
That’s it.
No other component is required for Health to function.
2️⃣ What is the correct extension point?¶
This is the most important section.
✅ Use Rules when you want to…¶
- Modify damage or healing math
- Apply crits, armor, affinity, execute logic
- React after damage/heal is applied (POST rules)
✅ Use Shields when you want to…¶
- Intercept damage before it reaches health
- Add capacity, reduction, overheal, or layered defence
- Affect previewed damage correctly
✅ Use Handlers when you want to…¶
- Add gameplay logic (regen, invincibility, extra lives)
- Intercept or control the death pipeline
- Modify lifecycle behaviour
✅ Use Effects / Post Effects when you want to…¶
- Play VFX / SFX
- Show feedback
- React visually to damage or death
❌ Do NOT…¶
- Subclass
HealthSystem - Modify Health source files
- Set health values directly
- Bypass
ApplyDamage/TryHeal
If you feel the need to do any of the above, you’re using the wrong extension point.
3️⃣ Can I modify health directly?¶
No.
And you should never need to.
Health mutation must go through:
- ApplyDamage
- TryHeal
- Kill
- Revive
- Writer interface methods (IHealthWriter)
Directly setting values bypasses: - rules - shields - authority - events - death handling
If you want to change how damage behaves, use Rules.
If you want to intercept damage, use Shields.
4️⃣ Can I use this in multiplayer?¶
Yes — with boundaries.
What Health does provide:
- Authority gating via IHealthAuthority
- Deterministic pipelines
- Preview-safe, rule-driven math
What Health does NOT provide: - Networking - Replication - Prediction - Rollback - Ownership models
Your job in multiplayer:
- Enable requireAuthority
- Implement IHealthAuthority
- Perform mutations only on the authoritative side
- Replicate results using your netcode
Health gates mutation.
You handle transport.
5️⃣ Can I replace the UI?¶
Yes — completely.
Health has no UI dependency.
Options:
- Use HealthBarUIConnector as-is
- Write your own UI using:
- IHealthReadonly
- IHealthWriter
- events
- Ignore provided UI entirely
UI is intentionally separate from gameplay logic.
6️⃣ Can I add my own rules / shields / handlers?¶
Yes — that’s the point.
- Custom damage logic → implement
IDamageRule - Custom healing logic → implement
IHealRule - Custom absorption → implement
IShield - Custom lifecycle logic → implement handlers
You never need to modify built-in components.
7️⃣ What should I NOT do?¶
Hard rules:
- ❌ Do not edit
HealthSystem - ❌ Do not bypass rule hubs
- ❌ Do not mutate health directly
- ❌ Do not assume networking
- ❌ Do not mix UI logic into gameplay code
- ❌ Do not encode game-specific logic in Shared or Core layers
Breaking these rules will cause: - bugs - desyncs - broken previews - unfixable support nightmares
8️⃣ Is Health opinionated?¶
On architecture — yes.
On gameplay — no.
Health is opinionated about: - separation of concerns - explicit extension seams - deterministic behaviour
Health is not opinionated about: - combat systems - abilities - RPG vs action design - single-player vs multiplayer
You decide the gameplay.
Health enforces correctness.
9️⃣ Common mistakes & misconceptions¶
-
“I thought Health included combat / abilities”
→ It doesn’t. Health manages state, not combat design. -
“I tried setting health directly and things broke”
→ That’s expected. Use the API. -
“Why doesn’t this replicate automatically?”
→ Because Health is netcode-agnostic by design. -
“Why is my preview wrong?” → One or more shields don’t implement
IShieldPreview, or the behaviour comes from handlers (invincibility, regen), which previews intentionally ignore. -
“Why didn’t my death logic fire?”
→ You likely bypassed the pipeline or cancelled it earlier.
🔟 Is this the right system for me?¶
Health is a good fit if: - You are comfortable with C# scripting - You want deterministic, extensible health logic - You need clean extension points - You don’t want a prefab combat kit
Health is not a good fit if: - You want a no-code solution - You want a full combat framework - You expect automatic multiplayer support
🧭 Decision Table¶
| If you want to… | Use this |
|---|---|
| Modify damage/healing math | Rules |
| Intercept damage | Shields |
| Add regen / invincibility / extra lives | Handlers |
| Play VFX/SFX | Effects / Post Effects |
| Bind UI | UI Connectors |
| Gate multiplayer mutation | Authority |
✅ Final Guidance¶
If you’re ever unsure: - Don’t modify core code - Look for an interface - Add a component - Let the pipeline do its job
That’s how Health is designed to be used.