Skip to content

01_RulesBasicsTags — Rules Basics & Tags

Goal

Teach how raw damage and hit tags flow through pre-shield damage rules before damage is applied.

What This Scene Demonstrates

Amount + tags → ArmorRule → Affinity providers → PreviewDamage → ApplyDamage.

This scene focuses on the first layer of the Health damage rule flow: tags, armor, and affinity. Tags do not deal damage by themselves. Tags describe the hit so rules can decide whether they contribute.

The hand breakdown is a teaching aid. HealthSystem.PreviewDamage(includeShields:false) is the authoritative rules preview, and HealthSystem.ApplyDamage is the authoritative runtime result.

What To Look For

  • Setup: The panel binds an optional attacker and a victim with HealthSystem.
  • Inputs: Amount defines the raw hit value. Tags describe the hit type.
  • Armor: ArmorRule contributes only when the selected tags intersect its affected mask.
  • Affinity: Affinity providers return per-tag multipliers. Matching multipliers combine into one product.
  • Preview: The simplified breakdown shows Armor + Affinity math, while engine preview shows the real rule result.
  • Apply: The same hit is sent through HealthSystem.ApplyDamage and reports the real applied result or rejection reason.

Mental model: raw amount + tags → rule evaluation → authoritative preview → authoritative apply result.

Sample Scope

This scene covers:

  • Raw damage amount
  • Hit tags: Melee, Ranged, Fire, Poison
  • ArmorRule flat reduction and percent reduction
  • IDamageAffinity provider multipliers
  • Rules-only preview with shields excluded
  • Real damage application through HealthSystem.ApplyDamage
  • Optional shield bypass on apply for rules-only comparison

This scene does NOT cover:

  • Shield behaviour as the main teaching focus
  • Death handling
  • Regeneration
  • Full combat flow
  • Networking implementation
  • Every possible custom damage rule

The simplified breakdown only models Armor + Affinity. If other damage rules are present, the hand breakdown and engine preview may differ. That is expected; the service result is truth.

Authority Note

This scene may include a permissive sample authority setup where mutations are allowed locally for demonstration purposes.

Networking Reminder

No networking is included; integration is the developer’s responsibility.

How To Use

  1. Enter Play Mode.
  2. Open the Setup tab.

  3. Confirm the panel has:

  4. an optional Attacker binding

  5. a Victim binding with HealthSystem
  6. optional ArmorRule
  7. optional affinity providers
  8. Set Amount to the raw damage value.

  9. Select one or more tags:

  10. Melee

  11. Ranged
  12. Fire
  13. Poison
  14. Use Bypass shields on Apply (rules-only) if you want apply behaviour to stay focused on rules.
  15. Open the Preview tab.

  16. Compare:

  17. raw amount

  18. armor contribution
  19. affinity contribution
  20. authoritative engine preview
  21. Open the Apply tab.
  22. Click Apply Hit to send the hit through HealthSystem.ApplyDamage.
  23. Read the result message to see whether damage was applied or rejected.
  24. Use Clear Tags to remove all tags.
  25. Use Melee+Fire / Ranged+Poison to toggle between the preset tag combinations.

Failure Behaviour

  • Missing Victim

  • Meaning: No victim GameObject is assigned.

  • Fix: Assign a victim GameObject with HealthSystem.

  • Missing HealthSystem

  • Meaning: The selected victim cannot preview or apply damage.

  • Fix: Add HealthSystem to the victim or choose a different victim.

  • No Focus Rules Found

  • Meaning: No ArmorRule or affinity provider was found.

  • Fix: Add ArmorRule or an IDamageAffinity provider to see rule contribution.

  • Zero Damage

  • Meaning: Amount is zero, so the hit will be rejected or reduced to nothing.

  • Fix: Set Amount above 0.

  • No Tags Selected

  • Meaning: Untagged hits are valid, but tag-based armor masks and affinity lookups may not contribute.

  • Fix: Select Melee, Ranged, Fire, or Poison if you want tag-based rules to respond.

  • Preview Blocked

  • Meaning: Preview needs a victim with HealthSystem.

  • Fix: Return to Setup and assign a valid victim.

  • Apply Requires Play Mode

  • Meaning: Apply mutates runtime health state and is disabled outside Play Mode.

  • Fix: Enter Play Mode.

  • Target Is Dead

  • Meaning: ApplyDamage will reject the hit because the victim is already dead.

  • Fix: Revive or reset the victim before applying damage.

  • AuthorityBlocked

  • Meaning: The hit was blocked by authority policy.

  • Fix: Check the health authority policy or run the hit from an allowed authority path.

  • Invincible

  • Meaning: The hit was blocked by invincibility.

  • Fix: Wait for i-frames to expire or disable the invincibility source.

  • DamageLocked

  • Meaning: Damage is currently locked.

  • Fix: Unlock damage or inspect the component/rule that enabled the lock.

  • TargetIsDead

  • Meaning: The victim is already dead.

  • Fix: Revive or reset the victim.

  • AbsorbedByShield

  • Meaning: A shield fully absorbed the hit.

  • Fix: Bypass shields for a rules-only test, reduce shield strength, or apply a larger hit.

  • ZeroOrNegativeAmount

  • Meaning: Rules reduced the hit to zero.

  • Fix: Increase Amount, change tags, or inspect Armor/Affinity multipliers.

Behind The Scenes

  • HealthSystem — previews and applies damage
  • DamageContext — carries attacker, victim, amount, tags, and shield bypass state
  • DamageTag — describes the hit type
  • ArmorRule — applies flat reduction first, then percent reduction when tags match its affected mask
  • IDamageAffinity — provides per-tag damage multipliers
  • AffinityRule — focus rule for affinity-based contribution
  • IDamageRule — used to detect additional damage rules on the victim
  • IShield — used only to detect shield presence when shields are enabled on apply
  • HealthSystem.PreviewDamage(in ctx, includeShields:false) — authoritative no-shield preview
  • HealthSystem.ApplyDamage(in ctx) — authoritative runtime mutation result

The panel does not access internals, use reflection, or fake rule behaviour.

Key Takeaway

Tags describe the hit. Rules decide whether those tags matter.

Armor and affinity can shape damage before it reaches health, but PreviewDamage and ApplyDamage remain the source of truth.

The simplified breakdown teaches the flow; the Health service owns the real result.