Skip to content

❤️ Pickups → Health Integration

This folder provides optional integration bridges between the Pickups system and the RevFramework Health system.

It allows pickup effects and decorators to interact with health-related surfaces such as:

  • Immediate healing
  • Regeneration over time
  • Health-based conditional gating
  • Alive/dead checks
  • Temporary shield application

👉 This keeps the Pickups system decoupled from Health while still allowing richer behaviour when Health is present.

This integration is built and supported for RevFramework systems only.
It is not intended as a general integration layer for third-party health systems.

🧠 What This Integration Does

This integration adds Health-aware pickup behaviour such as:

  • InstantHealEffect → restores health immediately
  • RegenOverTimeEffect → applies healing over time
  • ConditionalHealthPercentDecorator → only allows the wrapped effect when health is below a threshold
  • HealthAliveGateDecorator → blocks the wrapped effect when the target is dead
  • TempShieldIntegration → applies temporary shield points through the built-in Health shield implementation

These features live outside the core Pickups assembly so Pickups remains safe to delete without taking Health with it.

🔧 How It Works

Health Effects

Health-specific pickup definitions create Health-specific effects:

  • InstantHealPickupDefinition → InstantHealEffect
  • RegenPickupDefinition → RegenOverTimeEffect

These effects require a compatible Health surface such as:

  • IHealthWriter
  • IHealthReadonly

If the required Health interface is not present, the effect simply no-ops.

Health Decorators

This integration also adds optional decorators that wrap normal pickup effects:

  • Conditional Health Percent
    Only allows the wrapped effect when normalized health is below a configured threshold.

  • Alive Gate
    Cancels the wrapped effect when the target exposes IHealthReadonly and is dead.

These decorators exist in the Health integration assembly so the core Pickups system does not need a hard dependency on Health.

Health-Aware Factory Entry Point

PickupEffectFactoryHealthIntegration provides an explicit opt-in entry point for building pickup effects with optional Health gating.

This is important:

  • It does not modify PickupEffectFactory globally
  • Health conditional wrapping only happens when callers use the Health integration entry point explicitly

👉 In other words, Health integration is opt-in, not automatic magic.

⚠️ Important

This is optional

  • Pickups do not require Health
  • This folder only matters if you want pickups to interact with Health concepts

No global override

  • The core Pickups factory remains unchanged
  • Health-aware wrapping must be requested explicitly
  • Removing this folder does not affect normal pickup behaviour

Behaviour depends on Health surfaces

These integrations only work when the target exposes the expected interfaces or built-in components.

Examples:

  • InstantHealEffect requires IHealthWriter
  • ConditionalHealthPercentDecorator requires IHealthReadonly
  • TempShieldIntegration targets the built-in OverhealShield

If those surfaces are absent, the integration either no-ops or fails the condition.

🧪 Example Usage

Example 1 — Instant Heal Pickup

  1. Create an InstantHealPickupDefinition
  2. Set healAmount
  3. Assign it to a pickup
  4. Consume the pickup with a target that exposes IHealthWriter

👉 The target is healed immediately.

Example 2 — Regen Pickup

  1. Create a RegenPickupDefinition

  2. Set:

  3. regenAmount

  4. duration

  5. tickInterval

  6. Assign it to a pickup

  7. Consume the pickup with a target that exposes IHealthWriter

👉 The target receives healing over time.

Example 3 — Health-Conditional Effect

  1. Enable condRequireBelowHealthPercent on a pickup definition
  2. Set condHealthPercentThreshold
  3. Build the effect through PickupEffectFactoryHealthIntegration

👉 The final effect chain is wrapped in a Health-percent gate.

🧠 Design Intent

This integration demonstrates:

  • How Pickups can interact with other RevFramework systems without hard coupling
  • How optional decorators can live outside the core system
  • How integrations can extend behaviour without overriding the default runtime path

The goal is modularity, not lock-in.

🌍 Third-Party / Custom System Use

This integration is built for RevFramework Health systems only.

If you are using a different health system:

  • Treat this as a reference example
  • Implement your own pickup effects or decorators
  • Use your own service layer

👉 Custom or third-party health integrations are not supported by this layer.

🧹 Safe to Remove

This folder is completely optional.

Removing it will:

  • Not affect the Pickups runtime system
  • Not break non-Health pickups
  • Only remove Health-specific pickup behaviour

🧠 Summary

This integration answers:

“How can pickups interact with Health without making Pickups depend on Health?”

It provides:

  • Optional healing and regen pickup effects
  • Health-aware decorators
  • Explicit opt-in Health wrapping
  • A clear integration pattern

Use it as a reference, extend it, or remove it entirely.