🔌 Health Extensions¶

📦 Folder Overview¶

This folder contains convenience APIs built on top of the Health abstractions.

Currently includes:

DamageExtensions

These are ergonomic helpers, not core contracts.

🎯 Purpose¶

Extensions exist to:

Reduce boilerplate when applying damage
Provide common overloads for gameplay scenarios
Keep call-sites clean and readable

They are optional and sit on top of:

IHealthMutator
DamageContext

🧩 What Lives Here¶

`DamageExtensions`¶

Provides GameObject extension methods for applying damage to targets exposing IHealthMutator.

⚠️ Important Notes¶

API Styles¶

Result-based (preferred)

DamageResult DealDamageResult(...)

Returns full DamageResult
Suitable for UI, gameplay logic, and telemetry

Bool wrappers

bool DealDamage(...)

Returns DamageResult.Applied
Lightweight usage

Context Variants¶

Supports multiple usage patterns:

Basic damage
Full metadata (hit point, direction, impulse, sourceId, etc.)
RaycastHit-based impacts
Prebuilt DamageContext
True damage (bypass shields)

Combat Ping Integration¶

Most overloads call:

CombatPing.EnterOnOutgoingAttempt(attacker);

This signals outgoing combat state.

Exception:

DealDamageNoCombat(...)

Does not trigger combat ping
Intended for background or non-combat damage

Team ID Inference¶

If DamageContext.TeamId == 0:

Attempts to resolve from TeamProvider on attacker
Falls back to 0 if not found

Behaviour¶

If the victim does not expose IHealthMutator:
Result APIs return a rejected result
Bool APIs return false
These helpers:
Run the damage pipeline
Do not bypass rules unless explicitly configured

Boundaries¶

Extensions should not:

Introduce gameplay rules
Replace core APIs
Be required for system correctness
Depend on internal HealthSystem implementation details

🧠 Usage Guidance¶

Use extensions for convenience at call sites
Prefer result-based APIs when outcome data is needed
Treat extensions as optional layers on top of core contracts

Mutation (IHealthMutator)
Contracts (DamageContext, DamageResult)
Rules