Damage System (DS) Plugin

1. Overview

The Damage System (DS) plugin is the foundational utility layer for orchestrating all damage events and exposing shared core types to the gameplay ecosystem. It provides:

  • FDamageContext: A mutable struct carrying every piece of data for a damage event.
  • UDamageRouterComponent: An actor component that drives the ordered pipeline:
    1. Projectile Impact
    2. Armor Mitigation
    3. Health Application & Status Effects
    4. Outcome Broadcasting (GameplayCues)
  • Shared Core Types: Centralized enums and structs previously scattered across PDS, AS, and LHS.

All processing is server-authoritative, and the module is designed for extensibility, allowing insertion of global modifiers or custom routing steps.

Class Diagram

2. Core Features

  • Centralized Damage Data
    • FDamageContext encapsulates source, target, projectile data, armor results, health results, and outcome flags.
  • Ordered Processing
    • UDamageRouterComponent::ProcessDamageEvent() enforces a consistent flow across all subsystems.
  • Decoupling
    • PDS, AS, and LHS only depend on DS’s shared types and routing API—no direct inter-plugin dependencies.
  • Shared Core Types
    • DamageSystemTypes.h:
      • FDamageContext
      • ERoundType
      • EProjectileType
    • ItemSystemTypes.h:
      • EItemInstanceQuality
      • EStatModificationOperand
      • FStatModifier
      • FQualityModifierSet
      • FItemQualityModifierMapping
    • MyGameGameplayEffectContext.h:
      • FMyGameGameplayEffectContext (extends FGameplayEffectContext with FDamageContext* and HitLimbTag)
  • Extensibility
    • Hooks for global modifiers or custom routing stages can be inserted in the router component.

3. Key C++ Classes & Data Structures

TypeLocationPurpose
FDamageContextDamageSystemTypes.hCarries all data for a damage event, including projectile info, armor results, and health outcomes.
ERoundType, EProjectileTypeDamageSystemTypes.hEnumerations for round and projectile behavior (moved from PDS).
EItemInstanceQuality,ItemSystemTypes.hItem/armor quality enums (moved from AS).
FStatModifier, FQualityModifierSet,FItemQualityModifierMappingItemSystemTypes.hStructures for quality-based stat adjustments.
FMyGameGameplayEffectContextMyGameGameplayEffectContext.hCustom GE context holding a pointer to the active FDamageContext.
UDamageRouterComponentDamageRouterComponent.h/.cppDrives the damage pipeline; calls into PDS, AS, and LHS in order, then broadcasts outcomes.

Module Files:

  • IDamageSystemModule.h
  • DamageSystemModule.cpp
  • DamageSystem.Build.cs

4. Directory Structure

TEXT
DamageSystem/                          ← Plugin root
└── Source/
    └── DamageSystem/                 ← Module root
        ├── DamageSystem.Build.cs
        ├── Public/
        │   ├── IDamageSystemModule.h
        │   ├── DamageSystemTypes.h
        │   ├── ItemSystemTypes.h
        │   ├── MyGameGameplayEffectContext.h
        │   └── DamageRouterComponent.h
        └── Private/
            ├── DamageSystemModule.cpp
            ├── MyGameGameplayEffectContext.cpp
            └── DamageRouterComponent.cpp

5. Integration Points

  1. Provider of Core Types

    • LHS, AS, and PDS add DX’s plugin as a dependency to consume:

      • FDamageContext, ERoundType, EProjectileType
      • EItemInstanceQuality, FStatModifier, etc.
      • FMyGameGameplayEffectContext

  2. Orchestrator of Damage Flow

    • Damage Sources (PDS, melee, hazards) populate FDamageContext and call:

      CPP
      Target->FindComponentByClass<UDamageRouterComponent>()->ProcessDamageEvent(Context);

    • Armor Mitigation:

      CPP
      ArmorComponent->ProcessDamageInteraction(Context, HitLimbTag, HitBoneName);

    • Health & Effects:

      CPP
      UDamageRouterComponent::ProcessHealthAndEffects(Context);
// Creates and applies a GameplayEffect using Context.DirectDamageEffectClassToApply

    • Outcome Broadcasting:

      CPP
      UDamageRouterComponent::BroadcastPostDamageOutcomes(Context);
// Triggers GameplayCues based on flags in Context

  3. GameplayCue System

    • Uses final state in FDamageContext to emit cues (e.g., Damage.Hit, Damage.ArmorPenetrated, Damage.Killed).

6. Setup & Usage Notes

  • Module Dependencies

    • In LimbHealthSystem.Build.cs, ArmorSystem.Build.cs, and ProjectileSystem.Build.cs, add "DamageSystem" to their PublicDependencyModuleNames.
    • In each plugin’s .uplugin, list "DamageSystem" under "Plugins".

  • Attach Router

    • Add UDamageRouterComponent to any actor class that should receive routed damage.

  • Populate & Dispatch

    • All damage-dealing code must populate FDamageContext (from DamageSystemTypes.h) and call ProcessDamageEvent() on the router.

  • GameplayEffect Requirements

    • Effects referenced by Context.DirectDamageEffectClassToApply must implement an ExecutionCalculation that:

      1. Retrieves FMyGameGameplayEffectContext.
      2. Reads the SetByCaller "Data.Damage".
      3. Applies damage to the correct limb attribute based on HitLimbTag.

  • Extending the Router

    • You can subclass UDamageRouterComponent or bind to its events to insert custom stages (e.g., world effects, AI reactions).