Limb Health System (LHS) Plugin

1. Overview

The Limb Health System (LHS) plugin provides a comprehensive and data-driven solution for managing detailed character vitality and status. It is responsible for:

• Per-Limb Health & Stamina — Manages distinct health pools for individual limbs and a global stamina pool, integrated directly with GAS attributes.
• Status Effects — Implements a flexible system for applying and managing status effects such as bleeding, fractures, poison, etc., via Gameplay Effects.
• Conditional States — Automatically applies gameplay tags or effects representing conditional states (e.g., "CrippledLeg", "BrokenArm") based on limb health thresholds or active status effects.
• Medical Consumables Framework — Offers a data-driven approach for defining medical items (UMedicalItemDataAsset) that can restore health, remove status effects, and have quality-based efficacy.
• Gameplay Ability System (GAS) Integration — Deeply leverages GAS for all core mechanics, including health/stamina attributes, status and conditional effects, and abilities for medical item usage.

Built on Unreal’s Gameplay Ability System (GAS), LHS works in concert with the Armor System (AS) and Projectile System (PDS). All damage interactions are orchestrated by the central Damage Router Component within the Damage System (DS) plugin, which LHS depends on for core types and damage processing.

Class Diagram

2. Core Features

• Limb-Based Health — Manages distinct health pools for each limb, plus a global health pool, all defined as GAS Attributes.
• Stamina Management — Tracks character stamina, including consumption and regeneration, via GAS Attributes.
• Status Effects Application — Provides a framework for applying and managing status effects (e.g., bleeding, poison, fractures) through Gameplay Effects.
• Conditional States Logic — Automatically applies Gameplay Tags or Gameplay Effects to represent character states (e.g., "CrippledLeg") based on limb health or status effect thresholds.
• Medical Item Framework — Features data-driven UMedicalItemDataAsset for defining medical consumables, including their heal-over-time properties, status effects they remove, and efficacy based on quality.
• Data-Driven Configuration — All core definitions, including limb configurations, conditional states, and medical items, are configured using UDataAsset classes for maximum flexibility.
• Deep GAS Integration — Leverages the Gameplay Ability System for all fundamental mechanics, managing attributes (health, stamina) and effects (status, conditional states) via UAbilitySystemComponent and UCharacterAttributeSet.
• Server-Authoritative Design — Ensures all health, stamina, and status effect calculations and applications are processed on the server with reliable replication to clients.

3. Key C++ Classes & Data Assets

4. Directory Structure

LimbHealthSystem/                   ← Plugin root
└── Source/
    └── LimbHealthSystem/           ← Module root
        ├── LimbHealthSystem.Build.cs
        ├── Public/
        │   ├── ILimbHealthSystemModule.h
        │   ├── LimbSystemTypes.h
        │   ├── CharacterAttributeSet.h
        │   ├── LimbSystemComponent.h
        │   └── MedicalItemDataAsset.h
        └── Private/
            ├── LimbHealthSystemModule.cpp
            ├── CharacterAttributeSet.cpp
            ├── LimbSystemComponent.cpp
            └── MedicalItemDataAsset.cpp

5. Integration Points

5.1 Damage System (DS) Dependency

• Shared Types:

  • Include #include "ItemSystemTypes.h" and #include "DamageSystemTypes.h" from DS for EItemInstanceQuality, FStatModifier, ERoundType, etc.
  • Include #include "MyGameGameplayEffectContext.h" (DS) in CharacterAttributeSet.cpp and LimbSystemComponent.cpp to access the FDamageContext* pointer.

• Damage Routing:

  • UDamageRouterComponent (DS) applies GameplayEffect specs to the LHS’s UAbilitySystemComponent.
  • In UCharacterAttributeSet::PostGameplayEffectExecute, cast the incoming FGameplayEffectContext to FMyGameGameplayEffectContext to update DamageContextBeingProcessed flags (bTargetKilled, ResultingAppliedStatusEffectTags).

5.2 Gameplay Ability System (GAS)

• Attributes: Health and stamina attributes live in UCharacterAttributeSet.
• Effects: Damage, healing, and status changes are applied via UGameplayEffect assets defined in data tables or Blueprints.
• Abilities: Define UGameplayAbility classes for using medical items, triggering regeneration, or clearing conditions.

6. Setup & Usage Notes

1. Component Attachment

   • In your Character class (C++ or Blueprint), add:

     CPPCopy

     UPROPERTY(VisibleAnywhere) UAbilitySystemComponent* AbilitySystemComponent;
     UPROPERTY(VisibleAnywhere) ULimbSystemComponent* LimbSystemComponent;
     UPROPERTY() UCharacterAttributeSet* AttributeSet;
     

2. Initialize GAS & Limbs

   CPPCopy

   // In BeginPlay or OnPossess
   AbilitySystemComponent->InitAbilityActorInfo(this, this);
   AbilitySystemComponent->InitStats(UCharacterAttributeSet::StaticClass(), StatsDataTable);
   LimbSystemComponent->InitializeLimbSystem(LimbDefinitionsDataAsset->Definitions, AbilitySystemComponent);
   

3. Create DataAssets

   • DA_HumanoidLimbs: Array of FLimbDefinition (bone names → limb tags).
   • UMedicalItemDataAsset: Configure EffectsToApply, StatusEffectsToRemove, ApplicationTimeSeconds, and quality tiers.

4. GameplayEffects & Tags

   • Define healing, status, and penalty GEs in Config/DefaultGameplayTags.ini.
   • Reference these in your data assets and abilities.

5. Module Dependencies

   • In LimbHealthSystem.Build.cs, add "DamageSystem" under PublicDependencyModuleNames.
   • In LimbHealthSystem.uplugin, list "DamageSystem" in the "Plugins" array.

6. Include Paths

   • Ensure #include "ItemSystemTypes.h" and #include "MyGameGameplayEffectContext.h" resolve via the DS module’s Public/ directory.