Projectile System (PDS) Plugin

1. Overview

The Projectile System (PDS) plugin manages the creation, simulation, and impact processing of all projectile types in your FPS game. It handles:

• Projectile Movement & Collision — Manages instantaneous hitscan traces or physically simulated projectiles via UProjectileMovementComponent.
• Damage Calculation & Effects — Populates FDamageContext (from DS) and invokes the central damage pipeline.
• Advanced Ballistics — Includes features for ricochet, spall generation, environmental penetration, and configurable fragmentation.
• Object Pooling (Recommended) — Designed for reuse of ABaseProjectile instances to minimize runtime allocation and improve performance.
• Server-Authoritative Replication — Ensures all spawn, movement, and hit logic runs on the server, with clients receiving cosmetic updates.

This plugin is standalone but depends on the Damage System (DS) for core types and orchestration, and integrates upstream with the Armor System (AS) and Limb Health System (LHS).

Class Diagram

2. Core Features

• Diverse Projectile Types — Supports multiple projectile behaviors.
  • Hitscan for instantaneous impacts.
  • PhysicalBullet with simulated mass, drag, and gravity.
  • Extendable for Grenade, Rocket, etc., via EProjectileType (from DS).
• Varied Round Types — Allows definition of different ammunition characteristics.
  • Supports FMJ, AP, HP, Incendiary, etc., via ERoundType (from DS).
  • Round type governs penetration capabilities, damage output, and special on-hit effects.
• Data-Driven Archetypes — Projectile behaviors are defined in Data Assets.
  • UProjectileArchetypeDataAsset defines all behavior: velocity, mass, caliber, round type, damage, and VFX/SFX.
• Advanced Ballistics Simulation — Provides options for complex projectile interactions.
  • Ricochet: Configurable bounce probability and angle via FProjectileRicochetConfig.
  • Spall: Secondary fragment generation on impact, defined in FProjectileSpallConfig.
  • Penetration: Multi-surface penetration logic based on material resistance.
  • Fragmentation: Allows for configurable sub-munition spawning on impact.
• Damage & GameplayEffects Integration — Seamlessly works with the Damage System and GAS.
  • On impact, PDS fills the FDamageContext (from DS) and calls UDamageRouterComponent::ProcessDamageEvent().
  • Uses DirectDamageEffectClassToApply from the projectile archetype to apply damage via Gameplay Effects.
• Object Pooling Support — Designed with performance in mind.
  • Supports efficient reuse of ABaseProjectile actors to reduce garbage collection overhead and improve runtime performance.

3. Key C++ Classes & Data Assets

Module Files:

• IProjectileSystemModule.h — public interface
• ProjectileSystemModule.cpp — module startup/shutdown
• ProjectileSystem.Build.cs — declares dependency on "DamageSystem"

4. Directory Structure

ProjectileSystem/                     ← Plugin root
└── Source/
    └── ProjectileSystem/            ← Module root
        ├── ProjectileSystem.Build.cs
        ├── Public/
        │   ├── IProjectileSystemModule.h
        │   ├── ProjectileSystemTypes.h    ← includes DS’s DamageSystemTypes.h
        │   ├── ProjectileArchetypeDataAsset.h
        │   └── ABaseProjectile.h
        └── Private/
            ├── ProjectileSystemModule.cpp
            ├── ProjectileArchetypeDataAsset.cpp
            └── ABaseProjectile.cpp

Note: ERoundType, EProjectileType, FDamageContext, and ItemSystemTypes.h are now defined in the DamageSystem plugin.

5. Integration Points

1. Damage System (DS)

   • Dependencies:

     • DamageSystemTypes.h for FDamageContext, ERoundType, EProjectileType.
     • ItemSystemTypes.h for ammo quality.

   • Workflow:

     CPPCopy

     // In ABaseProjectile::ProcessImpact or hitscan handler
     FDamageContext Ctx;
     // Populate from archetype & hit:
     Ctx.ProjectileMassKg         = Archetype->MassKg;
     Ctx.ProjectileCaliberMm      = Archetype->CaliberMm;
     Ctx.ProjectileRoundType      = Archetype->RoundType;
     Ctx.ProjectileBehaviorType   = Archetype->ProjectileBehaviorType;
     Ctx.InitialDamagePotential   = Archetype->BaseDamageAmount;
     Ctx.DirectDamageEffectClassToApply = Archetype->DirectDamageGameplayEffectClass;
     Ctx.HitLimbTag               = HitLimbTag;
     Ctx.CurrentDamageToApply     = Ctx.InitialDamagePotential;
     // …other fields…
     TargetActor->FindComponentByClass<UDamageRouterComponent>()->ProcessDamageEvent(Ctx);
     

2. Armor System (AS)

   • Receives the same FDamageContext for mitigation in ProcessDamageInteraction().

3. Limb Health System (LHS)

   • Final damage and status effects are applied to limb attributes via GAS using the populated context.

4. External Weapon System

   • Selects the appropriate UProjectileArchetypeDataAsset and spawns or traces with the configured parameters.

6. Setup & Usage Notes

1. Create Archetypes

   • Define UProjectileArchetypeDataAsset instances for each ammo/projectile type.
   • Use DS enums (ERoundType, EProjectileType) and quality types.

2. Object Pooling

   • Implement a pool for ABaseProjectile to Spawn/Despawn rather than New/Destroy.

3. Hitscan Logic

   • On server, perform line trace, then populate and dispatch FDamageContext as above.

4. Build Dependencies

   • In ProjectileSystem.Build.cs, include:

     CSHARPCopy

     PublicDependencyModuleNames.AddRange(new string[]{
         "Core", "CoreUObject", "Engine",
         "GameplayTags", "GameplayAbilities",
         "DamageSystem"
     });
     

5. Include Paths

   • In your PDS headers:

     CPPCopy

     #include "DamageSystemTypes.h"     // for FDamageContext, ERoundType, EProjectileType
     #include "ItemSystemTypes.h"       // for ammo quality mappings
     

6. Define Direct Damage GE

   • Ensure each archetype sets DirectDamageGameplayEffectClass to a valid UGameplayEffect that reads "Data.Damage" from the context.