Skip to content

❓ Health System — FAQ

This FAQ answers integration and decision questions about the RevFramework Health System.

If you're unsure where something belongs or how to extend correctly, start here.

🧩 How do I apply damage correctly?

Use the supported mutation APIs.

Convenience usage (HealthSystem wrapper)

health.TryTakeDamage(20);

This is a simple wrapper for quickly sending damage to the host.

var ctx = DamageContext.CreateBasic(attacker, victim, 30, DamageTag.Fire);
health.ApplyDamage(in ctx);

Interface-driven usage

IHealthMutator mutator = ...;
mutator.ApplyDamage(in ctx);

This ensures:

  • PRE rules run
  • Shields intercept (unless BypassShields)
  • Authority gating applies (if enabled)
  • POST observers run
  • Death pipeline executes correctly

💚 How do I apply healing correctly?

Use:

health.TryHeal(amount);
// or
health.Heal(amount);

Healing runs:

  • authority / state checks (including dead check)
  • PRE heal rules
  • heal math evaluation
  • Healing modifiers (IHealingModifier)
  • HP mutation
  • Optional overheal spill into OverhealShield (when enabled)
  • POST heal observers

Do not mutate HP fields directly.

⚰ How do I revive a character?

Use the lifecycle API:

health.Revive();
health.Revive(50);

Revive bypasses the heal rule pipeline entirely.

It may:

  • Trigger invincibility
  • Reset regen
  • Fire revive events

But it does not simulate healing and does not run heal rules or modifiers.

🔄 Can I modify health directly?

Only through supported public APIs:

  • ApplyDamage
  • TryHeal / Heal
  • Kill / Revive
  • SetCurrent / SetMax
  • Snapshot restore (CaptureSnapshot() / RestoreSnapshot() on HealthSystem)

⚠️ Direct mutation APIs bypass the standard damage and healing pipelines.
They should only be used for setup, persistence, or controlled non-combat workflows.

Never modify serialized fields directly.

🛡 How do shields interact with rules?

Order is fixed:

Authority → State Guards → PRE Rules → Damage Evaluation → Shields → HP → POST → Death

Important:

  • Shields are skipped when DamageContext.BypassShields == true
  • PRE rules can bypass rule families via RuleBypass
  • Shields never mutate HP directly
  • POST observers run before death finalization

💥 When should I use Rules vs Shields vs Effects?

Use Rules when you want to:

  • Modify combat math
  • Scale, cancel, clamp, or tag damage/heal
  • Implement crits, executes, resistances, anti-heal

Use POST Rules when you want to:

  • Reflect damage
  • Apply lifesteal
  • Spawn VFX / SFX
  • Trigger secondary effects

Use Shields when you want to:

  • Intercept damage before HP changes
  • Implement capacity shields, regen shields, temp HP

Use Effects when you want to:

  • Apply timed mutation (DOT / HOT)
  • Build gameplay-over-time systems

🌐 How does multiplayer authority work?

Authority is opt-in.

Enable it via:

requireAuthority = true;

Then provide either:

  • SetAuthorityResolver(...)
  • An IHealthAuthority component

Authority:

  • Blocks mutation
  • Raises AuthorityDenied
  • Does not replicate state
  • Does not define ownership
  • Does not provide netcode transport

If authority denies mutation, the pipeline stops immediately and no rules, shields, or state changes occur.

Health guarantees deterministic pipeline ordering but does not provide rollback, prediction, or transactional guarantees.

🔍 How do previews work?

PreviewDamage(...) and PreviewHeal(...):

  • Do not mutate state
  • Do not fire events
  • Do not trigger death

Notes:

  • Damage previews ignore invincibility and damage locks
  • Previews ignore authority checks
  • Shield previews require IShieldPreview for accuracy
  • Preview never consumes shield capacity
  • Preview is an estimate, not a guaranteed final result

🧠 Can POST rules change the outcome?

No — not for the current attempt.

POST observers must not modify the outcome of the current attempt.

They may trigger new damage/heal attempts (e.g., reflect, lifesteal), but those run through a separate pipeline.

🔧 Can I subclass HealthSystem?

Not recommended.

HealthSystem is designed for composition, not inheritance.

Subclassing risks bypassing rule pipelines and breaking guarantees.

Extend via:

  • Rules
  • Shields
  • Handlers
  • Public interfaces

📊 How should I bind UI?

Depend on:

  • IHealthReadonly
  • Normalized01
  • HealthChanged
  • Damaged / Healed
  • MaxChanged

UI should treat HealthSystem as read-only and never trigger mutation.

Do not read or write serialized fields directly.

🧪 Why can preview results differ from actual damage?

Previews estimate outcomes based on rule math and shield previews.

Actual results may differ if:

  • Shields do not implement IShieldPreview
  • External modifiers change between frames
  • Runtime state changes (invincibility, shields, authority)
  • POST effects trigger additional damage or healing

❓ Why did my damage resolve to zero?

Damage may resolve to zero if:

  • PRE rules cancel the context
  • armor or resist rules reduce damage to zero
  • damage was clamped to zero by a rule (e.g., DamageClampRule)
  • shields absorb the entire hit
  • the target is invincible
  • the target is already dead
  • authority blocks the mutation
  • damage locks are active

Check the DamageResult and DamageRejectionReason to understand why a hit was rejected.

🚫 What should I avoid?

  • Mutating HP outside the supported pipeline
  • Embedding gameplay logic into Authority
  • Using POST rules to change math
  • Treating ShieldPool as an actual shield
  • Assuming preview == final result

🔗 See Also

  • Public API
  • Mental Model
  • Rules
  • Shields
  • Handlers